Defining a workflow to send email notifications

In a Notify action from filter or escalation workflow, you can select Email as a notification mechanism. When you select Email, the bottom part of the window displays the Fields, Messages, and Templates tabs where you define the configuration and contents of your email message.

The Email Engine must be running to enable you to send email notifications. Then, when the filter or escalation is triggered (for example, from a filter submit or modify action), the AR System server logs a message containing the notification text (and, optionally, field contents) on the AR System Email Messages form. The Email Engine then picks up the entries from the form, processes them, and sends the email notifications to the designated user or group.

Before you begin

Make sure you have an outgoing mailbox configured with Default Outgoing Mailbox set to Yes, otherwise, you will not receive any notifications. For more information, see Configuring-outgoing-mailboxes.

To define a workflow to send email

In Developer Studio, create a Notification filter or escalation.
Right click the If Action tab or the Else Action tab.
From the Add Action list, select Notify.
The Notify Filter (or escalation) page of the Create Filter (or escalation) dialog box as shown in the following screenshot is displayed. The fields required to define the Notify filter or escalation appear.
From the Mechanism field, select Email.
Enter a value in the Priority field.
Ranges of 1 to 10 are acceptable. By default, emails are sent out from the Email Engine in the order they were received, not in the order of priority.
In the User field, enter the name of the users or groups to notify. For each recipient, an entry is made in the AR System Email Messages form. You can enter a maximum of 255 characters.
To specify one or more recipients, enter any of the following choices separated by hard returns (the server evaluates each line separately) in the User Name field:
- AR System user logins
- AR System groups
- Email addresses
  Include the email domain name if you enter an email address (for example, Joe.User@acme.com) or a keyword (for example, $USER$@acme.com). The order in which these entries appear is the order in which the Email Engine searches for addresses. If the contents of the User Name field do not match an existing User or Group definition, the system interprets the field contents as a literal address and sends the notification to that address by SMTP, IMAP, MAPI, or POP mail protocols. This address can be an email address representing users who are not using AR System, an alias for a group, or an email address representing a program.
  Warning
  Do not use group notifications as an email system for broadcast-type items because the server processes a notification for each member. An email alias is more efficient. If you are using a field reference (for example, $Submitter$), do not include the domain name as part of the notification because the email address is being read from the Email Address field of the user's entry in the User form.
In the Text field, enter the text of the message.
You can use the Text list to insert fields from the current form or keywords into the text. The field or keyword will be expanded when the notification is sent, to a maximum of 32 KB.
You can include sophisticated AR System functionality in the text of an email notification. The following code block shows the use of a URL that performs a search that goes directly to the request the user needs to view.
*The $Impact$ incident, <a href="http://polycarp/arsys/servlet/ ViewFormServlet?server=polycarp&form=HD+Incident&eid=$Request ID$">$Request ID$</a>, has been assigned to you.*
From the Fields list, select an option that you want to include in the email notification.
The following options are available:
- None—None of the fields is included with the notification.
- All—All of the fields in the request are included with the notification.
- Selected—Selected fields from the fields list are included with the notification.
- Changed— Only fields that have changed in the current transaction are included with the notification.
To view additional settings, click Show Unused Fields.
When you select the Mechanism as Email, the Fields, Messages, and Templates tabs are displayed where you can define the configuration and contents of your email message.
The following screen shows additional settings available:
In the Mailbox Name field, specify the mailbox you want to use.
Save the filter or escalation.

Including attachments in the email notification

To include attachments, use the filter or escalation you have created to define the workflow to send an email.

In the filter, from the Fields list, select Attachment fields.

Make sure the receiver of the notification has permission to the attachment field on the AR System form. To receive the attachment, the $Assigned To$ group must have permission to the field, which the AR System administrator defines when the field is created.
The following screenshot shows the attachment field:

After the notifications are sent, the message status changes in the Email Messages form from Yes to Sent.
If you choose to delete Notification messages in your mailbox configuration, the notification email entry is deleted from the Email Messages form.

Using the Messages and Templates tabs

In Developer Studio, the Messages and Templates tabs on the filter allow you to determine at run time which user the email came from, which mailbox to use, which templates to use, and so on. The fields in these tabs are optional. If you leave these fields blank, the settings relating to the mailbox entered in the Mailbox Name field apply. Or, if the Mailbox Name field is empty, the default outgoing mailbox settings apply. The default outgoing mailbox is the first mailbox created, or you can specify another mailbox in the AR System Email Mailbox Configuration form.

Any entries in the fields in the Messages and Templates tabs will override the default settings. If there are no entries in the Messages and Templates tabs, and no default mailbox exists, an error message will be generated.

To define messages in email notifications

Use the Messages tab to override your mailbox configuration settings for the Notify action. If you leave these fields blank, the values in your notification email default to your current mailbox configuration settings.

