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
- 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
andsystem-up
are the notifications set.system-going-down
andsystem-up
are madecritical
, 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 DOWNThe system is going down while we upgrade our storage
","subject":"Upgrade to Storage","reply_to":"no-reply@example.com"}'