How to utilize Data Objects in a workflow

The Kustomer platform uses an extensible data model to allow users to store, manage, and interact with their data across multiple processes and applications. There is perhaps no better way to use that data than in a workflow. To get the most out of workflows we must first understand Kustomer’s data structure and how it relates to workflows. 

Kustomer utilizes a combination of objects and arrays to organize the data in standard and custom objects and allow the user to easily extract specific data points. 

In this blog, we’re going to work through a real-world troubleshooting example and show you how to use the debug and error logs to help create a functioning workflow. 

Before we dig into how to use these data objects for workflows, we need to review some of the commonly used terms. 

JSON

JSON is a lightweight data-interchange format consisting of

• A collection of name/value pairs. These are referred to as objects

• An ordered list of values. These are referred to as arrays

Name/Value Pairs

A name-value pair consists of a specific data value (for example, a monetary value or a true/false value) and a name that is used to identify that value 

Example: 

‘totalRevenue’: 114.23

Arrays

An array is a data structure that contains a group of elements. These elements are typically the same type of attribute and share similarities. You can think of an array as a list of attributes. Arrays can contain objects, strings, numbers, or even other arrays. Each item in the array can be targeted using the index, which is the order in which it appears in the list starting at 0. The first item in the list is at index 0, the second item is at index 1, and so on and so forth. 

Example:

‘customers’: [

‘John’,

‘Amy’,

‘Ali’,

‘Dana’

];

To pull Ali’s name from the array to use elsewhere, you would access it by using the following syntax: customers[2].

Because Ali is the 3rd name in the list, they are at index position 2 (0, 1, 2). 

Objects

An object is an abstract data type that can include multiple properties and methods and may even contain other objects and arrays 

Example:

exampleObject: {

‘Name’: ‘John’,

‘vipCustomer’: true,

‘orderNumbers’: [

123,

456,

789

]

}

In Kustomer we have both standard and custom objects.

Standard Objects

Standard Objects are the base set of objects installed on every organization providing applications with an extendable customer-centric data model.

The main list of Standard Objects installed for all organizations include:

1. Company

2. Customer

3. Conversation

4. Message/Note

5. Events

KObjects

KObjects, are objects that organizations can use to extend the base data model of the application. KObjects allow organizations to store information specific to their business and link to customer records or any other standard or KObject.

Klass

To create a KObject, an organization needs to define a set of attributes and relationships that will be used for all objects. This is done through a class definition called a Klass. A Klass is composed of the attributes that combine to make up the definition of all instances of that Klass. Klasses are uniquely identified by a Klass name that is used to reference KObjects and Klass definition across the product. 

All Klasses include a common set of attributes including:

• externalId - identifier that uniquely identifies a specific kobject across a single klass 

• title - a short string title of the object

• description - a long string description for the object

• images - an array of image URLs

• Rev - revision number used for optimistic locking purposes

For more details on the Kustomer data model, see our data model documentation

Example of Kustomer’s JSON structure

User Data

Notice how this ‘user’ object contains other objects and arrays within it

Targeting specific attributes in an object

Properties

An object has properties within it. A property is typically a variable that is linked to an object. The properties of an object make up the characteristics of that object. We are able to target specific properties by using what is referred to as dot-notation

Dot-Notation

Dot-notation is how we access a property of an object. To use dot-notation, write the name of the object, followed by a dot (.), followed by the name of the property. This process can be repeated several times until you get to the specific property you wish to access. 

For example, if I wanted to get the customer’s name from the customer object below, I would use customer.name. If I wanted to get the model of the customer’s car I would use customer.car.model

‘customer’: {

‘name’: ‘John’,

‘email”; ‘john@email.com’,

‘car’: { ‘make’: ‘Toyota’,

‘model’: ‘Prius’,

‘color’: ‘blue’

}

}

Camel Case

The practice of writing phrases without spaces or punctuation, indicating the separation of words with a single capitalized letter, and the first word starting with either case. Camel case helps ensure we are correctly targeting properties and values by ensuring we are all using the same syntax

example: camelCase

Example of how to access a property in a JSON object

In this example we want to utilize a conversation’s data to see when the first message in that conversation was sent 

To access that property we would use dot-notation and camel case to say data.attributes.firstMessageIn.sentAt to get the value of that property (2022-03-17T11:24:34.819Z)

