Troubleshoot Module Workflow Errors
The Tonkean module builder is designed to simplify the customization and configuration process, but sometimes errors and unexpected behaviors arise. The first step to troubleshooting these issues is always to understand what's happening, and for that, navigate to the Module Event History screen. On this screen, you can view a detailed history of recent events and runs that have been processed by the module, including detailed information about each action, trigger, and field.
View and Filter Module Event History
The first step in identifying errors or unexpected behavior in your module workflow is to view the module event history. The Module Event History screen displays the recent history of a module in the selected environment. You can view input data source records the module has received, module items, and each run the module has performed.
View Event Types
You can view any of three event types in the left panel of the Module Event History screen:
Data Sources - Input data source records monitored by the module. These events represent a data source record being created or updated in the intake source. For example, if your intake source is a Google Drive folder, the addition of a new file in that folder would display as a data source event.
You can select a data source event to view all the fields in the data source record, whether those fields are mapped and used in the module or not.
Module Items - Module items generated and processed by the module. These events represent the creation of or updates to items in the module. For example, if your intake source is a form, you would see the addition of newly-submitted forms and updates to those form fields as module item events.
You can select a module item event to view all the fields collected for the module item for a given event.
Flow Runs - Instances of an item running through the module workflow. These events represent each time a module trigger is activated and is processed by the workflow logic that follows the trigger. For example, if your intake source is an Intercom instance, you might have triggers for both when a new Conversation is created and when a reply is added to an existing Conversation; activation of either trigger creates a flow run event.
You can select a flow run event to view the Flow Investigation for that event, including which trigger was activated and what logic after it successfully ran or failed.
The Flow Investigation is a key tool when troubleshooting module workflows.
Filter Event History
There are various ways you can search and filter the Module Event History beyond selecting the Event Type:
Search History
Search by item name or ID in the provided search bar.
Specify Date Range
Filter events by date and time range using the provided Date fields. The maximum date range is six months.
The second Date field defaults to Now, the present day.
Filter Results
Select the filter button, , to filter events by various parameters:
Trigger - Trigger that was activated.
Background Process - Background processes run through the module.
For information about background processes, see Runtime Jobs.
Version - Module version.
Has errors - Whether the event contains any errors.
View Event Detail
To view details about a particular event, including the fields whose values changed, the triggers and actions that were activated, and details about any errors that occurred, select an event in the left panel and view the Event Detail panel on the right:
Inspect Action/Trigger Details
To get a closer look at a specific action or trigger in an event, select the Status for that action or trigger. A detail window displays the selected action or trigger:
Scroll through the fields in the action/trigger detail window to confirm the creation of fields or check whether the values of certain fields changed as part of the action.
You can filter module fields by selecting fields that fit one of the following criteria:
Involved in Action/Trigger - Fields that were newly populated or updated by the action or trigger, if any.
This filter displays as Involved in Action or Involved in Trigger, depending on your selection.
Empty Values - Fields with empty values.
Value Changed - Fields whose value the action or trigger changed. Note that fields in this category are also counted by the Involved in Action/Trigger filter.
Troubleshoot Action and Trigger Errors
If an error occurs in the event, an error message displays at the top of the Action Details panel. Select the Error Status to see details for the action or trigger where the error occurred.
In most cases, this error message indicates the specific problem, especially when the error is generated by a connected data source. In the example below, the error message generated by Jira is identified by Tonkean and passed through to the Module Event History screen.
You can re-run failed module logic directly from the Flow Run panel. Select Run Again in the upper right, then select to run the Entire event again or to only run module logic From failed actions. Choosing to run the event From failed actions can be a helpful way to pin-point a specific step where the logic is failing, especially as you work to resolve the issue causing the error.
View the field values before and after the action to pinpoint unexpected behavior. Here, you can locate a field that isn't updating properly, or is updating with an unexpected value.
Additionally, you can select the Request and Response tabs, where relevant, to view the raw JSON of the API calls made for the action. The details provided by the API endpoint can provide valuable troubleshooting information.
Resolve Common Workflow Errors
Below is a list of common workflow errors that are caused by generally simple configuration mistakes or misunderstanding workflow logic, and how to resolve those errors.
Acting on the Root Monitored Item When Not a Valid Option
When working with some data source actions (for example, an Invite Users to Channel action in Slack), you have the option to select Root Monitored Item in the Which Channel to update? field. However, the Root Monitored Item in this module is not a Slack channel, resulting in an incompatibility between the selected option and the item.
When you attempt to save or perform a test run in this module, the relevant action generates an error:
To resolve this error, you must select a relevant item or field to act on. In our example, we can resolve the issue by selecting Match in the Which Channel to update? field, and using a matched entity field to match to the channel ID.
There are various ways to fix this issue, but all solutions require an understanding of what the root monitored item is and what entity your action is designed to work on.
Missing Recipient on Notification Actions
While working on complex workflows with numerous Send Notification or data source notification actions, it's common to leave the recipient set to the default value, Flow item's owner. However, if no default item owner is set for the module, this configuration will generate an error. Also, some users opt to send the notification to a specific person but do not specify a user, missing the recipient altogether.
It's important to note that Tonkean does not validate notification recipient fields before testing a module—that is, an error is only generated during a module flow run, potentially making it more difficult to notice these missing values until later in your process.
An error does generate when testing the module, however. Notice in the example below that the error is on the Send Notification action and the error message specifies that "No value found in the configuration on who to send the message to":
The error message indicates that one possible cause of the failure is that the data retention policy removed the data from the action. This cause is possible when your data retention policies are set to have extremely short retention periods, but this is most often not the cause of this error. In most cases, the error is caused simply by the recipient being set to Flow item's owner when no default owner is set or no value is set at all.
To resolve this error, ensure you have set the item default owner for the module if set to Flow item's owner; if not, confirm that you have included a value for the recipient.
Deleting a Field Currently in Use
Perhaps the most common error you might encounter in your modules is the result of attempting to delete a field that's currently in use by a module action or custom item interface. The provided error message specifies where the field is being used.
To resolve this error, navigate to the module action or item interface widget and remove the field from use. Once the relevant action or widget is updated, you can delete the field from your module.