Email templates

You can define email templates, so that users in different roles can receive email notifications tailored to their role.

Email templates must be named EMailTemplate.templatename. For example, you could define the templates EMailTemplate.Developer, EMailTemplate.Operations, and EMailTemplate.Business.

WSRR is provided with a default email template, named EMailTemplate, which has the following format:
$event_title;

$event_type;($eventType;)
$object_bsruri;($bsrUri;)
$object_name;($name;)
$object_namespace;($namespace;)
$object_version;($version;)
The template uses escaping values to compose the message. The following order of precedence applies when replacing the escape values:
  1. The predefined escape strings; $eventType;, $bsrUri;, $name;, $namespace;, $version; will be replaced by the corresponding JMS message event or the appropriate entity metadata.

    In the case of the $eventType; escape string, it is replaced by the relevant value from the properties file for the locale by using the relevant key for the event: create_event, delete_event, update_event, transition_event, validate_event, make_governable_event or remove_governance_event.

  2. Escape strings that start with the percent character (%) are special functions that can alter the contents of the email message, or affect the email subject. A function has brackets after the escape string, for example, %emailSubject;($subject_key;,$name;), to indicate it requires parameters. Refer to the specific function to determine which parameters are required, and how many parameters are required.
  3. Any other escape string (for example $event_title;) is used as a key into the corresponding properties file for the locale. If it happens to have parameters indicated by having brackets after the escape string, for example $event_type;($eventType;), then those parameters will be used to replace the {0},{1},..,{n} strings contained in the relevant properties file value. The parameter value in brackets can reference another properties file key; however they cannot specify brackets inside the parameter value after the escape key and therefore the properties file value cannot contain the {0},{1},...,{n} strings.
You can base any role-specific templates on the default template. You can use the following additional escape strings when defining a template:
$transition_uri;
Specifies the URL of a transition that has occurred, for example, http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/LifecycleDefinition#Plan.
$transition;
Is the translated name of the transition, taken from the life cycle definition in the WSRR profile. For example, for the transition_uri http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/LifecycleDefinition#Plan, the value of $transition would be "Plan".

You can specify that the email includes a link to the item that triggered the email notification. You specify this by modifying the email template.

To specify a link to the item in the WSRR Web UI, add the following link to the template:
http://hostname:port/ServiceRegistry/ViewDetail.do?uri=$bsrUri;

If, for example, the mail recipient is expected to perform a transition, the governance tab can also be selected by appending the following to the end of the URL: &tabName=governance

To specify a link to the item in the dashboard, complete the following steps:
  1. Log in to the dashboard, and open the view and page that you want the email to link to. This page must include a Detail widget.
  2. Click the down-arrow next to the page name, and select Show Link from the menu.
  3. Copy the link string from the Page Link window.
    If you are viewing a page where the widgets have no content, then the link string will not have a reference to a specific item as shown in the following example:
    https://myserver:9443/ServiceRegistryDashboard/#view=DevelopmentView&page=P87523cb6-fd9a-4f2e-945a-2763d7766787
    You must edit the copied string to add the bsrURI parameter to the end, for example:
    https://myserver:9443/ServiceRegistryDashboard/#view=DevelopmentView&page=P87523cb6-fd9a-4f2e-945a-2763d7766787&bsrURI=$bsrUri;
    If you are viewing a page where the widgets already have content, then the bsrURI parameter will already be present. In this case you should change the value from its current alpha-numeric string to "$bsrUri;" as in the previous example.
  4. Include the link in your email template. The link loads the dashboard, on the view and page that was open when Show Link was clicked. The user who receives the email must have permissions to see the view.

Functions

Valid functions are:
emailSubject

This function sets the subject of the email message. It requires one parameter, which is the text of the email subject. This parameter can be an escape string which is used as a key into the corresponding properties file for the locale.

Any additional parameters, for example, %emailSubject;($subject_key;,$name;), are used to replace the {0},{1},..,{n} strings contained in the relevant properties file value. The additional parameters cannot reference another properties file key; if the parameter value is not one of the predefined set ($eventType;, $bsrUri;, $name;, $namespace;, $version;), it is substituted as a literal string.

If successfully resolved to a message, the string forming the email subject function is removed from the email message body.

The following example shows setting the email subject directly:
%emailSubject;(This is the subject)
The following example shows setting the email subject using the message in the properties file for the locale identified by the key "notification_notify_subject". The example provides an insert to replace the string {0} in the message. The {0} is replaced by the name of the object.
%emailSubject;($notification_notify_subject;,$name;)
dashboardUrl

This function works for templates used by the Email Owner and Email Consumers feature without configuration. If the template is used by the subscription notifier, then the user must configure the URL of the dashboard in the EMailSettings configuration item.

This function is replaced by a URL to the dashboard from which the email owner or email consumers request originates. The URL shows details of the service the email is about.

The function requires one parameter and accepts two parameters. The first parameter is the ID of the dashboard view to use and is required. The second parameter is the ID of the page in the dashboard view to use and is optional. For views with a single page, only the view ID is required. The ID of both the view and the page can be obtained by using the Show Link menu option on any dashboard page. The URL shown in the Page Link window contains the view ID as the value for the view parameter, and the page ID as the value for the page parameter.

The page specified must contain a widget which can display the service, for example, a Detail widget. If the view is not accessible to the user who clicks the link in the email, the user receives an error from the dashboard.

You can use the URL generated in a HTML link within the template.

The following example shows setting the dashboard URL to display details of the service in the SOA Governance view on the Browse page:

%dashboardUrl;(SOAGovernanceView,P138674b2-0967-4e70-b40a-069745386d83)

The following example shows embedding the dashboard url into a HTML link within the template, and using the message in the properties file for the locale identified by the key "notification_soagovernance":

<a href="%dashboardUrl;(SOAGovernanceView,P138674b2-0967-4e70-b40a-069745386d83)">$notification_soagovernance;</a>
Parent topic: Optionally, configure the email templating feature