Triggers Used for Email Notifications

You can use the Notification object with an eService Trigger Program Parameters object to define email notifications without writing code. By combining existing attributes with select clauses, you can customize email notifications for any trigger event defined for your business process.

The following topics are discussed:

How the Notification is Sent

A notification can be sent:


  • using the Trigger Manager
  • calling the notification API from a bean or JPO

The email notification object must be associated with an Action trigger type. If a notification needs to be sent and there is no associated trigger event, custom code can be written to call the method directly and pass the name of the notification object.

All notification objects must be stored in the eService Administration vault.

These sections describe how to work with Notification objects:

Generic Email Utility

emxNotificationUtil is a generic email utility that accepts input arguments (as entered as the attribute values of the Notification object), and constructs and sends an email message to the defined distributions lists.

This JPO contains these methods:


  • objectNotification-takes an object ID and notification object name as arguments
  • relationshipNotification-takes a relationship ID and notification object name as arguments

These methods operate on all revisions of the notification object and formulate the input to lower level utility methods that actually send the email. The methods use the Filter attribute to determine whether or not the email should be sent, evaluate select clauses to populate the recipient fields (From Agent, Static and Dynamic To, Cc, and Bcc Lists), and builds the ID lists to be sent as attachments.

The email messages make use of the preferred language functionality defined in About Internationalizing.

Execution of the emxNotificationUtil is queued until the outermost transaction surrounding the event is committed. If the transaction is aborted, the JPO does not execute and the notification is not sent.

If errors occur during the email process, they are written to the system log file (mxtrace.log). If notifications are not being sent, the system administrator can scan the log file to diagnose the problem. If the problem cannot be diagnosed using the log file, the system administrator can turn on SMTP tracing.

Notification Object Attributes

This section lists the attributes for the Notification object.

All attributes are optional except:


  • At least one recipient needs to be defined
  • The Subject Text must be supplied

The Body Text attribute is required if the notification is triggered by a subscription event.

In addition, these attributes can specify a JPO to calculate the value of these attributes at run time: filter, recipients of the To, Cc, or Bcc list, subject and body text. When used, the format for specifying the JPO and method is:

JPO jponame:methodname

When used with subscriptions, the notifications can use provided JSPs to process distribution lists and the body of the message as listed in the Accepted Values/Examples column of the table below.

If you specify a JPO as the value for an attribute, you cannot combine it with other values for that attribute.See Sample JPO Code for Notification Attributes for a sample JPO that can be used for several of the notification object attributes.

If a value is provided for both the Body Text and Body HTML attributes, the body will be constructed as a multipart message of MIME Content-type multipart/alternative. The email client can be configured to show either format, if both are supported.

This table defines the attributes used to configure a Notification object:

Attribute Description Accepted Values/Examples

Filter

Expression used to determine whether or not the email notification should be sent. If the expression evaluates to true, the notification is sent, otherwise the notification is not sent.

If a JPO method is provided, then the method is executed. If the method returns 0 (a false result), no more processing takes place and the message is not sent.

policy == $<policy_ECRItem> && $<attribute[attribute_Priority]> == High

From Agent

Defines the user that the notification is sent from (the default is the context user). This attribute displays in the From field of the email message.

Use $USER to define the current context user as the From Agent.

$<person_UserAgent>

$USER

User Agent

$<state[Design Work].signature[Senior Design Engineer].signer>

Any select clause that results in a username

Static To List

To list of the email notification (semicolon-separated list of users to be notified).

$<person_JSmith>;$<group_DesignEngineering>

JSmith;Design Engineering Group

Static Cc List

CC list of the email notification (semicolon separated list of users to be copied on the notification).

$<role_ECRCoordinator>

Static Bcc List

BCC list of the email notification (semicolon separated list of users to be blind-copied on the notification).

$<group_ReviewPanel>

Dynamic To List

To select clauses, a semicolon separated list of select clauses that result in users being added to the To list. The JPO shown retrieves all users who subscribed to the event; if you use this JPO, you cannot specify any other users.

$<attribute[attribute_Originator]>

JPO emxSubscriptionUtil.getSubscribersList

Dynamic Cc List

Cc select clauses, a semicolon separated list of select clauses that result in users being added to the CC list.

$<attribute[attribute_CoOwners]>

Dynamic Bcc List

Bcc select clauses, a semicolon separated list of select clauses that result in users being added to the Bcc list.

$<attribute[attribute_CoOwners]>

Subject Text

Subject string key, or the actual string. If a key is used, the text can be internationalized.

emxEngineeringCentral.Notification.NotifyOwner.Subject

Completion: Route Name $<from[Route Task].to.name> Task Name $<name>

Body Text

Body string key or the actual string. If a key is used, the text can be internationalized.

When multiple values are returned for a select clause, the values are concatenated in a comma-separated list.

This attribute is required if the notification is triggered by a subscription event.

Can be a JPO:method that returns the notification message in plain text format. The JPO in the Accepted Values column converts XML string data passed to the method and converts it to plain text.

ECO $<name>, Approval category $<attribute [attribute_ApprovalCategory]>

Route Task Rejection $<from[relationship_ RouteTask].to.name>

JPO emxSubscriptionUtil:prepareBodyText

Body HTML

Same as Body Text except in HTML format.

This attribute is required if the notification is triggered by a subscription event.

Can be a JPO:method that returns the notification message in plain text format. The JPO in the Accepted Values column converts XML string data passed to the method and converts it to HTML format.

JPO emxSubscriptionUtil:prepareBodyHTML

Registered Suite

Used to define the property base file name - the name of the file that contains the string keys passed in other attributes. If string keys are not used, this attribute can be blank.

For example, Engineering Central would be formulated to create:

emxEngineeringCentralStringResource

Attachments

Semicolon-separated list of select clauses that result in IDs of objects added to the message as URLs. The links can be used by the recipient to go directly to that page in the ENOVIA product.

id;$<from[relationship_RouteTask].to.id>

id;from[Route Task].to.id

URL Suffix

URL suffix to append to all URLs embedded in the message body.

&DefaultCategory=PMCLifecycle

Reply To

User to send replies to (the default is the From Agent); can contain text (including embedded select clauses) following a single pipe character

&<person_NotificationAgent>|$<id>

Preprocess JPO

JPO name and method called prior to sending email. The method is passed the values of all attributes and can perform any type of processing (including changing the values of the attributes) and return an integer status. If a non-zero value is returned, the email message will not be sent.

emxSubscriptionUtil:addRecipientsSubscribers

Internationalizing Text Strings in Notifications

To internationalize the email notification, you can use string keys for the Subject Text, Body Text, and Body HTML attributes, then provide the Registered Suite name so that the strings can be looked up.

See Internationalizing Business Process Services Products for details.

After testing a notification object, any strings used for the Subject Text, Body Text, or Body HTML attributes should be moved into the appropriate property file to support internationalization of the notifications.

For example, you might add these strings to the emxFrameworkStringResource.properties file: 

emxFramework.Notification.NotifyRouteOwner.Subject=Completion: Route 
Name $<frm[Route Task].to.name>, Task Name $<name>
emxFramework.Ntofication.NotifyRouteOwner.Body=Task Instructions: 
$<attribute[Route Instructions]> \nTaskResponse: 
$<attribute[Comments]>

Then, update the following attribute fields to reference these property strings:


  • Subject Text--emxFramework.Notification.NotifyRouteOwner.Subject
  • Body Text--emxFramework.Notification.NotifyRouteOwner.Body
  • Registered Suite--Framework