Making Dynamic Communications Templates with Smart Data

The IDI platform Communications module gives your users the ability to send and receive emails right where they are doing their work. This process will be made easier by pre-defining message templates for your users which can ensure consistency, quality and ultimately speed up task times.

Templates also can be used in Workflow when you want to send pre-defined automated messages based on system events or Workflow tasks.

Creating Templates

An email template typically is composed of three common elements:

• Pre-defined text

• Smart Data elements

• Placeholder for user-added message (if template is for manual communications)

Templates are created in the Communcations Module.  When you are creating a new template the Type you select determines what Smart Data elements are available to work with in your message.

Smart Data

Smart Data allows you to create a Communications template that uses placeholders for information that will get filled in when the template is used. For example, when sending a customer an email about a Ticket you can use a placeholder for Ticket Title in the Subject line that will get replaced with the actual Title.

For example:

This allows you to create templates for your users that dynamically pull in relevant information based on the tasks they are working on.

Using Smart Data in a Template

Adding Smart Data into your template is accomplished simply by clicking the button in the toolbar and selecting the data element you want to use.

When creating your templates, you can use a mixture of fixed text and Smart Data to deliver the desired message.

For example:

The Smart Data elements in this example are underlined. The red text section is used to provide your users an indicator when they send the email where they are supposed to tailor the message to the individual situation.

What the user sees when sending the email:

Your users can now just highlight the section in red, replace it with a description of the information they need and hit send.

Data Lookups

When the information you want to pull into a template is not available in the supplied Smart Data elements you can still use Data Lookups to find the values you need.

Data Lookups allow you to use the information that is available automatically in the template (e.g. customer id) to look up other information in the IDI platform (e.g. Account Name).

Data lookups are a very powerful tool and they can extend the Smart Data that is available for you to use in your templates to a wide array of values.

Data Lookup Example

To illustrate how to use Data Lookups we will use an example of pulling in the name of the customer contact and the customer account number into a template.

Step 1: Looking up Contact Name

To get started with Data Lookups, create a new template (type = Ticket) and enter your fixed text into the template. At the point you want to use a Lookup value place your cursor and click the Smart Data button, this time selecting Data Lookup.

Data lookups are organized by the items in the IDI platform that you can pull information down from. To find information for a contact on a Ticket we need to browse to the Ticket lookups.

Select the Ticket Lookup

Clicking on the Tickets lookups displays a drop-down with all the possible information about a Ticket that we can use. In his case we want the Contact name so we select ContactFullName

Select the ContactFullName Value

Now that we have picked the field we want to use we must tell the system which Ticket we want to pull the information from. Behind the scenes Tickets are stored and uniquely identified by the JournalItemID Field. To make sure we are getting the right Contact Name we want the system to use the record where the JournalItemID is equal to our TicketID.  Clicking the data insert button to the right of the field display a list of all of the data elements that are already supplied in the template.  From here you can just select TicketID from the list.

Set filter = TicketID

Hit Select and the new Smart Data element is added to you template:

Step 2: Looking up Account Number

Looking up account number will follow a similar process. This time we will select CustomerSummary lookups. The property we want to pull in is AccountNumber. The account record in CostGuard that we want to pull the Account Number for is the one where the CustomerID is equal to the CustomerID associated to the Ticket.

Users selecting this template on a Ticket will see the new Smart Data elements with the right values pulled in:

Adding Links to your Templates

You can add URL links to your templates that use Smart Data. This will allow users to open a web page right to the referenced item in the email when they click the link.

Adding a link is made simple since many of the URLs in the IDI platform use a common stem and then end with the object id of the item that is being viewed. For example, the page to view a Ticket will always look like this:

https://api.idibilling.com/tickets/<environment>/#/ticket/<ticketid>

In your template, you would replace < environment> with the environment you are working in and <ticketid> with Smart Data. You do not have to add any additional URL tags or special syntax, just type the URL stem and then use the Insert Smart Data button.

When the recipient receives the email their email client will automatically format the URL as a clickable link.

Creating Your Own Data Lookups

Creating your own Data Lookups can be useful when the data you need is already available however the default filters that are provided do not meet your needs.

For example, there is a Lookup for pulling in values from an IDI platform user account when you know the user name:

This works great if we have User Name to work with but what if only have the User ID?

We can create our own Lookup to allow us to find User information by User ID by going to the Workflow module and then Configure -> Data Lookups

Choose to ‘Create Data Lookup’, give it a name and select User as the Data Source.

Add your own Filter Condition and since we want to be able to lookup User properties when we know the User ID select UserID. Since the actual User ID we are looking up will be supplied later when we are actually using the Lookup you can uncheck ‘Set Value Now’.

