In this topic:
Variables allow the administrator to create generic templates. Variables are used only with templates that are to be used as one of the following types of templates:
- User-defined instruction templates for incoming email.
- Result templates for incoming email.
- Content templates for new outgoing email.
Variables are placeholders that are replaced by specific values defined when:
- The user instruction is executed and where the values are defined by a user sending the email executing this user instruction.
- The template for new outgoing emails is used as a content template. The variables are defined by values of the fields in the entry that triggers the notification.
Variables can be used in place of values in the label/value pairs in templates. The variable is replaced by a value at execution time.
The variable is defined as follows:
When used in a label/value format, use the following syntax:
For more information about label/value formats, see Basic format.
The name of the variable can be the same as a AR System field, so there are no restrictions if used in the context of a AR System form. This allows you to use existing AR System field values to define the value of a variable. The variable value is retrieved from the same
!Field ID! label as that of AR System fields so the variable name might also be the name or ID of an existing AR System field.
In content templates used for outgoing emails, variables for field values must use the field database name, not the field ID. For specific examples, see Using variables with notifications.
For outgoing emails, the variable value is determined in the following order:
- Using the Attachment Alternatives tab. If you supply an attachment in the Values attachment field of the Attachment Alternatives tab of the AR System Email Messages form, the attachment is used to determine the values for variables contained in the template. For more information about how to do this, see
- If you do not supply an attachment in the Values attachment field, but supply information in Field Values, or obtain a value by using a qualification in the Qualification field of the Variable Replacement tab of the AR System Email Messages form, the information is used to determine values for variables contained in the template. For more information, see Using the Variable Replacement tab.
- If you do not supply field values, but your content template contains a query to obtain information to substitute in the email, the query information is used to generate the message. For query information to be used, a form, server, and qualification must be supplied. If any one of these items is missing, the message creation will fail.
The following example shows a field value used as a variable in a query or qualification:
Query:[$$'Last Modified By' = "User" AND 'Modified Date' > "#$$modified_date$$#"$$]
Inside the same template or defined in the user-defined instruction template received in email, this variable could be associated with a value as follows:
After the parser has extracted all the required information, the variable is replaced with the appropriate value, resulting in a query as follows:
Query:[$$'Last Modified By' = "User" AND 'Modified Date' > "21/01/2004"$$]
Variables can be used only for form field values and qualifications. They do not work for Login or Server labels. For example, the variable Login: #$$Joe User$$# would not be correctly parsed by the Email Engine and would return an unknown user error. Only local fields (fields after the Action label) can be substituted. Global fields (fields before the Action label) cannot be substituted. Labels like Server, Schema, Login, Password, or Key are considered to be global and cannot be substituted.
Using variables with notifications
When creating templates to be filled in using notifications, the template variables for field values must use the field's database name (not the field ID) as the variable name. This is because the server uses the field name (database name) to assign the values in the AR System Email Messages form.
For example, if the user has a template to mail out the user information through a notification that looks like the following, it will not work for notifications:
Login Name : #$$101$$# Password : #$$102$$# Group List : #$$104$$# Full Name : #$$8$$# Default Notify Mechanism : #$$108$$# Email Address :#$$103$$#
To use this template in notifications, the user must change it so that it looks like the following example:
Login Name : #$$Login Name$$# Password : #$$Password$$# Group List : #$$Group List$$# Full Name : #$$Full Name$$# Default Notify Mechanism : #$$Default Notify Mechanism$$# Email Address :#$$Email Address$$#
Add the following core fields to the template:
Req Id:#$$Request ID$$# Submitter:#$$Submitter$$# Create Date:#$$Create Date$$# Assigned To:#$$Assigned To$$# Stat:#$$Status$$# ShortDescr:#$$Short Description$$# StatHist:#$$Status History.New.USER$$#
Do not use the Request ID to return entries from display or vendor forms in a notification. If you construct a content template by using the
#$$Request ID$$# variable and use the content template in the Templates tab of notifications on display or vendor forms, the system will not generate errors, but it also will not return the Request IDs.
Date formats supported in email templates
Date and time formats supported by the email templates
A numerical date that includes the numerical month, day, and year (for example, 06/18/04). The order of each component is based on the Regional Options properties in the Control Panel.
Longer numerical date description, for example, Jan 12, 1952.
An alphanumeric date that includes the day of the week, month, day, and year (for example, Friday, June 18, 2004). The order of each component is based on the Regional Options properties in the Control Panel.
Completely specified numerical date description, for example, Tuesday, April 12, 1952 AD.
You cannot mix different locales for short and long formats. So, in the countries where the valid value is mm/dd/yy, dd/mm/yy is not valid and will not work, especially when the dd part is greater than 12. You can see examples of valid date format values when you open Regional Options on your Control Panel for long and short dates.
As a result, depending on your locale, 31/01/04 will work as a short date if your locale is set to dd/mm/yy, not mm/dd/yy. The format 31-Jan-04 will not work, but you can use Jan 31, 2004 or January 31, 2004.
The Email Engine uses reserved variables to place the results of executing an email. You can use reserved variables in Result and Status templates, but not in Content templates. Reserved variables fall under two main categories:
- Action information — Useful when creating a template that will contain the results of executing the associated action. They can be defined in a Result template with variables that define the fields of a specific form. The Email Engine will replace these variables with the correct values before the results are returned to the sender of the email containing the actions.
The following formats are valid:
- #$$Action.Name$$# — The action value, such as Submit or Query.
- #$$Action.Number$$# — The position of the action within the entire execution list.
- #$$Action.Form$$# — The name of the AR System form involved in this action.
- #$$Action.Query$$# — The qualification (if any) associated with the instruction. (This reserved variable is valid only for User Defined Instruction templates.)
- Status information— Used to store the results of system-generated errors. The following formats are valid:
- #$$ActionStatus.Number$$# — The error or warning number.
- #$$ActionStatus.Type$$# — The type of error, such as Severe, Error, Warning.
- #$$ActionStatus.Text$$# — The message text.
- #$$ActionStatus.AppendedText$$# — The associated appended text.
These are also values that you would define in a status template; they are common to all forms. The following figure displays an email that includes these reserved variables for status information. This particular email uses the HTML status template found in Types of email templates.
Reserved variables for status information used in outgoing email
(Click the image to expand it.)
The following rules apply for specific Status History information in the templates:
- You must use the fully qualified status history name, for example:
- You can also use numeric values, for example:
15.0.USER Status-History.0.USER 15.New.USER
- The USER and TIME identifiers are case sensitive.