Within the context of a workflow, we would be able to use that timestamp in another workflow step to achieve a specific outcome.

Using data in a workflow

Workflows allow us to do a large number of automations with our data. When we understand the data structure we can easily pull specific data points from an object and use it to complete specific tasks.

We are going to look at the app-created postmark-message-receive workflow to show how data can be used between workflow steps.

• This workflow is triggered by an email message being received in Postmark. 

• That message will have a JSON payload that contains all of the relevant data. From there, we are able to pull specific attributes from that payload to use for each step in the workflow. 

• When we open the debug log we can see the output from step 1. This contains the message’s JSON data from the email and helps us to clarify what attributes are readily available 

• Step 2 of the workflow is trying to look up an existing customer based on their email address. In order to do that, we need to enter an email address in the required fields section. We can look up the customer who sent in the email by getting their email address from the output in step 1.

•  If you click on the ‘<>’ symbol above the required field you can see the dot-notation used to get that attribute. This can also be accomplished by clicking on the dropdown list of attributes and selecting the appropriate property from step 1 

• Moving on to the output of step 2, you can see that we now have access to the customer’s data that we looked up. You will notice that the several attributes are stored in an array to allow for multiple values to be added (emails, phones, shared emails, etc.) In order to get the value of a property within an array we will need to use dot-notation while also targeting the specific index within that array. In order to get the primary customer email address you would use /#steps.2.emails.0.email 

• Make sure to check the ID of the step that you are targeting because they have unique IDs that need to be used in place of the actual step number

• If you want to use Kustomer data in a message body or some other text field you can dynamically add it by using handlebars notation and excluding the forward slash and pound sign before your do notation string (/#) 

  • {{{steps.1.ATTRIBUTE_NAME}}}

  • https://kustomer.d.pr/oVB1AD

Workflow Logs

To get a better understanding of the data being ingested by your workflow we can look in either the debug log or error logs to see what kind of output you are getting 

Debug Log

• You can open the debug log by clicking on ‘view logs’ on the bottom left portion of your workflow editor

• This will open the logs and allow you to see each event that passed through the workflow. 

  • Successful events will have a green circle next to them

  • Failed events will have a red circle and result in an error appearing in the error log

• If you click on an event you can expand it and see the input and output for each step of the workflow.

  • This is useful because it allows you to see what data your workflow has access to each step along the way.

  • This is the best way to troubleshoot workflows 

Error Log

• When viewing the list of workflows, you can see which ones have errors by looking for the red text that displays the total number of errors present

  • Clicking on that red text will open that workflow and bring up the error log

• Like the debug log, clicking on an error in the error log will expand the error and allow you to see the output of each step of the workflow.

  • The step in which the error occurred will provide you with details on the error instead of the output, since that step was unsuccessful

Example of troubleshooting using logs

• This is a simple workflow made to demo how to use data objects in a workflow and what to do if the workflow returns an error

  

• When testing the workflow with the debug log on, we can see that we are getting an error, signified by the red circle and the 400 status code

• When we click on that event in the debug log we can get more information on the error.

  • We are now able to see that error is being caused by a bad parameter. 

  • That means that the next step in the workflow is trying to perform an action using a data input, but the data being used for that step is incorrect

• If we click on ‘step 2’ we can investigate the field that is causing the error and what value is being passed into it. 

  • I can see that we are trying to plug in an email address by using the from address from the last inbound message in the conversation. The dot-notation for that is /#steps.1.lastMessageIn.from

• The next step we should take would be to go back to the debug log and take a look at the JSON data being outputted from step 1.

  • We need to search through the data to find the lastMessageIn object and see if we are making a mistake in the way we are retrieving the property we need or if the data itself is not correct

  • After viewing the lastMessageIn object, it is clear that the ‘from’ attribute is actually within another object, called ‘meta’

• After reviewing the output of step 1 we now know that the ‘from’ email address is present in the data, but we were not targeting it correctly. Now we need to change the dot-notation for step 2 so that it matches /#steps.1.lastMessageIn.mata.from

  

• When we save the workflow and test it again, the debug log now shows the workflow was successful and the customer was updated. 

  • It is usually smart to double check all of the steps of a successful workflow event when testing to make sure that everything is working as expected. 

  • The lack of an error does not guarantee that the data is being passed correctly

For more information, you can always reach us by emailing: support@kustomer.com