forked from cloudfoundry/docs-cf-admin
-
Notifications
You must be signed in to change notification settings - Fork 0
/
notifications.html.md.erb
179 lines (129 loc) · 6.95 KB
/
notifications.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
---
title: Get started with the Notifications Service in Cloud Foundry
owner: Notifications
---
<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>
<% set_title("Get started with the Notifications Service in", vars.app_runtime_abbr) %>
<% end %>
You can use the Notifications Service in <%= vars.app_runtime_abbr %> to create a client, obtain
a token, register notifications, create a custom template, and send notifications.
<%= vars.notifications_api_1 %>
## <a id='prereqs'></a> Prerequisites
Before you use the Notifications Service you must:
* Install [<%= vars.app_runtime_full %>](<%= vars.product_url %>) (<%= vars.app_runtime_abbr %>).
* Have `admin` permissions on your <%= vars.app_runtime_abbr %> instance.
<%= vars.asg_notifications_prereq %>
* Install the [Cloud Foundry Command Line Interface (cf CLI)](https://github.com/cloudfoundry/cli)
and [User Account and Authorization Server (UAAC)](https://rubygems.org/gems/cf-uaac) command line
tools.
## <a id='create-client'></a> Create a client and get a token
To interact with the Notifications Service, you must create UAA scopes.
To create UAA scopes:
1. Target your UAA server by running:
```
uaac target uaa.YOUR-DOMAIN
```
Where `YOUR-DOMAIN` is the domain of your UAA server URL.
1. <%= vars.uaa_admin_client_creds %>
1. Authenticate and obtain an access token for the admin client from the UAA server by running:
```
uaac token client get admin -s ADMIN-CLIENT-SECRET
```
Where `ADMIN-CLIENT-SECRET` is the admin client secret.
<br><br>
UAAC stores the token in `~/.uaac.yml`.
1. Create a `notifications-admin` client with the required scopes by running:
```
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.
1. Log in using your newly created client by running:
```
uaac token client get notifications-admin
```
<p> Stay logged in to this client to follow the examples in
this topic.</p>
For more information about UAA scopes, see
[User Account and Authentication (UAA) Server](../concepts/architecture/uaa.html).
## <a id='registering'></a> Register notifications
<p class="note important">
<span class="note__title"><strong>Important</strong></span>
To register notifications, you must have the
<code>notifications.manage</code> scope on the client. To set critical notifications, you must have
the <code>critical_notifications.write</code> scope.</p>
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-up` are the notifications set.
* `system-going-down` and `system-up` are made `critical`, so no users can unsubscribe from that
notification.
## <a id='custom-template'></a> Create a custom template
<p> To view a list of templates, you must have the
<code>notifications_templates.read</code> scope. To create a custom template, you must have the
<code>notification_templates.write</code> scope.</p>
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
by running:
```
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":"<p>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:
```
{"template-id": "E3710280-954B-4147-B7E2-AF5BF62772B5"}
```
Check all of your saved templates by running:
```
uaac curl https://notifications.user.example.com/templates -X GET
```
## <a id='associate'></a> 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.
## <a id='send'></a> Send a notification
<p class="note important">
<span class="note__title"><strong>Important</strong></span>
To send a critical notification, you must have the
<code>critical_notifications.write</code> scope. To send a non-critical notification, you must have
the <code>notifications_write</code> scope.</p>
You can send a notification to the following recipients:
* A user
* A space
* An org
* All users in the system
* A UAA scope
* An email address
For more information, see
[Notifications V1 Documentation](https://github.com/cloudfoundry-incubator/notifications/blob/master/V1_API.md) in
the Notifications repository on GitHub.
The following example command 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":"<strong>THE SYSTEM IS DOWN</strong><p>The system is going down while we upgrade our storage</p>","subject":"Upgrade to Storage","reply_to":"no-reply@example.com"}'
```