Getting Started with the Notifications Service

Page last updated:

This topic describes how to use the Notifications Service, including how to create a client, obtain a token, register notifications, create a custom template, and send notifications to your users.

Prerequisites

Create a Client and Get a Token

To interact with the Notifications Service, you must create UAA scopes:

  1. Use uaac target uaa.YOUR-DOMAIN to target your UAA server. 

    $ uaac target uaa.example.com

  2. Record the Admin Client Credentials from the UAA row in the PAS Credentials tab.

  3. Use uaac token client get admin -s ADMIN-CLIENT-SECRET to authenticate and obtain an access token for the admin client from the UAA server. UAAC stores the token in ~/.uaac.yml. 

    $ uaac token client get admin -s MyAdminPassword

  4. Create a notifications-admin client with the required scopes. 

    $ uaac client add notifications-admin --authorized_grant_types client_credentials --authorities \
    notifications.manage,notifications.write,notification_templates.write,notification_templates.read,critical_notifications.write

    • notifications.write: send a notification. For example, you can send notifications to a user, space, or everyone in the system.
    • notifications.manage: update notifications and assign templates for that notification.
    • (Optional) notification_templates.write: create a custom template for a notification.
    • (Optional) notification_templates.read: check which templates are saved in the database.

  5. Log in using your newly created client:

    $ uaac token client get notifications-admin

    Note: Stay logged in to this client to follow the examples in this topic.

Register Notifications

Note: To register notifications, you must have the notifications.manage scope on the client. To set critical notifications, you must have the critical_notifications.write scope.

You must register a notification before sending it. Using the token notifications-admin from the previous step, the following example registers two notifications with the following properties:

$ uaac curl https://notifications.user.example.com/notifications -X PUT --data '{  "source_name": "Cloud Ops Team",
  "notifications": {
     "system-going-down": {"critical": true, "description": "Cloud going down" },
     "system-up": { "critical": true, "description": "Cloud back up" }
     }
 }'
  • source_name has “Cloud Ops Team” set as the description.
  • system-going-down and system-upare the notifications set.
  • system-going-down and system-up are made critical, so no users can unsubscribe from that notification.

Create a Custom Template

Note: To view a list of templates, you must have the notifications_templates.read scope. To create a custom template, you must have the notification_templates.write scope.

A template is made up of a name, a subject, a text representation of the template you are sending for mail clients that do not support HTML, and an HTML version of the template.

The system provides a default template for all notifications, but you can create a custom template using the following curl command. 

$ uaac curl https://notifications.user.example.com/templates -X POST --data \
'{"name":"site-maintenance","subject":"Maintenance: {{.Subject}}","text":"The site has gone down for maintenance. More information to follow {{.Text}}","html":"
The site has gone down for maintenance. More information to follow {{.HTML}}"}'

Variables that take the form {{.}} interpolate data provided in the send step before a notification is sent. Data that you can insert into a template during the send step include {{.Text}}, {{.HTML}}, and {{.Subject}}.

This curl command returns a unique template ID that can be used in subsequent calls to refer to your custom template. The result looks similar to this:

{"template-id": "E3710280-954B-4147-B7E2-AF5BF62772B5"}

Check all of your saved templates by running a curl command:

$ uaac curl https://notifications.user.example.com/templates -X GET

Associate a Custom Template with a Notification

In this example, the system-going-down notification belonging to the notifications-admin client is associated with the template ID E3710280-954B-4147-B7E2-AF5BF62772B5. This is the template ID of the template we created in the previous section.

Associating a template with a notification requires the notifications.manage scope.

$ uaac curl https://notifications.user.example.com/clients/notifications-admin/notifications/system-going-down/template \
-X PUT --data '{"template": "E3710280-954B-4147-B7E2-AF5BF62772B5"}'

Any notification that does not have a custom template applied, such as system-up, defaults to a system-provided template.

Send a Notification

Note: To send a critical notification, you must have the critical_notifications.write scope. To send a non-critical notification, you must have the notifications_write scope.

You can send a notification to the following recipients:

  • A user
  • A space
  • An organization
  • All users in the system
  • A UAA-scope
  • An email address

For details, see the Notifications V1 Documentation in GitHub.

The following example sends the system-going-down notification described above to all users in the system.

$ uaac curl https://notifications.user.example.com/everyone -X POST --data \
'{"kind_id":"system-going-down","text":"The system is going down while we upgrade our storage","html":"THE SYSTEM IS DOWN
The system is going down while we upgrade our storage
","subject":"Upgrade to Storage","reply_to":"no-reply@example.com"}'