Defining a workflow to send email notifications

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.

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 three tabs — Fields, Messages, and Templates — that are used to define the configuration and contents of your email message.

The Email Engine must be running to enable you to send email notifications. You can set some configuration options in the Create Filter (or escalation) dialog box when you create a Notify filter or escalation to customize your email.

To define a workflow to send email

Make sure that you have an outgoing mailbox configured with Default Outgoing Mailbox set to Yes, or set Mailbox Name in the workflow to the configured outgoing mailbox. Otherwise, you will not receive any notifications.
For more information, see Configuring-outgoing-mailboxes.
Create your Notification filter or escalation.
Click the If Action tab or the Else Action tab.
From the New Action list, select Notify.
The Notify Filter (or escalation) page of the Create Filter (or escalation) dialog box is displayed. The fields required to define the Notify filter or escalation appear.
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 BMC Remedy AR System functionality in the text of an email notification. The figure that follows demonstrates 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.*
This URL appears in the notification email as a link that the user clicks to display the ticket in a browser.
A direct access URL used in email notification
(Click the image to expand it.)

For more information, see URLs-for-forms-and-applications.
In the User Name 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 are entering 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 BMC Remedy 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.
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.
To set properties in the EmailDaemon.propertiesfile so that the Email Engine sends high-priority emails first and then lower priority emails, change the following property as shown:
*SortMessages=true*
For more information, see Email-daemon-issues-when-AR-System-server-stops.
From the Mechanism field, select Email.
The Fields, Messages, and Templates tabs are activated.
Select the Add Shortcut check box to include the originating request as an ARTask attachment in the email that is sent.
Save the filter or escalation.

Defining fields in email notifications

Use the Fields tab to define the subject line of the email and to indicate which fields (if any) to include in the body of the email.

Subject line and fields in an email notification
(Click the image to expand it.)

To define the Fields tab

Enter the text that will appear in the subject line of the email.
Subject text can include the use of keywords, for example, $USER$. The field or keyword will be expanded when the notification is sent. If you enter a field name in the Subject Line field, the notification will contain the value of the field in the database. You can enter a maximum of 255 characters.
Select which fields have the content you want to select in the email (in addition to the notification text).
Note
The Request ID of entries from display or vendor forms are not returned in notifications.
The options are:
- 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.
  Note
  If you use a content template to format the email, the template will override any of the options that are selected. For example, if an administrator selected All, but the template only uses a few fields, only the fields in the template appear in the email.
  Make sure that all fields used as variables in header, footer, and content templates are selected in the Include Fields list of the filter. (For more information, see Variables.)
  To be able to send the field contents, make sure that users being notified have the necessary form and field permissions. See Access-control.
  The order of fields included in an email notification is strictly based upon 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-like 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 actual X and Y coordinates in the form.
To include attachments in an email notification, select the attachment fields from the Fields list.
Including attachments with notifications
(Click the image to expand it.)

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

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

The Messages and Templates tabs

The Messages and Templates tabs 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.

Defining 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.

To define 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 BCCfields:
- 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.

Defining 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 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
(Click the image to expand it.)

Tip

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, workflow would substitute a value that uses the Urgent header template instead. For more information, see Dynamically-assigning-templates-to-outgoing-email.

To define 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.
Note
You cannot use BMC Remedy 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 in 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 are used.
  If no template is used for the Content, the order of fields included in an email notification is strictly based upon 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.