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.

For more information about the Notifications Service, see the Notifications API v1 or v2 documentation.

Prerequisites

You must have the following setup before using the Notifications Service:

Create a Client and Get a Token

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

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

    $ uaac target uaa.example.com
    

  2. Record the uaa:admin:client_secret from your deployment manifest.

  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": false, "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.

Create a pull request or raise an issue on the source for this page in GitHub