Getting Started with the Notifications Service

Page last updated: October 29, 2015

This guide is intended to walk you through using the Notifications Service. For more information about the Notifications Service, see the Notifications API v1 or v2 documentation.

We’ll show you how to set up the service through the following example: Darla is a cloud operator who needs to take the system down for maintenance and wants to notify everybody about her intentions.

Prerequisites

Prior to using the Notifications service, Darla must have done the following:

  • Installed Cloud Foundry
  • Set up an admin account on her Cloud Foundry instance
  • Installed the Notifications service using the Notifications Release
  • Installed the cf and uaac command line tools

Create your Client and Get a Token

To interact with the Notifications service, Darla needs certain UAA scopes (authorities). Rather than use her admin user account directly, she creates 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

It’s worth noting that she doesn’t need all of these scopes just to send a notification. notifications.manage is used to update notifications and assign templates for that notification. notification_templates.write allows Darla to custom-make her own template for a notification, and notification_templates.read allows her to check which templates are saved in the database. Finally, notifications.write is the scope necessary to send a notification to a user, space, everyone in the system, and more.

Now, Darla logs in using her newly created client:

$ uaac token client get notifications-admin

Stay logged in with this client for the rest of the examples in this guide.

Registering Notifications

Darla cannot send a notification unless she has registered it first. Registering notifications requires the notifications.manage scope on her client. For example:

$ uaac curl https://notifications.darla.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" }
     }
 }'

Darla has registered two different notifications: system-going-down and system-up. In addition, she gives the notifications-admin client the human-friendly description “Cloud Ops Team.” Notice that she has made the system-going-down notification critical. This means that no users can unsubscribe from that notification. Setting notifications as critical requires the critical_notifications.write scope.

Create a Custom Template

The system provides a default template for all notifications, but Darla has decided to forgo this luxury. Darla wants to include her own branding and has opted to create her own custom template using the curl below (this action requires the notification_templates.write scope):

$ uaac curl https://notifications.darla.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}}"}'

A template is made up of a human readable 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.

Special attention and care should be paid to the variables that take this form {{.}}. These variables interpolate data provided in the send step below into the template before a notification is sent. Data that you can insert into a template during the send step includes {{.Text}}, {{.HTML}}, and {{.Subject}}.

This curl 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"}

Darla can check all of the saved templates by curling:

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

To view a list of all templates, you must have the notifications_templates.read scope.

Associate a Custom Template with your Notification

Darla now wants to associate her custom template with the system-going-down notification. Any notification that does not have a custom template applied, like her system-up notification, defaults to a system-provided template.

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

Here, Darla has associated the system-going-down notification belonging to the notifications-admin client with the template ID E3710280-954B-4147-B7E2-AF5BF62772B5. This is the template id of the template we created in the previous step.

This action requires the notifications.manage scope.

Send your Notification to All Users

Darla is ready to send her system-going-down notification to all users of the system. She performs this curl and includes some other pertinent information that gets directly inserted into the template:

$ uaac curl https://notifications.darla.example.com/everyone -X POST --data \
'{"kind_id":"system-going-down","text":"The system is going down while we upgrade our storage","html":"<h1>THE SYSTEM IS DOWN</h1><p>The system is going down while we upgrade our storage</p>","subject":"Upgrade to Storage","reply_to":"[email protected]"}'

The data included in the post body above gets interpolated into the variables we previously inserted into our created template (they had the special syntax similar to {{.Text}}).

Sending a critical notification requires the scope critical_notifications.write, while sending a non-critical notification requires the scope of notifications_write.

Darla could have also chosen to send the above notification to one specific user, an email address, or a particular space. For more information about targeting your notification to particular audiences, see the Notifications API v1 or v2 documentation.