Tutorial: Creating a Workflow

Workflows are a power tool available to Kustomer administrators using our Business, Enterprise, and Ultimate plans. This article will give an overview of how to create a basic workflow that will post a note on a conversation timeline if a CC’d address replies to an email, letting your agents know that a reply came from an address other than the one that was originally used to send in an email. 

By the end of this article, you’ll have a better understanding of how to work with the workflow editor UI, how to make basic API requests, how to use the String Interpolation workflow helper, and how to use the workflow Debug Logs.

To get started, we need a trigger step. A trigger is a defined event that will cause the workflow to run. To recap, the goal of our workflow is to identify when a reply comes in from an email address that is different from the original email address. Since we are trying to capture something that happens when a new message comes into Kustomer, Message: Created would be our best option. To select this option, set the Trigger App to Kustomer and the Trigger Event to Message: Created using the drop down menus on the right side of the workflow editor. Like this:

You can learn more about our other workflow triggers here. 

When we use the Message: Create step as our trigger step, we are now able to reference any information available on the newly created Message object. To figure out what information is available, we can make a simple API request. Before doing so, it’s highly recommended that you install a JSON beautifier extension like this one. JSON beautifier extensions will make it easier to read JSON data, and will help with visualizing its structure.

Once you’ve installed a JSON formatter, open a new tab in your web browser, and send in a test email to your support email address to create a new conversation in Kustomer. Then, navigate to the newly created conversation in Kustomer. Click on the URL, and copy everything you see after /event/ like this:

The string of letters and numbers you just copied is the ID of the conversation. This is how the conversation is referenced on the backend of our product.

Once you’ve copied the conversation ID, click on the URL in your web browser and format it like this:

https://subdomain.api.kustomerapp.com/v1/conversations/conversationId

Replace subdomain with your org’s subdomain, which is the text that comes before “kustomerapp.com”. In the example screenshot above, the subdomain is “zzz-charlotte-lesly”.

Paste in the conversation ID that was copied earlier where it says “conversationId”. It should look something like this:

Once the URL has been formatted correctly, hit “enter” and you’ll be able to see the data associated with the conversation in our API. Since we want to view information about the messages associated with the conversation, we will change the URL slightly to access the Messages Endpoint.

https://subdomain.api.kustomerapp.com/v1/conversations/conversationId/messages

Once you’ve formatted the URL, hit “enter” and you’ll be able to see all of the data associated with the messages on the conversation. It should look something like this:

This is the JSON formatted data associated with the message that came into Kustomer. JSON uses a Key: Value structure to describe objects. The Key, or attribute, is the type of information, whereas the Value is the information itself. For example, in the above Message object you’ll see “subject”: “CC Reply Test”, this means that the subject of the message was “CC Reply Test”. You’ll also see “direction”: “in”. Because the message came in to Kustomer (it came from a customer and not an agent), its direction is in.

JSON data can also be nested, meaning some data is encased in other data. You’ll be able to tell when this occurs by evaluating the indentation of the data. Take a look at the meta attribute. 

Notice how the from attribute is slightly more indented than the meta attribute. 

This indicates that the from attribute is contained by the meta attribute. Similarly, look at the to attribute and then the email attribute. Based on their indentation, you can see that the email attribute is inside the to attribute, which is inside of the meta attribute.

Now that you have a better idea of JSON structure, we can get back to filling in the workflow, so go ahead and navigate back to the tab where you were editing your workflow.

With selected Message: Create as our workflow trigger, we can access any attribute listed in the Message object. We now need to determine which messages should this run on. Since we want to know if incoming messages are coming from a CC’d sender, then our best option is to have this only run on inbound messages. If we had it run on all messages, then the workflow would take outbound messages from your agents into consideration, which isn’t the functionality we are looking for. 

To limit the types of messages the workflow runs on, we should add a condition that specifies to the workflow that it should only run on inbound messages. To do so, click the + sign under the Message: Create step and select Condition Step. Then use the drop down menu on the right side of the editor to create a condition like this:

In this condition, we are referencing the Direction attribute of the inbound message, and since we only want inbound messages to be checked, we are making sure the Direction equals In.

Now that we’ve specified the types of messages we want to process, we need to be able to tell who the original sender was in the conversation. The Message: Create trigger step only gives us access to information about a newly created message, so we aren’t able to tell who the original sender of the conversation was. We’ll need to look up more information about the conversation associated with the newly created message to see who the original sender was. We can do this by adding a Conversation: Lookup step like this:

In this Conversation: Lookup step, we’re referencing the conversation attribute associated with the new message that came in to get more information about it.

Now that we’ve looked up the conversation, we’re able to access any information available to us on the Conversations Endpoint. To see what’s available, navigate back to the URL below in your other tab

https://subdomain.api.kustomerapp.com/v1/conversations/conversationId

By clicking on the back button in your browser. It should look something like this:

If you scroll down a bit, you’ll see an attribute called firstMessageIn like this:

Based on the name of the attribute, we can tell that this attribute contains information about the first inbound message on the conversation. If you look at the meta attribute inside of the firstMessageIn attribute, you’ll see a from attribute, which tells us the email address the first inbound message came from.

Now we have two important pieces of information that we can use in our workflow to determine whether or not a reply came from a CC’d address. We have the from address from the newly created message, and the from address from the first message that came into the conversation. If these two addresses aren’t identical, then it’s safe to assume a CC’d address sent the new message.

We can input this logic into the workflow by creating a new condition under the Conversation: Lookup action that checks if those two addresses are equal. Since we are working with nested attributes, we’ll have to enter in the information slightly differently than we did in the first condition.

First, use the drop down menu to select the firstMessageIn attribute from the Conversation: Lookup step like this:

This will reference the entire firstMessageIn attribute, but we only want to reference the from attribute, which is inside of the meta attribute. 

To accomplish this, all we need to do is click on the “<>” icon and add “.meta.from” to the inputted code. Adding the periods and attribute names creates a path the workflow can follow to find the correct information. The condition should look something like this when you’re finished: 

/#steps.oqGp4DfAG.firstMessageIn.meta.from

Don’t worry if the text between steps and firstMessageIn are different from the above, that’s just the workflow action ID which will differ from workflow to workflow.

Underneath the code we just entered, change the quantifier to Not Equals. In the field below, we want to reference the from attribute associated with the message from the Message: Create step. Since it’s inside the meta attribute, we’ll need to make sure we map that as well. To do so, enter in the following:

/#steps.1.meta.from

The “/#” indicates to the workflow that we are referencing data from a previous workflow step. The “steps.1” indicates that we are referencing data from the trigger step, and the “meta.from” is the attribute mapping. Once you’ve entered in the code, the completed condition should look like this:

Now that we’ve added a condition that checks whether or not the addresses are different, we need to add an action to take if they are different. In our case, it’s going to be a Note: Create action.

Use the drop down menu in the conversation field to select the conversation from the trigger step like this:

In the body field, we can add whatever we want our notes to say. It would be useful to know the new sender’s email address, so we can use the String Interpolation workflow helper to add that information to the body. We know that the from address from the newly created message can be found in steps.1.meta.from, so to add that information to the body of the note, all we need to do is add this to the body field:

{{steps.1.meta.from}}

You can add that to text that already exists in the body. So in total, your note body could say something like this:

CC Reply from: {{steps.1.meta.from}}

The above is just a suggestion of what your note could say, but you can customize the body field to say whatever works best for you.

With the Note: Create action fully configured, go ahead and save the workflow and then turn it on. Once you do, any messages that come from an email address other than the one used initially will generate a note indicating who the message came from like this:

To test out the workflow, first open the workflow debug logs like this and wait for the dot next to Debug Mode to turn green. 

When Debug Mode is turned on, a log of all of the actions a workflow took after it was triggered will be captured like this:

The last step a workflow process took will be included in all of the logs, but to get more granular, you can click on one of the logs to see all of the actions that took place. You’ll also be able to see the input and output of each workflow step. This is what I see when I click on Log Event 1:

In another tab, send another email to your support address, and CC another address in the email. Then, have that CC’d address reply to the email, making sure that your support address is included in the reply. Once the CC’d address has sent an email, wait a minute or two for the email to come into Kustomer, and then click on the refresh button next to the green dot to refresh the log.

When you refresh the log, you may see quite a few entries, depending on the amount of messages that are created in your org at any given time, but you should be able to find an event where the Last Step is Note: Create. If you aren’t seeing one, then there may be a configuration issue with your workflow, or the workflow may not be turned on.

If all of your entries’ Last Step is Message: Create, then there may be something wrong with the condition before the Conversation: Lookup step. If all of your entries’ Last Step is Conversation Find By Id, then the condition before the Note: Create might be the issue. Playing around with the workflow logs should give you a better idea where things are going wrong.

If you did find a log where the Last Step is Note: Create, then go ahead and find that conversation in Kustomer, and you’ll now see a note created on the timeline letting you know that the email came from a sender other than the original sender!