1. Implementing Your Agency
  2. Using Attributes in Communication Templates

Using Attributes in Communication Templates

You can add attributes to your communication templates when defining the recipients and content.

You insert attributes into your communication templates on the Communication Event Details page, which you access by selecting an event from the list on the Communication Event page. You can select from attributes in the resource for the event you're working with, contact type attributes, and additional attributes available from other resources.

Note: Contact type attributes are not available for ad hoc emails, notifications, and texts in the Communication Center because the communication must be associated with a transaction to populate contacts. Parent resource attributes from an event are also not available in the ad hoc communications template in the Communication Center.

The endpoint attributes of communication service REST APIs correspond to the variables you use to set up a communication template. For a reference document that directs you to the endpoint attributes and their descriptions in the REST API documentation, see Public Sector Communication Services Endpoints Catalog (Doc ID 2755859.1) in My Oracle Support.

Adding Predefined Variables for Attributes

When you create a template, you can insert variables for attributes into the message fields. Predefined variables for attributes are available to use for communications associated with any event. For example, using the contact types in the communication template, you can send communication to the contacts listed on the application.

You insert attributes listed under Resource attributes to retrieve values you find in fields on applications that are referenced in the parent resource. Contact type attributes are especially designed to gather contact information from applications referenced in the resource of the selected event.

  1. On the Communications Event Details page, go to the Add Attributes fields.

  2. Select the field and the attribute that you want to add to the field.

  3. Click Insert.

For example, if you select Body and the Permit ID attribute, and click Insert, the ${Permit ID} variable is inserted into the Message Body field of the communication template. When the application generates a communication using the template with the variable attribute, the permit ID that is associated with the triggered communication event is inserted into the body text.

Here’s an example of a letter template and the output:

Example Expressions with Variable Attributes

Output

Dear ${Payer First Name} ${Payer Last Name},

Thank you for your payment of ${CommunicationUtils.formatNumber(${Payment Amount},’9,999,999.99’)} for permit ${Permit Id}, which was received on ${CommunicationUtils.formatDate(${Payment Date})}.

If you have any questions please contact the office between 9:00 a.m. and 4:30 p.m., Monday through Friday.

Dear John Smith,

Thank you for your payment of $835.00 for permit REM-2017-000035, which was received on 15-AUG-2017.

If you have any questions please contact the office between 9:00 a.m. and 4:30 p.m., Monday through Friday.

The communication engine supports the following predefined functions for variable attributes in your templates.

Function

Description

Variable Attribute

Output

Current Date

Returns the system date in the agency time zone without the time. There is no need to use the format utility.

Note: The Current Date is internally formatted using the formatDate() function based on the agency time zone. Using an additional formatDate() function causes an error.

${Current Date}

For example, 2016-04-25.

Current Date Time

Returns the system date in the agency time zone with the time. There is no need to use the format utility.

Note: The Current Date Time is internally formatted using the formatDate() function based on the agency time zone. Using an additional formatDate() function causes an error.

${Current Date Time}

For example, 2016-04-25 23:44:52.0.

Format Number

Formats the number to the given format. The formats supported are Java Number Formats.

${CommunicationUtils.format('number', ${Fees Total Amount},'###,###,###')}

To support backward compatibility, the following format is currently available:

${CommunicationUtils.formatNumber($Amount, '9,999,999')}

For example, 46,064.

Format Date and Time

Formats the date and time in the agency time zone with the given format. The supported formats use Java Simple Date Format.

Example 1: ${CommunicationUtils.format('datetime', ${Creation Date},'yyyy-MM-dd HH:mm:ss')}

Example 2: ${CommunicationUtils.format('datetime',${Creation Date})}

Example 3: ${CommunicationUtils.format('date',${Creation Date},'yyyy-MM-dd')}

To support backward compatibility, the following formats are currently available:

Example 4:

${CommunicationUtils.formatDate(${Creation Date},'yyyy-MM-dd HH:mm:ss')}

Example 5:

${CommunicationUtils.formatDate(${Creation Date})}

Example 1 output: 2019-11-22 20:04:00.

Example 2 output: 11/22/19 8:04 PM.

Example 3 output: 2019-11-22

Example 4 output: 2019-11-22 20:04:00

Example 5 output: 11/22/19

Format Amount

Formats the amount into the default local currency format.

Example 1: ${CommunicationUtils.format('amount',${Fees Total Amount})}

Example 2: ${CommunicationUtils.format('amount',${Fees Total Amount},'en_US')}

To support backward compatibility, the following format is currently available:

Example 3:

${CommunicationUtils.formatAmount(${Amount})}

All the examples produce the output: $1,345,667.00

Link

Provides the hyperlink from the message.

Input is expected to be the link URL and the label that you want to display:

${CommunicationUtils.format('url',${URL},${Label})}

