Defining a Notify action for email, alerts, or other applications

Use the Notify action to send specified users or groups an email, an alert, or an alternate method outside of AR System server. For example, a filter can notify support staff that they have been assigned a new request, or an escalation can notify a manager that a request has not been handled within the specified time.

You can use the Notify action in:

Filters
Escalations

Alerts are stored in the database, and users can view them in the alert list. Email messages are sent through the Email Engine, which supports the SMTP, MAPI, and EWS mail protocols for outgoing messages. You can also write notifications to a file for use by another application.

To define the delivery mechanism, recipients, and contents

Right-click the If Action or the Else Action panel header.
Select Add Action > Notify.
In the Mechanism field, select the notification mechanism:
- Alert—The specified users are notified with entries in the Alert Events form. Users can view their list of alerts and open the originating requests.
- Email—The notification is sent to the specified recipients by email. You can identify AR System server recipients by their AR System user or group names, or enter email addresses to notify any recipient inside or outside of AR System server.
  Important
  - For the email notification mechanism, the Login name field on the User form takes precedence over the Email field.
  - When you specify an email address in the User field of the Notify action, that email address is considered as an external email address if the email address not available in your environment as a Login name.
  - We recommend avoid using email address as Login ID.
- User Profile Default—The specified users are notified using the default method specified in their User form record.
- Cross Reference—The specified users are notified with the mechanism specified by an integer or selection field in the current request. Use this option to determine the notification method at runtime. For more information, see Using a dynamic delivery method.
- Other—The specified users are notified using the mechanism specified in the Other Code field. In this case, the notification is written to a file. Use this option to create your own delivery method. For example, you can set up your system to page users when they receive a notification. For more information, see Using an external delivery mechanism.
In the Priority field, enter a number from 0 through 10 to set the priority.
The priority appears in the Priority field of the Alert Events form to allow the user to sort the alert list by priority.
In the User field, enter information to identify the recipients of the notification.
The user field is limited to 255 characters. If you enter more than one recipient, separate each recipient by entering a hard return (press Enter). The server evaluates each line separately.
To specify one or more recipients, enter the recipient information in any of the following formats:
- AR System user names
  - Alert notifications are entered in the Alert Events form, with the user name appearing in the User field.
  - Email notifications are sent to the email address specified in the User form entry for the user.
- AR System group names—AR System server takes the group name from the entry in the Group form, searches the User form for all users belonging to this group, and delivers the notification for each member.
  - For Alert notifications, an entry is made in the Alert Events form for each group member.
  - Email notifications are sent to the email address specified in the User form entry for each user.
    For more information about users, groups, and the User and Group forms, see:
    - Creating-and-modifying-users
    - User-and-group-access
      Best practice
      To broadcast a notification to a large group, we recommend that you send the notification to a mailing list or alias on the email server, instead of using an AR System server group. This avoids the need to create all the notifications on the AR System server, which can impact performance.
- Email addresses—In addition to obtaining the email address from the User form, in filters you can enter email addresses directly or by using a keyword, such as $USER$. This allows the Notify action to send messages to users outside of AR System server, including aliases or an email address that represents a program.
  Include the email domain name in the address, for example, Joe.User@calbro.com or $USER$@calbro.com.
- A field reference, AR System keyword, or expression—To allow the notification recipients to be determined at runtime, enter an expression using field names or keywords:
  - Type a dollar sign ($) and select the field name or keyword from the content assist list, or click the ellipsis to open the Expression Editor dialog box. For example, to send a message to the user who created the request, enter $Submitter$.
    Entering a field name indicates that the name of the user or group to notify is in that field in the current request. You must create workflow to populate the field. The field can contain one or more recipients in the form of a user name, group name, or email address, separated by hard returns. The field cannot contain another field reference.
    Make sure that the data entered in the User field at runtime does not exceed 255 characters. If it does, the notification might not be delivered to some recipients.
    When you select a keyword, the current value of the keyword is substituted at runtime.
    To resolve the contents of the User field, AR System server first checks for a matching request in the User form. If found, the notification is sent to that user. If not found, the server checks for a matching request in the Group form. If the name corresponds to a group name, the notification is sent to all members of that group.
    If the contents of the User field do not match an existing User or Group definition, AR System server interprets the field contents as a literal address and sends the notification to that address, using the SMTP, MAPI, or EWS mail protocols.
