How to Debug a Workflow

Debugging Workflow Errors

Written by: Vincent Colantuoni, Technical Support Engineer @ Kustomer

One of the most versatile features of the Kustomer platform are Workflows. Workflows can automate a variety of tasks and processes in your platform by creating rulesets that trigger certain actions based on predefined conditions. While incredibly powerful, due to the complexity of the feature, a variety of errors and unintended events can ensue if a Workflow does not run as expected.

There are several different types of errors that you might encounter within a Workflow. Additionally, while some Workflow issues are not related specifically to errors, there are situations where you might have seen a Workflow only partially complete or travel down the incorrect flow. Understanding these types of issues and how to account for them can help make your Workflows more accurate and less likely to deviate from the intended path.

Workflow Actions & Conditions

Before going into specific types of Workflow errors, it would be important to touch on view logs; which are imperative when troubleshooting Workflow errors. In a blog post from a few weeks ago, we discussed the concept of view logs and how to dig through them in order to create Workflows. In addition to what is discussed in that article, Workflow logs are also vitally important when troubleshooting any issues you encounter related to your Workflow. For more on how to access view logs as well as the types of data they can speak to, you can reference the blog post linked above.

Our help center also contains information related to using these logs as well as Workflow errors to debug issues. There is a good amount of overlap with the contents of this article and viewing that information here will provide great context to general troubleshooting of Workflow errors. While that article goes into how you can troubleshoot general issues, we will be more granular below regarding specific issues you may run into and how you can verify an issue in your Workflow even if it might not have registered as an error.

The Workflow below is designed to add an ‘Email Team’ tag to new conversations that come in through that channel. Additionally, this will also do the same thing for chats with a ‘Chat Team’ tag. 

If we have our view logs activated at the time the Workflow runs, we can verify the steps the Workflow ran through inspecting the view logs related to that interaction. In the screenshot below, we can verify that the Workflow made it to its final step and added the tag to the conversation as we can see both steps of the Workflow were successful. In cases where we have a Workflow that branches into different paths, we can also verify the specific path the Workflow traveled through based on the steps highlighted in the logs.

In instances where a Workflow does not run as expected, we can generally see one of three scenarios come into play:

Scenario 1: The Workflow does not satisfy a condition


In these scenarios, a Workflow would not have reached the end of one of its branching paths. As we can see on this Workflow, each branch will have a total of two action steps it would have had to run through in order to fully complete. In this case, the Workflow logs only display one action step completed. Therefore, you would want to check the conditions the Workflow should have run through and verify where a discrepancy could have been encountered from the data sent through the view logs. For larger Workflows, this would be the branch of conditions directly after the last action step completed.

Scenario 2: The Workflow travels down the incorrect Workflow path


In some cases, upon inspecting the Workflow’s view logs, you might observe the Workflow traveling down an unintended path. This could be due to one of two reasons:

  • The first (intended) path of the Workflow was not satisfied, so the Workflow ran down the next available path.
  • The Workflow satisfies multiple conditions in the same condition branch. In these cases, the Workflow will travel down the condition it satisfies closest to the left of the condition branch, which might not be the branch you intended for it to travel down.

The fix for both of these would roughly be the same: You would want to ensure that in a specific scenario, a Workflow’s condition branch has diametrically opposed options. For instance, if a condition branch looks for the only channel on the conversation to be either email or chat, there would never be a time where a conversation would qualify for more than one branch. For branches where multiple satisfactions are possible, you will want to make sure the branch that serves as the ‘dominant’ option is closest to the left side of the branch.

Scenario 3: The Workflow writes the incorrect information through an erroneous configuration


It would also be possible for a Workflow to run successfully, but possibly write the incorrect data into an attribute or leverage the correct data in a condition step of the Workflow. This may also occur for one of two reasons:

  • The source of the data is not what you initially expected it to be. 

  • The attribute from the Workflow used to satisfy a condition or write into a field is linked incorrectly. For instance, when verifying a conversation ID in a Workflow, the condition might be configured to accidentally pull a customer ID instead.

To solve these issues, you would want to make sure the data set to populate in an attribute or verify in a condition is linked appropriately through verifying the step and attribute the data is tied to. This can be done very easily through the code view of the data as seen below.

Additionally, you would also want to ensure the data itself is as expected from the source you are pulling it from through these same steps.

API Errors (Path/Data/DataType)

Within Workflows, you also have the ability to create action steps which can call either the Kustomer API or other external APIs. This can be incredibly useful when needing to verify information from another system, or perform other operations outside of the traditional scope of normal Workflow action steps. This makes our Workflows feature exponentially more powerful, but like everything we have discussed thus far, things can error out. For this reason, it would be worth our time to go over the types of API errors you may receive in your Workflows.

Below is a Workflow that uses a REST API JSON step to make a call to the update conversations API endpoint, adding a 'Conversation Complete' tag to Conversations that have been marked as done.

API errors in Workflows can be a little more hidden than many traditional Workflow errors as they lie within the API call itself as opposed to the Workflow. Additionally, API call action steps may appear as running successfully even if the intended configuration is not happening. When looking at view logs, click on the API step. The output portion of the logs will show you the results of the API call.

The fact that this API call resulted in a statusCode of 200 is great as this generally indicates that a successful call was made! Different statusCodes will show in this output related to a more specific issue that the API call might have encountered. For instance, a statusCode of 401 indicates that there was an issue with the authorization of the call, meaning you will likely want to check the API key being used to make the call. A 400 error might indicate that some aspect of the call is not formatted correctly, such as the data or URI. You would want to ensure all of the code related to the call is correct per the API documentation before troubleshooting further. For more information on the status codes you may encounter with our API, you can view our documentation on the topic here.

One other type of issue you may encounter is that the API call might not be processing your request as expected. For instance, if you are trying to update a conversation attribute through this API call, the call will still show as successful even if the data portion of the API call’s payload is empty. This is because the API was still able to successfully communicate with the intended server. The same logs above would be able to tell you exactly what was configured through the call and these types of issues are able to be troubleshooted further from there.

Recursive/Looping Workflows

One other type of error you might run into with your Workflow is finding that it continuously runs. This is what we commonly refer to as recursive Workflows. For instance, if you have a Workflow that triggers on a conversation update to update another attribute in a conversation, this type of output action would also be considered a conversation update, triggering the Workflow to run again. 

An example of this would be a Workflow that creates a note on a conversation when the conversation is updated. Because not creation is also a conversation update, this would trigger the Workflow to run again, creating a new note, triggering the Workflow again, and so on. 

Should you find a Workflow to unintentionally run multiple times, the first thing you will want to do is to turn off the Workflow to cut the loop. From there, you will want to build in conditions to prevent the Workflow from running subsequently. For instance, when updating an attribute in a brand new conversation, you might want to add a condition to verify if the attribute at the time of it updating is currently blank. This would allow me to update the attribute once, and will prevent the Workflow from running additional times as the attribute will have a value when it attempts running additional times.

As powerful as Workflows are, they may often be confusing, especially to a person who did not initially build a Workflow. Through understanding the different types of issues that could affect a Workflow’s intended operation, you can best arm yourselves to find the breaks in the Workflow that may prevent it from working as intended. If you have any general questions about how to better understand Workflows as a whole, or need assistance with debugging an issue yourself, feel free to reach out to or visit our knowledge base at Kustomer University is another great resource, with videos and tutorials to help you better utilize everything Kustomer has to offer. You can find both the knowledge base and KU on the home page of our community as well.