Now when we are working with Smart Data Lookups we can pull in properties of the IDI User Account, such as their configured email address, based upon knowing what their User ID is and not just their User Name.

Using a Data Lookup within Your Data Lookup (Nesting)

Sometimes the Smart Data you want to pull into a template is not readily available to you just by using the values that are provided. For example, using CustomerID we can get the User ID of the Account Manager assigned to an account but we cannot get this user’s name. To get the name of the account manager we need to Lookup the configured First Name and Last Name on their User Account.

So how do we get to the name of a customer’s account manager when the template only providers us the Customer ID? The answer is in the example below.

Example: Using Nested Lookups to get Account Manager Name

The Communications templates provide CustomerID when you send an email. Using this we will:

• Use CustomerID to Lookup the User ID of the account manager assigned to the customer

• Use the User ID of the account manager to Lookup the First Name and Last Name assigned to the user account.

Step 1: Create a Lookup for UserbyUserID

We will need to create a Data Lookup which will allow us to get User information when we only know the User ID. See the previous section Creating Your Own Data Lookups for details on how to do this.

Step 2: Get the Lookup syntax for Account Manager User ID

We need to get the syntax for Looking Up the User ID of an Account Manager using the CustomerID that we are supplied. This Lookup string is ultimately what we are going to nest into another Lookup but that doesn’t mean we must create it by hand. We can use the Insert Smart Data button in the template to provide the right syntax for us.

Step 3: Add Lookup for Account Manager First Name

Now we need to create Lookups for the account manager’s First Name:

• Start by cutting (Control – X) the User ID lookup underlined in the diagram above so that it is in your clip board.

• Click the Smart Data button again and this time select your new UserbyUserID Lookup. Select First Name as the property you are pulling in and then paste your User ID Lookup in the filter.

  

This gives us our nested Lookup.

To review the what we did:

• We started with CustomerID

• Found the Account Manager User ID by matching on our Customer ID

• Found the First Name of the Account Manager by matching on our User ID

Step 4: Add Lookup for Account Manager Last Name

Repeat the steps however this time choose to pull in Last Name from the UserbyUserID lookup. You now will have successfully used nested Lookups to pull in Smart Data into your template.

Using Templates in Workflow Triggers

Send Message From Template is a Workflow Action that allows you to send an email based upon a Trigger in the IDI platform. For example, you can notify an account manager when a new account is created or notify a customer when a Ticket has been resolved.

The key to using the Send Message From Template Action is to ensure that you map any Smart Data that you are using in your template to the properties that are being specified in the Trigger.

Example: Notify Account Manager on Customer Created Event

This example will demonstrate how to use Workflow Triggers to automatically send an email based upon a Customer Created event.

Step 1: Create Template

To create a Trigger that will email an Account Manager when a Customer is created we will start by defining the template we want to use. For this example, we created a Template with a Type = Customer and use the following Smart Data

• CustomerID

• AccountNumber

• Account Name (via a Data Lookup)

Step 2: Add Trigger

To notify the Account Manager will go into Workflow and Create a new Trigger. The Trigger we need is Customer Created and for this example we are not going to add any filters.

Step 3: Add Action

The action we need to send the account manager an email is Send Message From Template.

The Parameters on the Action are filled out as follows:

From: Use the email addressed configured for your Communications module

To: To get the email address for the Account Manager we will need to use a nested lookup. You can reference the example in the section above Using Nested Lookups to get Account Manager Name and just change the value you are pulling in to the user’s email instead of name.

Template: Select the template created in step 1

Data: This is the trickiest part. We need to make sure that all the Smart Data that we used in the template gets mapped to the properties being sent on the Customer Created Trigger.

To do the mapping we start with the list of Smart Data used in the template:

• CustomerID

• ACCOUNTNUMBER

Data Lookups we used do not need to be included in the mapping however the property specified in the Lookup filter does. In this example, we used a Lookup for AccountName with a filter property of CustomerID. Since CustomerID is already on our list to map we do not need to do any additional work for AccountName.

The format for mapping Template Smart Data to Trigger Properties is:

{“<template smart data property>”:<trigger property>}

Note:

• Entire mapping field is encapsulated in curly brackets { }

• Template Smart Data field name is encapsulated in double quotes “ “

• Colon separates Template Smart Data from Trigger property :

The mapping for CustomerID in the template to the CustomerID property on the trigger would look like this then:

{“CustomerID”:@[CustomerID]}

The easiest way to enter this into the action is to type the Template Smart Data field into the Action and then use the data insert button to add the correct Trigger Property you are mapping to.

We also need to map ACCOUNTNUMBER. We can add this by following the same format and separating it from the CustomerID mapping with a comma.

