See related
No related articles

Workflow helpers

Last Update: Sep 2024 • Est. Read Time: 7 MIN
To check plan availability, see the pricing page.

You can use workflow helpers to automate tasks in your workflows. The basic workflow helpers include String Interpolation, Date, Random Id, and Type Conversions. The more advanced workflow helpers are Each, If / Else, and Conditionals.

Who can access this feature?
User typesAdmins can configure workflows.


In this article

Prerequisites

Basic workflow helpers

As you build out workflows, you may want specific fields to be more customizable. Some common examples are addressing a customer by name in the body of an email, setting an auto-response date, or formatting data coming in via a webhook. This functionality is made possible with workflow helpers, which can be used within condition and action steps.

String interpolation

String interpolation is a versatile workflow helper because it allows you to access any data attribute and surface it according to your use case. For example, when performing a Customer lookup action, you have access to all attributes provided in the JSON, and you can view these attributes using the workflow logs.

The standard structure of this workflow helper looks like such:

{{{steps.1.ATTRIBUTE_NAME}}}

If we wanted to address a customer by name in the body of an email, the Body field in the workflow would look like this:
It is important to remember that the step number will correspond to the ID of the specific lookup action.

If we need to access data that has been passed into a workflow via a hook, the structure of the helper looks like this:

{{{steps.1.attributes.data.ATTRIBUTE_NAME}}}

Date

The date workflow helper is most commonly used for time comparisons and auto-responses. Using auto response as an example, you may want to add a custom date field to track the last auto response date.

Here is an example of different options for setting the date, and how it can be adjusted to fit your needs:

  • {{{date 'hours' count=24}}} resolves to 24 hours ago
  • {{{date 'day' count=1}}} resolves to 1 day ago
  • {{{date 'day' count=0}}} resolves to the current day

Random ID

Random ID can generate a more user friendly ID (only a few characters) instead of the longer ID associated with a conversation. A common use case is to set an external ID each time a conversation is created. This external ID can be shared with the customer if they are inquiring about a specific issue.

Here is an example of basic usage and how to set a specific size:

  • {{{randomId}}}
  • {{{randomId size=10}}}

Type conversions

The type conversion workflow helpers are mainly used to format data that is coming through a webhook properly. We want to ensure that the data is processed properly within the Kustomer platform to prevent a workflow from failing.

  • dateDiff allows you to compare two dates and output the result using the following structure: {{dateDiff "days" from=date1 to=date2}}. The from date will be the older date and the >to date will be the newer date. If you want to compare against the current date, you can leave out the to part of the helper. For example, if you wanted to use a conditional to see if a conversation was marked done more than 7 days ago from today, the helper would be {{dateDiff "days" from=steps.1.lastDone.createdAt}} in the first part and "greater than 7" in the second part.

    The following longhand units of time are supported:
    • years
    • months
    • weeks
    • days
    • hours
    • minutes
    • seconds
    • milliseconds

  • /#fn:inBusinessHours allows you to check if the current time is within Business Hours. The helper with either return true or false and is most commonly used in condition steps when creating an Auto Response workflow. You can set your business schedules by going to Settings  > Administration > Business Schedules.

  • /#fn:dateFormat allows you to convert a date into the appropriate format that can be processed within the Kustomer platform. For example, an order date comes in as "2018-5-4". To convert this to the proper date format, using /#fn:dateFormat,steps.1.attributes.data.orderDate will result in the correct format of "2018-05-04T00:00:00Z".

  • /#fn:isValidEmailAddress validates if the input is a valid email address. This will ensure you do not try to create/update a customer in a workflow with an invalid email address, which will cause the workflow to fail. For example, an email address comes in as "support@kustomer". The validation will return false when using /#fn:isValidEmailAddress,steps.1.attributes.data.email. If the email address is "support@kustomer.com", this validation will return true. This validation would specifically be used in a condition step.

  • /#fn:isValidPhoneNumber  validates if the input is a valid phone number. This will ensure you do not try to create/update a customer in a workflow with an invalid phone number, which will cause the workflow to fail. For example, a phone number comes in as "73255". The validation will return false when using /#fn:isValidPhoneNumber,steps.1.attributes.data.phone. If the phone number is "732555555", this validation will return true. This validation would specifically be used in a condition step.

  • /#fn:parseFloat allows you to convert the string version of a number into a number with decimals (float). For example, the price of an order comes in as "10.50". To convert this value to a float, using /#fn:parseFloat,steps.1.attributes.data.price will result in a value of 10.50.

  • /#fn:parseInt allows you to convert the string version of a number into an integer. For example, the price of an order comes in as a value of "10". To convert this value to an integer, using /#fn:parseInt,steps.1.attributes.data.price will result in a value of 10.

  • /#fn:URIDecode decodes a string. For example, to decode a value like Hello world! that is stored as a conversation's name, you could use /#fn:URIDecode,steps.1.attributes.data.name will result in a value of 10.

  • /#fn:URIEncode  encodes a string. For example, to encode a value like Hello, world! that is stored as a conversation's name, you could use /#fn:URIEncode,steps.1.attributes.data.name.

  • /#fn:parseJSON allows you to convert the string representation of a JSON object into a literal JSON object. For example, consider the following stringified object "{\"foo\":\"bar\"}". To convert this value, /#fn:parseJSON,{\"foo\":\"bar\"} will result in the literal object { foo: "bar" } being passed to this reference within a workflow step input or workflow action definition. When a string is passed to the parseJSON function that cannot be interpreted as an object, the function returns an empty object by default.

