notifications.html.md.erb

---
title: Getting Started with the Notifications Service
---

<strong><%= modified_date %></strong>

This guide is intended to walk you through using the Notifications Service.
<%= vars.notifications_api_1 %>

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.

##<a id='prereqs'></a> 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
- <%= vars.notifications_service %>
- Installed the [cf](https://github.com/cloudfoundry/cli) and [uaac](https://rubygems.org/gems/cf-uaac) command line tools

##<a id='create-client'></a>Create your Client and Get a Token ##

To interact with the Notifications service, Darla needs certain [UAA](../concepts/architecture/uaa.html) scopes (authorities). Rather than use her `admin` user account directly, she creates a `notifications-admin` client with the required scopes:

<pre class='terminal'>
$ uaac client add notifications-admin --authorized_grant_types client_credentials --authorities \
    notifications.manage,notifications.write,notification_templates.write,notification_templates.read,critical_notifications.write
</pre>

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:

<pre class='terminal'>
$ uaac token client get notifications-admin
</pre>

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

##<a id='registering'></a> 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:

<pre class='terminal'>
$ 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" }
     }
 }'
</pre>

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.

##<a id='custom-template'></a>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):

<pre class='terminal'>
$ 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":"<p>The site has gone down for maintenance. More information to follow {{.HTML}}"}'
</pre>

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:

<pre class='terminal'>
$ uaac curl https://notifications.darla.example.com/templates -X GET
</pre>

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

##<a id='associate'></a>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.

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

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.

##<a id='send-all'></a> 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:

<pre class='terminal'>
$ 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":"&lt;h1&gt;THE SYSTEM IS DOWN&lt;/h1&gt;&lt;p&gt;The system is going down while we upgrade our storage&lt;/p&gt;","subject":"Upgrade to Storage","reply_to":"no-reply@example.com"}'
</pre>

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. <%= vars.notifications_api_2 %>