Merge field expressions

Merge field expressions have a set of standard formatting requirements that allow the field to correctly pull information from the database.

These standard formatting requirements are:

• The expression cannot exceed 255 characters.
• The expression must be enclosed by ${ on the left and } on the right.
• The first part of the expression must be an attribute from the Entity class or any of its derived classes, such as Person, UserPerson, Company, Household, and so on.
• If a part of the expression is an association to another class (i.e., not a primitive), then the next part of the expression must be an attribute from the associated class or any of that class' derived classes. This continues to be applied to any depth in the expression, until the last part is a primitive type.
• Attributes that are collections must be written in the form <attributeName>[<index>], where index represents a value that is referencing an item in the collection by name.
• Attributes that are timestamps must be followed by a comma and at least one of the following elements:
  • d
    Displays the day number. For example, an integer between 1 and 31.
  • dd
    Displays the day number always with two digits. For example, the first day of the month would be displayed as 01.
  • M
    Displays the month number. For example, an integer between 1 for January and 12 for December.
  • MM
    Displays the month number always with two digits. For example, January would be displayed as 01.
  • MMM
    Displays the full name of the month. For example, November would be displayed as November.
  • yy
    Displays the last two digits of the year. For example, the year 2013 would be displayed as 13.
  • yyyy
    Displays all four digits of the year. For example, the year 2013 would be displayed as 2013.

Elements are case sensitive.

You may also add additional text before, after, or between elements. For example, use MMM d, yyyy to display a date in the format January 31, 2013 or MM-dd-yy to display the date in the format 01-31-13.

Merge field expression examples

The following is a list of examples of merge field expressions:

${firstName}
Returns the first name of the entity. firstName is an attribute of the Entity class.

${workPhone address}
Returns the entity's default work phone number. workPhone is an attribute of the Entity class that is associated with the Telcom class. address is an attribute of the Telcom class that returns a string (which, in this case, is a phone number).

${defaultAddress type name}
Returns the address type of the entity's default address. defaultAddress is an attribute of the Entity class that is associated with the Address class. type is an attribute of the Address class that is associated with the AddressType class. name is an attribute of the AddressType class that is a string containing the name of the address type.

${customFields[Spouse] entityValue firstName}
Returns the first name of the entity referenced in the "Spouse" custom field. customFields is an attribute that is a collection of the CustomField class. "Spouse" is an index used to identify the custom field, and corresponds to the custom field name. entityValue is the attribute of the CustomField class that is associated with the Entity class, and firstName is an attribute of the Entity class.

${currentTime, dd MM yyyy}

Returns the current date (day, month, and year). currentTime is an attribute of the Entity class.

${currentTime, yyyy}
Returns all four digits of the current year only.

A Boolean attribute causes the merge field to print Y if its value is true and N if its value is false.

For information about the different attributes that are available in merge fields, see the NexJ Class Model Reference.