Format dates with Moment.js

dateFormat allows you to convert a date into the appropriate format, which takes in optional input parameters. This workflow helper uses Moment.js, a library that lets you parse, validate, manipulate, and display dates, so you can use any of the formatting parameters listed in their documentation.

You can find Moment.JS in the following resources:

The dateFormat workflow helper outputs dates in UTC. If you have an order date for 1/14/2022, you will get 2022-01-14T00:00:00.000Z. The syntax you need to output the correct format will look like: 

/#fn:dateFormat,steps.1.attributes.data.orderDate 

It takes in an optional input parameter that uses moment.js so you can use any of the format parameters that are listed on their website. 

Here are examples of different formats you can use with moment.js:

  • /#fn:dateFormat,steps.1.attributes.data.orderDate,mmm resolves to Jan 
  • /#fn:dateFormat,steps.1.attributes.data.orderDate,dddd resolves to Thursday
  • /#fn:dateFormat,steps.1.attributes.data.orderDate,LL resolves to January 14, 2022

Advanced workflow helpers

As you build out workflows, you may want to populate a specific field based on a condition. While in the Basic workflow helpers section, we were only adjusting the value of a field, the workflow helpers covered in this section will allow for more advanced functionality. A few examples are setting a condition based on what email address a message was sent to or creating a custom note based on a custom attribute.

Each

The each workflow helper allows you to take an array of objects and concatenate a specific attribute from each object into one string. A common use case is assigning a conversation to a team based on the email address the message was sent to. Within a message object, the sent to email addresses are held in their object, which requires us to use the workflow helper.

For example, let's say a user sent an email to both "support@company.com" and "billing@company.com". In the JSON, the data would look like this:

steps.1.meta.to = [ { email: ‘support@company.com’ }, { email: ‘billing@company.com’ }]

The corresponding workflow helper is:

{{#each steps.1.meta.to}}{{this.email}} {{/each}}

Within the workflow, we can test whether the email string contains 'support@' and then create specific actions based on this condition. Most commonly, organizations will assign a specific team to handle the conversation.
You can create multiple condition branches based on the emails you want to check.

If / Else

The if/else workflow helper will first check to see if the value of an attribute exists and then display the specified text accordingly. One important note is that this helper only checks to see if the value exists; it does not check for equality.

A common use case is to create a note with a specific message based on a custom attribute. In this example, we have a custom attribute "VIP" and a custom attribute "Fraud". The structure of the workflow helper will be:

{{#if steps.1.custom.vip}}Check VIP{{else if steps.1.custom.fraud}}Check Fraud{{else}}{{{steps.1.name}}}{{/if}}

The helper will output Check VIP if the custom "VIP" field exists. If not, the conditional will output Check Fraud if the custom "Fraud" field exists. Otherwise, it will evaluate the name property. Keep in mind that {{else}} and {{else if}} are also optional.

Basic Conditionals

Conditional helpers take the if/else helpers one step further by allowing you to check if a specific value exists. This conditional allows for more granularity, which allows you to create more custom actions. Based on our earlier example, we can output a specific message if a customer is VIP or not (designated by true/false boolean value).

The structure of the workflow helper will be:

{{{cond steps.1.custom.vip true='Customer is VIP' false='Customer is not VIP'}}}

If the custom VIP attribute is true, the conditional will output 'Customer is VIP'. If the VIP attribute is false, the conditional will output 'Customer is not VIP'.

These types of conditionals can also be used to check the value of a string attribute; and multiple values can be checked as a part of the conditional:

{{cond steps.1.custom.country USA='United States' CA='Canada' MX='Mexico'}}

Conditionals using multi-level lists

We can also implement conditionals in conjunction with multi-level lists. This allows you to create custom messages based on a specific field chosen by the agent.

For example, an org has a 'Custom Resolution' field for each conversation. Level 1 of the list is 'CX Education', with 'Customer Support' and 'Knowledge Base' as the Level 2 fields. We want to display a custom message based on what is chosen in Level 2.

The structure of the workflow helper will be:

{{{cond steps.1.attributes.data.contactResolutionTree [cx_education.customer_support]='Custom support message' [cx_education.knowledge_base]='Custom knowledge message'}}}

If 'Customer Support' is chosen in the MLL, the conditional will output Custom support message. If 'Knowledge Base' is chosen, the conditional will output Custom knowledge message.

One important note is that each field in the list is identified by its ID. To find the ID, make an API call to /v1/metadata/conversation.

Math

The math workflow helper allows using basic arithmetic operations like addition within a specific workflow step. The full list of supported operations can be found below:

operation
input
output
addition
{{math "9" "+" "4"}}
13
subtraction
{{math "9" "-" "4"}}
5
multiplication
{{math "9" "*" "4"}}
36
division
{{math "9" "/" "4"}}
2.25
modulo
{{math "9" "%" "4"}}
1


It's important to note that the math workflow helper returns a string data type. To use a real-world example, if you are looking to calculate something like a customer's lifetime value so that your agents can take some action if a customer's LTV is greater than X, then you'd have to convert the returned value of the math workflow helper to a number data type using one of the other helper methods like /#fn:parseInt. This can be accomplished as follows:

  1. Use the math workflow helper within a regular expression action step to return the string value of the operation. The regex string shown below (.*) captures the output of the mathematical operation.
  2. In the subsequent Customer Update step, set the appropriate customer attribute equal to /#fn:parseInt of the returned regex match.