notifications

Notifications

A notifications component that parts of CF can use to send email to end users

UAA Client

Notifications itself needs the following UAA client in order to retrieve arbitrary users' email addresses and check the members of arbitrary spaces:

properties:
  uaa:
    clients:
      notifications:
        secret: my-secret
        authorities: cloud_controller.admin,scim.read
        authorized-grant-types: client_credentials

Client Configurations

Send Notifications

The following client configurations are needed for sending messages to individual users, users in a specific space and arbitrary email addresses.

To send non-critical notifications, notifications.write scope is required. Sending critical notifications requires critical_notifications.write scope. To send notifications to an arbitrary email address requires emails.write scope.

notifications-client-name:
  scope: uaa.none
  resource_ids: none
  authorized_grant_types: client_credentials
  authorities: notifications.write critical_notifications.write emails.write
  autoapprove:

View and Edit User Preferences

To view and edit a user's preferences for receiving non-critical notifications, a client will need to be configured with notification_preferences.read scope and notification_preferences.write scope.

A client with notification_preferences.admin scope has the ability to retrieve an arbitrary user's preferences.

notifications-client-name:
  scope: notification_preferences.read notification_preferences.write openid
  resource_ids: none
  authorized_grant_types: authorization_code client_credentials refresh_token
  redirect_uri: http://example.com/sessions/create
  authorities: notification_preferences.admin
  autoapprove: 

If you are unfamiliar with UAA consult the UAA token overview.

##Configuring Environment Variables

* required

Posting to a notifications endpoint

Notifications currently supports two different types of messages. Messages to individual users and messages to spaces.

Users are messaged via the /users/id endpoint and spaces are messaged via /spaces/id endpoint.

Both endpoints expect a json body to be posted with following keys:

* required

** either text or html have to be set, not both

Further API Documentation

Configuring Email Templates

The default templates are located in ./templates. The templates directory should look similar to this:

overrides/
user_body.text
user_body.html
space_body.text
space_body.html
organization_body.text
organization_body.html
email_body.text
email_body.html
subject.missing
subject.provided

When emailing a single user, user_body.html and user_body.text are used as templates in the email body for the html and plaintext, respectively. When emailing a space, space_body.html and space_body.text are used as templates in the email body for the html and plaintext, respectively. When emailing an organization, organization_body.html and organization_body.text are used as templates in the email body for the html and plaintext, respectively.

When the subject is provided, the default subject template is found in subject.provided, while subject.missing is used when the email subject is not provided.

When using the /emails endpoint, email_body.html and email_body.text are used as templates in the email body for the html and plaintext, respectively.

The files located in the templates directory are defaults and will be used if there is no override of the same name.

Overriding default templates

There are three types of overrides.

All types of overrides have access to the same variables described in global overrides. The only difference is which email types they are applied to.

global overrides

Any file that exists in ./templates can be overriden by placing a file of the same name in ./templates/overrides.

The templates are go templates. The templates have access to the following variables:

To override the plain text template in the email body, write the following in ./templates/overrides/space_body.text:

You are receiving this electronic mail because you are a member of {{.Space}}

All apps in {{.Space}} have had an emergency of type {{.KindDescription}}

overriding by clientID

To override a template for a client with id banana. You would place a file in the ./templates/overrides directory with the following name scheme:

clientID.templateName.templateExtension

So to override the subject.missing the file name would be:

banana.subject.missing

This override would only be applied to emails sent by the client banana.

overriding by clientID and kind_id

To override a template for client banana with the kind_id damage you would place a file in the ./templates/overrides directory with the following name scheme:

clientID.kind_id.templateName.templateExtension

So to override the user_body.text template the file name would be:

banana.damage.user_body.text

This override only applies to requests that match both the clientId and the kind. This has the most precedence and overrides all other overrides.

Further Template API Documentation

UnsubscribeID

AES Encryption is used to encrypt a token value for unsubscribing a user from a notification. The format of the token is the user_guid|client_id|kind_id. The key used to instantiate a cipher is a 16 byte MD5 sum of the text given to the ENCRYPTION_KEY environment variable.

Encrypting:

1. Concatenate user GUID, client ID, and kind ID into a single string, delimited by a | character.
2. Base64 encode the concatenated string.
3. Encrypt the encoded text using AES cipher in CFB mode.
4. Base64 encode the cipher text.

Decrypting:

1. Base64 decode the unsubscribe token.
2. Decrypt the decoded text using AES cipher in CFB mode.
3. Base64 decode the decrypted text.
4. Split the text at the | characters.

Development

Running locally

The application can be run locally by executing the ./bin/run script. This script will look for a file called ./bin/env/development to load environment variables. Setting the TEST_MODE env var to true will disable the requirement for a running SMTP server.