${CommunicationUtils.format('url',${URL},’Setting Up Communication Events’)}

To support backward compatibility, the following format is currently available:

${CommunicationUtils.setLink(${Url},${Label})}

The examples produce the output: Setting Up Communication Templates.

Add Grid

Inserts a table in the message body

This applies to specific communication templates where the Add Grid functionality is enabled.

${CommunicationUtils.format('grid','publicSectorFeeDues','Assessed Date, Currency Code','${AssessedDate},${FeeCurrencyCode}')}

To support backward compatibility, the following format is currently available:

${CommunicationUtils.insertGrid('publicSectorFeeDues','Assessed Date, Currency Code','${AssessedDate},${FeeCurrencyCode}')}

Inserts a table inside the communication message.

Guidelines for Using Formatting Functions

When you are creating or updating communication templates, follow these guidelines to review and edit the usage of the formatting functions such as setLink(), formatAmount(), formatDate(), and insertGrid() in the message:

  • Creating New Template: You must use only format() functions as defined in the above table.

  • Updating Existing Template: Currently, the system supports single references to these formatting functions for a given communication. The communication will not be triggered if there are multiple usages of these formatting functions within the communication definition. So, to avoid any errors in the communication delivery, you must update the templates to ensure the usage of only format() functions.

  • Nesting format() functions: Currently not supported.

  • Format() to display grid: This is a special format function that handles the date and amount attribute formatting as per agency setup options. So, there is no additional format() allowed for grid attributes.

  • Using the $ symbol in message: To include a ‘$’ character into the message text, you prefix the ‘$’ with the character ‘\’ (backslash key). This enables the communication processor to read the ‘$’ character as a string, and not as an attribute.

Using Contact Type Attributes

After your agency sets up contact types, you can insert variables for contact type attributes when composing communications for contacts by type, as well as for primary contacts or all contacts. For example, you might set up the system to send contractors a copy of the email sent when a permit or planning application is withdrawn. In this case, you would create a template for a withdrawn event with an Email or Emails and Notifications channel type, and insert the email variable for the Contractor contact type attribute in the email Cc field. You can insert variables for contact attributes into the address fields as well as the subject line and message body.

Here are the available contact type attributes and examples of the variables:

  • Email: Inserts a variable for the email address of contacts with the specified contact type. Select this attribute to send emails. This example shows the variable for email addresses of all contacts:

    ${CommunicationUtils.insertContactType('publicSectorApplicationContactTypes','AllContacts','${ContactEmailAddress}')},

  • Phone: Inserts a variable for the phone number of contacts with the specified contact type. Select this attribute to send texts. This example shows the variable for phone numbers of primary contacts:

    ${CommunicationUtils.insertContactType('publicSectorApplicationContactTypes','Primary Contact','${ContactPhoneNumber}')},

  • User ID: Inserts a variable for the user ID of contacts with the specified contact type. Select this attribute to send notifications. This example shows the variable for user IDs of contractors:

    ${CommunicationUtils.insertContactType('publicSectorApplicationContactTypes','Contractor','${ContactUserId}')},

  • User Name: Inserts a variable for the name of contacts with the specified contact type. You can select this attribute to insert the user's name in the message body to personalize the communication, such as "Dear Linda." This example shows the variable for user names of business owners:

    ${CommunicationUtils.insertContactType('publicSectorApplicationContactTypes','Business Owner','${ContactUserName}')},

For information about setting up contact types, see Setting Up Contact Types.

Inserting Additional Attributes in Templates

Some attributes are available across resources for you to use when creating templates. You can insert a grid in the message body that contains the additional attributes. This option is available only for events in the Permits Workflow Communication resource. Formatting is not supported for related resource attributes.

The data for the attributes are displayed in the generated communication as a table. To add the grid to your template:

  1. Select Communication Setup > Communication Events in the Navigator.

  2. On the Communication Event page, select an event in the Permits Workflow Communication resource for which you want to add a template.

  3. Click Add in the Communication Template grid on the Communication Event Details page.

  4. Set up the communication properties as described in Setting Up Communication Templates.

    You must use the Emails, Emails and Notifications, or Notification channel type, and the MIME type must be HTML to render the grid in the generated communication.

  5. Click Add Grid.

  6. On the Define Grid Attributes page, select up to 5 attributes that you want to appear in the generated table. The attribute source name appears on the page.

  7. Click Insert Grid in Message.

For example, if you select the Fee Description, Fee Item, and Fee Record attributes, and click Insert Grid in Message, the following is inserted into the Message Body field of the communication template:

${CommunicationUtils.insertGrid('publicSectorFeeCommunications','Fee Description,Fee Item,Fee Record','${FeeDescription},${FeeItemId},${FeeRecordKey}')}

Each attribute name is displayed in the generated email or notification as a column title, and record values populate each row. If you want to change the order of the columns, you can manually move the attributes around in the template.