LATEST VERSION: 1.9 - CHANGELOG
Pivotal Cloud Foundry v1.9

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

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.

Was this helpful?
What can we do to improve?
View the source for this page in GitHub