,”ACCOUNTNUMBER”:@[AccountNumber]

The final field looks like this

Link Reference ID: Use this if you wish the email you are sending to be linked to the customer account. The Link Reference ID is the system ID for the item you want the email to be associated to.

In this example, we want to link the email to the customer account that was created so the field is set to the CustomerID received on the Trigger.

Link Reference Type: Lets the system know what type of item in the IDI platform you are linking the email to. In this instance, we want to set the type = Customer.

Using Templates in Workflows

Like using a Template in a Trigger, using one in a Workflow requires you to ensure you can map the supplied properties into the template Smart Data that you use. For a Workflow, the supplied properties are determined by the Extended Data in your Workflow definition.

Example: Notify Account Manager Workflow Task

This example will demonstrate how to add a Workflow task that will automatically email the Account Manager regarding a new customer account.

Step 1: Create Template

We can use the same template from the Trigger example above. This is a template with a Type = Customer and it uses the following Smart Data

• CustomerID

• AccountNumber

• Account Name (via a Data Lookup)

Step 2: Create Workflow Definition

Our example will assume that notifying an Account Manager is part of a Order Workflow. When you create a new Workflow definition with a type of Order you automatically get the following Extended Data:

We will need to ultimately map CustomerID and AccountNumber into our template so we need to add those fields as User-Defined Extended Data.

Adding User-Defined Extended Data

The CartID will automatically be populated in the Workflow when the Order is submitted. We can use this to lookup the CustomerID and AccountNumber associated to the Order via the Order Data Lookup.

To do this add your Extended Data field ‘CustomerID’ , type = integer, and use the Data Lookup to pull in the CustomerID value from the associated Order.

Repeat this step, this time for AccountNumber

Step 3: Create Workflow Task

At the step in the Workflow you want to email the Account Manager add an automated task using the Send Message From Template action.

The Parameters on the Action are filled out as follows:

From: Use the email addressed configured for your Communications module

To: To get the email address for the Account Manager we will need to use a nested lookup. You can reference the example in the section above Using Nested Lookups to get Account Manager Name and just change the value you are pulling in to the user’s email instead of name.

Template: Select the template created in step 1

Data: This is the trickiest part. We need to make sure that all the Smart Data that we used in the template gets mapped to Extended Data properties on the Workflow.

To do the mapping we start with the list of Smart Data used in the template:

• CustomerID

• ACCOUNTNUMBER

Data Lookups do not need to be included in the mapping however the property specified in the Lookup filter does. In this example, we used a Lookup for AccountName but the filter property of used is already on our list.

The format for mapping Template Smart Data to Extended Data Properties is:

{“<template smart data property>”:<trigger property>}

Note:

• Entire mapping field encapsulated in curly brackets { }

• Template Smart Data field encapsulated in double quotes “ “

• Colon separates Template Smart Data from Extended Data property :

The mapping for CustomerID in the template to the CustomerID property on the Workflow would look like this then:

{“CustomerID”:@[CustomerID]}

The easiest way to enter this into the action is to type the Template Smart Data field into the Action and then use the data insert button to add the correct Extended Data Property you are mapping to.

We also need to map ACCOUNTNUMBER. We can add this by following the same format and separating it from the CustomerID mapping with a comma.

,”ACCOUNTNUMBER”:@[AccountNumber]

The final field looks like this

Link Reference ID: Use this if you wish the email you are sending to be linked to the customer account. The Link Reference ID is the system ID for the item you want the email to be associated to.

In this example, we want to link the email to the customer account that was created so the field is set to the CustomerID used on the Order.

Link Reference Type: Lets the system know what type of item in the IDI platform you are linking the email to. In this instance, we want to set the type = Customer.

 Common Smart Data / Data Lookup Questions

Why do none of the Pre-Defined Smart Data Elements match the Lookup I want to use?

The pre-defined Smart Data elements are determined by the Template, Workflow Trigger or Workflow Action that you are working with. For example, a Communications Template for a Ticket has Ticket info pre-defined, an Adjustment Trigger has Adjustment info and a Workflow for an Order has Order related extended data.

When using a Data Lookup, you can only utilize the ones where the data you have will allow you to lookup additional information that you want to pull in.

For example, trying to pull in an Adjustment Reason into a Ticket email will not work because just using the information on a Ticket the system cannot determine what individual Adjustment record you want to pull information from.

What if I don’t see the Lookup I need?

You can build your own Lookups in Workflow using the existing data sources that are provided (see above section Creating Data Lookups). You set they filters you wish to use for the Lookups which can provide different paths to get the values you need. If there is data in the IDI platform that you wish to use and you do not see it as available to work with then the IDI Product Idea portal can be used to enter a suggestion for it to be added.