diff --git a/docs/notification_system.md b/docs/notification_system.md index 65b05607b3..5b3b8fccd4 100644 --- a/docs/notification_system.md +++ b/docs/notification_system.md @@ -11,6 +11,39 @@ At a high level, the typical notification task flow is: * User creates a `NotificationTemplate` at `/api/v2/notification_templates/`. * User assigns the notification 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 Notification Template to trigger when `Job Template 1` fails. +## Templated notification messages + +When creating a notification template, the user can optionally provide their own custom messages for each notification event (start, success, error). If a message is not provided, the default message generated by Tower will be used. + +The notification message can include templated fields written using Jinja templates. The templates may reference a set of white-listed fields found in the associated job's serialization. + + HTTP POST /api/v2/notification_templates/ + + { + "name": "E-mail notification", + "description": "Custom e-mail notification", + "organization": 1, + "notification_type": "email", + "notification_configuration": { + .. + }, + "messages": { + "started": { + "message": "{{ job.name }} completed successfully in {{ job.elapsed }} seconds using instance group {{ job.summary_fields.instance_group.name }}", + "body": null # default body will be used + }, + "success": { + "message": null, # default message will be used + "body": null # default body will be used + }, + "error": { + "message": "{{ job.name }} was unsuccessful ({{ job.status }})", + "body": "{{ job.job_explanation }}" + } + } + } + + ## Notification Hierarchy Notification templates assigned at certain levels will inherit notifications defined on parent objects as such: @@ -28,7 +61,7 @@ Notifications can succeed or fail but that will _not_ cause its associated job t ## Testing Notifications Before Using Them -Once a Notification Template is created, its configuration can be tested by utilizing the endpoint at `/api/v2/notification_templates//test` This will emit a test notification given the configuration defined by the notification. These test notifications will also appear in the notifications list at `/api/v2/notifications` +Once a Notification Template has been created, its configuration can be tested by utilizing the endpoint at `/api/v2/notification_templates//test`. This will emit a test notification given the configuration defined by the notification. These test notifications will also appear in the notifications list at `/api/v2/notifications` # Notification Types @@ -47,7 +80,6 @@ The currently defined Notification Types are: 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 and timeouts. @@ -59,17 +91,16 @@ 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. +* Verify message subject and contents are formatted sanely. They should be plaintext but readable. ### Test Service -Set up a local SMTP mail service. Some options are listed below: +Set up a local SMTP mail service. Some options are listed below: * Postfix service on galaxy: https://galaxy.ansible.com/debops/postfix/ * Mailtrap has a good free plan that should provide all of the features necessary: https://mailtrap.io/ * Another option is to use a Docker container: `docker run --network="tools_default" -p 25:25 -e maildomain=mail.example.com -e smtp_user=user:pwd --name postfix -d catatnight/postfix` - ## Slack Slack is simple to configure; it requires a token, which you can get from creating a bot in the integrations settings for the Slack team. @@ -80,10 +111,9 @@ 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. - ## Mattermost -The Mattermost notification integration uses Incoming Webhooks. A password is not required because the webhook URL itself is the secret. Webhooks must be enabled in the System Console of Mattermost. If the user wishes to allow Ansible Tower notifications to modify the Icon URL and username of the notification, then they must enabled these options as well. +The Mattermost notification integration uses Incoming Webhooks. A password is not required because the webhook URL itself is the secret. Webhooks must be enabled in the System Console of Mattermost. If the user wishes to allow Ansible Tower notifications to modify the Icon URL and username of the notification, then they must enable these options as well. In order to enable these settings in Mattermost: 1. Go to System Console > Integrations > Custom Integrations. Check "Enable Incoming Webhooks". @@ -107,7 +137,6 @@ In order to enable these settings in Mattermost: * Utilize an existing Mattermost installation or use their Docker container here: `docker run --name mattermost-preview -d --publish 8065:8065 mattermost/mattermost-preview` * Turn on Incoming Webhooks and optionally allow Integrations to override usernames and icons in the System Console. - ## Rocket.Chat The Rocket.Chat notification integration uses Incoming Webhooks. A password is not required because the webhook URL itself is the secret. An integration must be created in the Administration section of the Rocket.Chat settings. @@ -124,16 +153,15 @@ The following fields are available for the Rocket.Chat notification type: ### Test Service -* Utilize an existing Rocket.Chat installation or use their Docker containers from https://rocket.chat/docs/installation/docker-containers/ +* Utilize an existing Rocket.Chat installation or use a Docker container from https://rocket.chat/docs/installation/docker-containers/ * Create an Incoming Webhook in the Integrations section of the Administration settings - ## Pagerduty Pagerduty 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 also be given to Tower. 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. +* `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 @@ -144,36 +172,34 @@ Pagerduty is a fairly straightforward integration. The user will create an API K Pagerduty allows you to sign up for a free trial with the service. - ## Twilio -Twilio is a 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 (the one you created for this purpose) 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. +Twilio is a 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 (the one you created for this purpose) 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". +* `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. +* 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 there may not be a free trial offered; 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 online, then the Notification will not fail; the failure scenario is reserved specifically for connectivity. +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 online, 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. +* `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`: If you want the bot to use SSL when connecting. * `targets`: A list of users and/or channels to send the notification to. @@ -184,12 +210,11 @@ Connectivity information is straightforward: ### Test Service -There are a few modern IRC servers to choose from. [InspIRCd](http://www.inspircd.org/) is recommended because it is actively maintained and pretty straightforward to configure. - +There are a few modern IRC servers to choose from. [InspIRCd](http://www.inspircd.org/) is recommended because it is actively maintained and pretty straightforward to configure. ## Webhook -The webhook notification type in Ansible Tower provides a simple interface to sending `POST`s 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 webhook notification type in Ansible Tower provides a simple interface for sending `POST`s 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 fairly straightforward: @@ -251,7 +276,7 @@ The configurable options of the Grafana notification type are: * Make sure the annotation gets created on the desired dashboard and/or panel and with the configured tags. ### Test Service -* Utilize an existing Grafana installation or use their Docker containers from http://docs.grafana.org/installation/docker/. +* Utilize an existing Grafana installation or use Docker containers from http://docs.grafana.org/installation/docker/. * Create an API Key in the Grafana configuration settings. * (Optional) Lookup `dashboardId` and/or `panelId` if needed. * (Optional) Define tags for the annotation.