In the Text field, enter the content of the notification message.
The size limit for this field depends on the notification type. There is no limit on the message content in an email notification. For an Alert notification, enter no more than 4000 characters.
To include field values or keyword values in the notification text, use the Expression Editor dialog box or the content assist feature to select fields and keywords from the list. You must enter field names and keywords in the variable format, for example, $Short Description$. For information about using the expression editor, see Using-buttons-and-menu-bar-items-to-execute-active-links.For every recipient, on the notify action, the values of Fields, Subject and Text fields are parsed depending upon the access to the corresponding fields.
For example, if Text = Subject $Short Description$ and the recipient does not have an access to the $Short Description$ field, then the text for that recipient is displayed as Subject:.

Notify action example

The following figure shows an example of a Notify action. In this example, the user in the Assigned To field of the current request will receive a priority 1 notification by either Alert or an email message, depending on the default set in the recipient's User form record.

If the notification is an Alert, the contents of the Text field will appear in the Alert Text column of the Alert List, including the name of the submitter and the time stamp. If the notification is an email, the subject line will include the request ID, and the contents will include the contents of the Text field, along with a URL to the request, and the contents of the request's Short Description field.

Example Notify action

To enter additional email information

For all notification mechanisms except Alert, optional fields appear in the Notify action for email-specific information. In addition actions set for Email in the Mechanism field, Notify actions configured for User Profile Default, Cross-Reference, or Other can also generate email notifications. The fields described in this procedure are ignored for Alert notifications.

In the Subject field, enter a subject for the message.
You can include field and keyword values in the subject. The maximum length for the subject is 255 characters. If the value replacing a variable at runtime causes the Subject field data to exceed 255 characters, the subject is truncated at 255 characters. If you enter a field name in the Subject Line field, the notification contains the value of the field in the database, up to 255 characters.
For some UNIX email systems, you can include extra header lines in your email message by inserting hard returns followed by formatted mail headers in the Subject field. The resulting notification contains a Subject Line and your header lines. However, the total of all data in the Subject Line field must be 255 or fewer characters.
(Optional) Select a shortcut option to add a link to the request in the email message:
- AR Task—Adds an AR Task attachment to the email notification.
- Web URL—Includes a URL to the request in the email notification. The URL allows the user to open the request in the web client.
  To use a Web URL, you must define the web path in the Email Notifications Web Path field on the Advanced tab of the AR System Administration: Server Information form. For more information, see Setting-performance-and-security-options.
From the Fields list, select an option to control the addition of request data in the message body of the email notification:
- None—None of the fields is included in the notification.
- All—All of the fields in the request are included in the notification.
- Selected—Selected fields are included in the notification. Click Add to open the Field Selector dialog box and select the fields to include.
- Changed—Only fields that have changed in the current transaction are included in the notification.
  If you include field contents, AR System will check the field permissions to the notification's subject and body.
  Ensure that the user has permissions to access the fields mentioned in the Fields list.
  By default, the order of fields included in an email notification is based on their arrangement in the form view, as follows:
  - Fields are taken from the default form view. If there is no default view, the first view is used.
  - Ensure that the user has permissions to access the fields mentioned in the Fields list.
  - Using the X and Y coordinates of each field, the order of fields begins at the top left, and moves 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 in a notification.
  - You can only include data fields in an email. Other field types such as panel fields are ignored.
    To guarantee the order of fields in a notification, create a special view named ARNotification. Exclude any panel fields from this view; otherwise, notifications default to the default view.
To view additional email-related fields, click Show Unused Fields. Use these fields to override default parameters relating to the email system. For information about these parameters, see Defining-an-email-notification.
Save the Notify filter or escalation action.

Using a dynamic delivery method

To determine the notification method at runtime, select Cross-Reference in the Mechanism field. For more information, see To define the delivery mechanism, recipients, and contents. With this option, users are notified based on the numerical value in an integer or radio (selection) field in the current request.

When you select the Cross-Reference delivery mechanism, another field appears in the filter or escalation named Reference Field. Enter the field variable for the referenced field in this field, for example, $DeliveryType$. Only integer fields and radio fields appear in the Field Selector dialog box.

To populate this field at runtime, you must also define workflow that inserts a numeric value between 0 and 4 in this field, or sets the equivalent radio field value, at runtime. In a radio field, the first option has a value of 0, the second a value of 1, and so on. These values represent the following delivery mechanisms:

0—Do not notify
1—Alert
2—Email
3—User default

Using an external delivery mechanism

To use a delivery method that does not use Alert or the Email Engine, select Other in the Mechanism field. For more information, see To define the delivery mechanism, recipients, and contents.

When you select the Other delivery mechanism, the Code field appears in the filter or escalation. Select a value from 4 through 98 in the Code field to indicate the delivery mechanism to use.

With this option, the notification is written to a file in the following path:

Windows—arInstallDir\arserver\db\notification NN.arn, where NN is the number in the Code field.
UNIX—arInstallDir/db/notification NN.arn, where NN is the number in the Code field.