Open the Messages tab.
In the Mailbox Name field, enter the name of the outgoing mailbox that you want to handle the notifications if you do not want to use the default mailbox.
You can use a field or a keyword to substitute the mailbox name. This mailbox name should correspond to a valid mailbox configured in the AR System Email Mailbox Configuration form.
Enter information in the From, Reply To, CC, and BCC fields:
- If you make multiple entries in these fields, separate the entries by hard returns. The maximum size of these fields is 32000 characters.
- You can use the following entries in the fields:
  - AR System user logins
  - AR System groups
  - Email addresses—Include the email domain name if you are entering a user's name (for example, Joe.User@acme.com) or a keyword (for example, $USER$@acme.com).
  - A field
  - A keyword
    The order in which these entries appear is the order in which the Email Engine searches for addresses.
- If you fill in these fields, the Email Engine populates the equivalent fields in the AR System Email Messages form for the appropriate user name.
  However, if the information for these fields in the AR System Email Messages form is supplied from the AR System Email Mailbox Configuration form (that is, a specified mailbox, or a default mailbox that has already been configured), you need to display and save the AR System Email Messages form before you see the entries.
In the From field, enter the name to be displayed to indicate where the mail is from.
If this field is blank and there are no entries in the From field on the Advanced tab of the AR System Email Mailbox Configuration form for the specified mailbox, or for the default mailbox, there will be no entry in the email to indicate who the email is from.
In the Reply To field, if you enter a group name, a reply will be sent to all the names in the group.
If this field is blank, and there are no entries in the Reply To field on the Advanced tab of the AR System Email Mailbox Configuration form for the specified mailbox, or for the default mailbox, there will be no entry in the email to indicate any Reply To.
In the CC and BCC fields, if there are no entries in these fields or the Default Addressing section of the Advanced tab of the AR System Email Mailbox Configuration form for the specified mailbox, or for the default mailbox, no copies of the email will be sent.
If you specify multiple recipients in the User Name field, the name or names specified in the CC and BCC fields on this form will appear only in the CC and BCC fields of the AR System Email Messages form entry for the first user listed in this User Name field. The permissions applied to the recipients of the CC and BCC fields will be the same as those of this first listed user. This might be a security issue, especially if you list a group name with some ambiguity about which is the first name on the list. You might list names individually in the User Name field so that you have more control over the permission status.
In the Organization field, enter a company name, an organization, a keyword, or a field reference to a name that you would like to appear on the email.

To define templates in email notifications

Use the Templates tab to define any templates to use in the email. If you leave these fields blank, the values in your notification email default to your current mailbox configuration settings. You could create a workflow that substitutes a specially designed urgent template to alert a manager to the email's importance. The following figure illustrates an email sent by the Email Engine if an urgent ticket is created and no user is assigned (( 'TR.Impact' = "Urgent") AND ( 'Impact' != 'DB.Impact') AND ( 'Assigned To' = $NULL$ )).

An Urgent email generated by the Email Engine

Best practice

A more "advanced" solution can use a Set Fields action to dynamically set template values using data-driven workflow on a transaction basis. For example, a filter could read a value from a hidden field on a form. By default, a notification would use a default header template. But if a ticket was marked Urgent, the workflow would substitute a value that uses the Urgent header template instead. For more information, see Using-templates-with-outgoing-email.

Open the Templates tab.
In the Header, Content, and Footer fields, specify the names of the templates to use for a header, content, or footer of the email notification.

You can enter the name of the template directly, or enter a field reference or keyword that leads indirectly to a template name. The templates specified here must be stored in the AR System Email Templates form, and the name must be the same as that entered in the Template Name field of the AR System Email Templates form. For more information about creating and using templates, see Creating-and-using-email-templates.

When you create a content template for_email notifications_, the variable format must correspond to a field's database name and not the field label.

If you are using a content template for email notifications and you want to see the notification text in the corresponding email, you must use the following variable format in the content template:
#$$AR Notification Text$$#
To create a content template to show Status History when doing email notifications, represent the Status History in the following formats:
#$$Status History.New.USER$$# #$$Status History.Closed.TIME$$#
These formats are based on AR System core field ID 7. The Status History strings shown here as examples could also be displayed languages other than English.
You cannot use AR System keywords in content templates for outgoing emails in notifications.
Click Add Action, and save your changes to the filter or escalation.
The system determines which templates to use in the following order:
1. The template entries on this tab.
2. The templates set as defaults for the mailbox entered in the Mailbox Name field of the Messages tab of the Notify action dialog box.
3. The templates set as defaults for the default mailbox.
4. No templates used.
  If no template is used for the Content, the order of fields included in an email notification is strictly based on their arrangement in the form view. Using their X and Y coordinates, the order of fields begins top left to right, then down (in a zigzag pattern). Fields excluded from the form's default view are randomly included at the bottom of the list. If a form includes page fields, the pages are ignored. The order of fields included in the notification is still based on their X and Y coordinates in the form.