-
Notifications
You must be signed in to change notification settings - Fork 10
GuideNotifications
The Notification Service is a service included by DTGov to make it easy to send out email notifications to users directly from the workflow. However, it can easily be used to send email notifications by any client that can perform a simple REST API call. This chapter describes how to enable and configure the Notification Service.
Invoking the Notification Service is a simple matter of sending a POST request to the proper dtgov service endpoint. For example:
http://localhost:8080/dtgov/notify/email/{group}/{template}/{target}/{uuid}
The path is made up of the following segments (see above):
-
group: a logical group name - maps to a "Notification Destination" (see below)
-
template: a logical name of a Template - maps to a Template (see below)
-
target: string passed to the Template
-
uuid: the UUID of an artifact - the name of the artifact can be used in the template
First, DTGov must either be configured with an "email" notification destination in the dtgov.properties file or the destination configuration must be left blank so that the default email settings are used. To configure explicit destination settings, the following can be set in the dtgov.properties file:
governance.email=<group1>|<fromAddress>|<toAddresses> governance.email=<group2>|<fromAddress>|<toAddresses> governance.email=<groupn>|<fromAddress>|<toAddresses>
This allows a mapping of logical group names to real destination email addresses. Note that the toAddresses value is a colon-separated list of real email addresses. Therefore an example configuration might be:
governance.email=DEV|[email protected]|[email protected]:[email protected] governance.email=PROD|[email protected]|[email protected]
If the 'governance.email' property information is missing from dtgov.properties, then an implicit mapping will be used based on the group name passed to the Notification Service when it is invoked and the following global email settings configured in dtgov.properties:
governance.email.domain governance.email.from
When these default settings are used, the Notification Service will send the email from the configured 'from' address specified above to the following email address:
${groupName}@${governance.email.domain}
The group name is whatever is passed to the notification service and the domain comes from the 'governance.email.from' property in dtgov.properties.
When sending an email notification, the subject and body of the email are generated by leveraging a template. When invoking the Notification Service, the template name is passed as one of the REST path segments. This logical name is used to look up the email template either from the classpath or from the S-RAMP repository.
The resulting template is then processed so that any Ant-style properties found in the template are resolved. A typical email body template might look like this:
Artifact ${uuid} with name '${name}' has been deployed to target ${target}.
Please claim this task, test this deployment and set a pass/fail status at the taskform at
${dtgovurl}/#taskInbox
--Overlord
There are two types of templates: one for the email body and one for the email subject. These template files can be located either on the classpath or in the S-RAMP repository.
When discovering the email template to use, DTGov will first look in the S-RAMP repository. DTGov will search for an artifact using the following query (for the email body template):
/s-ramp/ext/DtgovEmailTemplate[@template = '<templateName>' and @template-type = 'body']
Similarly, when looking for the email subject template, this query will be used:
/s-ramp/ext/DtgovEmailTemplate[@template = '<templateName>' and @template-type = 'subject']
When discovering the email template to use, DTGov will search the classpath for the body template here:
/governance-email-templates/<templateName>.body.tmpl
And for the subject it will look here:
/governance-email-templates/<templateName>.subject.tmpl
As a result, if the Notification Service is invoked with the following URL:
http://localhost:8080/dtgov/notify/email/DEV/invoiceReady/foo/12345
DTGov will look for email templates in the following places (in this order):
/s-ramp/ext/DtgovEmailTemplate[@template = 'invoiceReady' and @template-type = 'body'] /s-ramp/ext/DtgovEmailTemplate[@template = 'invoiceReady' and @template-type = 'subject'] /governance-email-templates/invoiceReady.body.tmpl /governance-email-templates/invoiceReady.subject.tmpl