Using variables in email templates

You can use the variables 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 an AR Systemfield, so there are no restrictions if used in the context of an AR System form. This allows you to use existing AR Systemfield 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:

1. 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. 
2. 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.
3. 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.

For more information, see Using-advanced-features-on-the-AR-System-Email-Message-form.

Variable examples

The following example shows a field value used as a variable in a query or qualification:

Inside the same template or defined in the user-defined instruction template received in the 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:

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 Engineand 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:

To use this template in notifications, the user must change it so that it looks like the following example:

Add the following core fields to the template:

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

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.

Reserved variables

The Email Engineuses 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 Enginewill 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, or 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

The following rules apply for specific Status History information in the templates:

• You must use the fully qualified status history name, for example:

  Status-History.New.USER Status-History.New.TIME

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