2 files changed, 260 insertions, 0 deletions
diff --git a/docs/licenses/ip_associations_python_novaclient_ext.txt b/docs/licenses/ip_associations_python_novaclient_ext.txt
new file mode 100644
index 0000000000..137069b823
--- /dev/null
+++ b/docs/licenses/ip_associations_python_novaclient_ext.txt
@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/docs/notification_system.md b/docs/notification_system.md
new file mode 100644
index 0000000000..fc8f99b9ee
--- /dev/null
+++ b/docs/notification_system.md
@@ -0,0 +1,187 @@
+Completion pending unit tests and acceptance info and instructions.  The following documentation will likely be moved to the feature epic card and reproduced in our development documentation.
+
+# Notification System Overview
+
+A Notifier is an instance of a notification type (Email, Slack, Webhook, etc) with a name, description, and a defined configuration (A few examples: Username, password, server, recipients for the Email type.  Token and list of channels for Slack.  Url and Headers for webhooks)
+
+A Notification is a manifestation of the Notifier... for example, when a job fails a notification is sent using the configuration defined by the Notifier.
+
+This PR implements the Notification system as outlined in the 3.0 Notifications spec.  At a high level the typical flow is:
+
+* User creates a Notifier at `/api/v1/notifiers`
+* User assigns the notifier to any of the various objects that support it (all variants of job templates as well as organizations and projects) and at the appropriate trigger level for which they want the notification (error, success, or any).   For example a user may wish to assign a particular Notifier to trigger when `Job Template 1` fails.   In which case they will associate the notifier with the job template at `/api/v1/job_templates/n/notifiers_error`.
+
+## Notifier hierarchy
+
+Notifiers assigned at certain levels will inherit notifiers defined on parent objects as such:
+
+* Job Templates will use notifiers defined on it as well as inheriting notifiers from the Project used by the Job Template and from the Organization that it is listed under (via the Project).
+* Project Updates will use notifiers defined on the project and will inherit notifiers from the Organization associated with it.
+* Inventory Updates will use notifiers defined on the Organization that it is listed under
+* Ad-hoc commands will use notifiers defined on the Organization that the inventory is associated with
+
+## Workflow
+
+When a job succeeds or fails, the error or success handler will pull a list of relevant notifiers using the procedure defined above.  It will then create a Notification object for each one containing relevant details about the job and then **send**s it to the destination (email addresses, slack channel(s), sms numbers, etc).    These Notification objects are available as related resources on job types (jobs, inventory updates, project updates), and also at `/api/v1/notifications`.   You may also see what notifications have been sent from a notifier by examining its related resources.
+
+Notifications can succeed or fail but that will not cause its associated job to succeed or fail.   The status of the notification can be viewed at its detail endpoint `/api/v1/notifications/<n>`
+
+## Testing Notifiers before using them
+
+Once a Notifier is created its configuration can be tested by utilizing the endpoint at `/api/v1/notifiers/<n>/test`   This will emit a test notification given the configuration defined by the Notifier.  These test notifications will also appear in the notifications list at `/api/v1/notifications`
+
+# Notification Types
+
+The currently defined Notification Types are:
+
+* Email
+* Slack
+* Hipchat
+* Pagerduty
+* Twilio
+* IRC
+* Webhook
+
+Each of these have their own configuration and behavioral semantics and testing them may need to be approached in different ways.   The following sections will give as much detail as possible.
+
+## Email
+
+The email notification type supports a wide variety of smtp servers and has support for ssl/tls connections.
+
+### Testing considerations
+
+The following should be performed for good acceptance:
+
+* Test plain authentication
+* Test SSL and TLS authentication
+* Verify single and multiple recipients
+* Verify message subject and contents are formatted sanely.  They should be plaintext but readable.
+
+### Test Service
+
+Either setup a local smtp mail service here are some options:
+
+* postfix service on galaxy: https://galaxy.ansible.com/debops/postfix/
+* Mailtrap has a good free plan and should provide all of the features we need under that plan: https://mailtrap.io/
+
+## Slack
+
+Slack is pretty easy to configure, it just needs a token which you can get from creating a bot in the integrations settings for the slack team.
+
+### Testing considerations
+
+The following should be performed for good acceptance:
+
+* Test single and multiple channels and good formatting of the message.   Note that slack notifications only contain the minimal information
+
+### Test Service
+
+Any user of the Ansible slack service can create a bot integration (which is how this notification is implemented).   Remember to invite the bot to the channel first.
+
+## Hipchat
+
+There are several ways to integrate with hipchat.  The Tower implementation uses Hipchat "Integrations".  Currently you can find this at the bottom right of the main hipchat webview.  From there you will select "Build your own Integration".   After creating that it will list the `auth_token` that needs to be supplied to Tower.  Some other relevant details on the fields accepted by Tower for the Hipchat notification type:
+
+* `color`: This will highlight the message as the given color.  If set to something hipchat doesn't expect then the notification will generate an error, but it's pretty rad.  I like green personally.
+* `notify`: Selecting this will cause the bot to "notify" channel members.  Normally it will just be stuck as a message in the chat channel without triggering anyone's notifications.  This option will notify users of the channel respecting their existing notification settings (browser notification, email fallback, etc.)
+* `message_from`: Along with the integration name itself this will put another label on the notification.  I reckon this would be helpful if multiple services are using the same integration to distinguish them from each other.
+* `api_url`:  The url of the hipchat api service.  If you create a team hosted by them it'll be something like `https://team.hipchat.com`.   For a self-hosted service it'll be the http url that is accessible by Tower.
+
+### Testing considerations
+
+* Make sure all options behave as expected
+* Test single and multiple channels
+* Test that notification preferences are obeyed.
+* Test formatting and appearance.  Note that, like Slack, hipchat will use the minimal version of the notification.
+* Test standalone hipchat service for parity with hosted solution
+
+### Test Service
+
+Hipchat allows you to create a team with limited users and message history for free, which is easy to set up and get started with.   Hipchat contains a self-hosted server also which we should test for parity... it has a 30 day trial but there might be some other way to negotiate with them, redhat, or ansible itself:
+
+https://www.hipchat.com/server
+
+## Pagerduty
+
+Pager duty is a fairly straightforward integration.   The user will create an API Key in the pagerduty system (this will be the token that is given to Tower) and then create a "Service" which will provide an "Integration Key" that will be given to Tower also.   The other options of note are:
+
+* `subdomain`: When you sign up for the pagerduty account you will get a unique subdomain to communicate with.   For instance, if you signed up as "towertest" the web dashboard will be at towertest.pagerduty.com and you will give the Tower API "towertest" as the subdomain (not the full domain).
+* `client_name`: This will be sent along with the alert content to the pagerduty service to help identify the service that is using the api key/service.  This is helpful if multiple integrations are using the same api key and service.
+
+### Testing considerations
+
+* Make sure the alert lands on the pagerduty service
+* Verify that the minimal information is displayed for the notification but also that the detail of the notification contains all fields.  Pagerduty itself should understand the format in which we send the detail information.
+
+### Test Service
+
+Pagerduty allows you to sign up for a free trial with the service.   We may also have a ansible-wide pagerduty service that we could tie into for other things.
+
+## Twilio
+
+Twilio service is an Voice and SMS automation service.  Once you are signed in you'll need to create a phone number from which the message will be sent.  You'll then define a "Messaging Service" under Programmable SMS and associate the number you created before with it.  Note that you may need to verify this number or some other information before you are allowed to use it to send to any numbers.  The Messaging Service does not need a status callback url nor does it need the ability to Process inbound messages.
+
+Under your individual (or sub) account settings you will have API credentials.   The Account SID and AuthToken are what will be given to Tower.   There are a couple of other important fields:
+
+* `from_number`:  This is the number associated with the messaging service above and must be given in the form of "+15556667777"
+* `to_numbers`: This will be the list of numbers to receive the SMS and should be the 10-digit phone number.
+
+### Testing considerations
+
+* Test notifications with single and multiple recipients
+* Verify that the minimal information is displayed for the notification.  Note that this notification type does not display the full detailed notification.
+
+### Test Service
+
+Twilio is fairly straightforward to sign up for but I don't believe it has a free plan, a credit card will be needed to sign up for it though the charges are fairly minimal per message.
+
+## IRC
+
+The Tower irc notification takes the form of an IRC bot that will connect, deliver its messages to channel(s) or individual user(s), and then disconnect.  The Tower notification bot also supports SSL authentication.  The Tower bot does not currently support Nickserv identification.  If a channel or user does not exist or is not on-line then the Notification will not fail, the failure scenario is reserved specifically for connectivity.
+
+Connectivity information is straightforward:
+
+* `server`: The host name or address of the irc server
+* `port`: The irc server port
+* `nickname`: The bot's nickname once it connects to the server
+* `password`: IRC servers can require a password to connect.  If the server doesn't require one then this should be an empty string
+* `use_ssl`: Should the bot use SSL when connecting
+* `targets`: A list of users and/or channels to send the notification to.
+
+### Test Considerations
+
+* Test both plain and SSL connectivity
+* Test single and multiples of both users and channels.
+
+### Test Service
+
+There are a few modern irc servers to choose from but we should use a fairly full featured service to get good test coverage.   I recommend inspircd because it is actively maintained and pretty straightforward to configure.
+
+## Webhook
+
+The webhook notification type in Ansible Tower provides a simple interface to sending POSTs to a predefined web service.  Tower will POST to this address using `application/json` content type with the data payload containing all relevant details in json format.
+The parameters are pretty straightforward:
+
+* `url`: The full url that will be POSTed to
+* `headers`: Headers in json form where the keys and values are strings.  For example: `{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}`
+
+### Test Considerations
+
+* Test HTTP service and HTTPS, also specifically test HTTPS with a self signed cert.
+* Verify that the headers and payload are present and that the payload is json and the content type is specifically `application/json`
+
+### Test Service
+
+A very basic test can be performed by using `netcat`:
+
+```
+netcat -l 8099
+```
+
+and then sending the request to:   http://\<host\>:8099
+
+Note that this won't respond correctly to the notification so it will yield an error.   I recommend using a very basic Flask application for verifying the POST request, you can see an example of mine here:
+
+https://gist.github.com/matburt/73bfbf85c2443f39d272
+
+This demonstrates how to define an endpoint and parse headers and json content, it doesn't show configuring Flask for HTTPS but this is also pretty straightforward: http://flask.pocoo.org/snippets/111/