Getting Started with the Notifications Service

Prerequisites
Create a Client and Get a Token
Register Notifications
Create a Custom Template
Associate a Custom Template with a Notification
Send a Notification

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

Install Pivotal Application Service (PAS).
You must have admin permissions on your Cloud Foundry instance. You also must configure Application Security Groups (ASGs).
Install the Cloud Foundry Command Line Interface (cf CLI) and User Account and Authorization Server (UAAC) command line tools.

Create a Client and Get a Token

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

Use uaac target uaa.YOUR-DOMAIN to target your UAA server.
```
$ uaac target uaa.example.com
```
Record the Admin Client Credentials from the UAA row in the PAS Credentials tab.
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
```
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.
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"}'

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