1 of 8

Troubleshooting process flows

About this section

This section contains quick, task-based guidance for some common usage questions!

In this section

Unable to edit a process flow
Process flow not running
Process flow run failures
Required fields not being tracked
Process flow timeout retrieving large payload
Process flow error when using a webhook connector
Your third-party systems go offline

Unable to edit a process flow

Scenario

You've accessed an existing process flow but can't make any changes on the canvas - there are no options to add shapes.

Reason

What you can and can't do with a process flow depends on the version you're viewing. If there are no options to add shapes to the canvas, it's likely that you're viewing a or an of the process flow. Only the of a process flow can be updated.

Solution

Try one of the following:

Switch to the of the process flow
Use the option to create a new draft version of the process flow

Further information

For more information please see our page.

Process flow not running

Scenario

A process flow has been triggered (either manually, or via a trigger schedule, API call or webhook) but it's not running.

Reason

A process flow must be both deployed AND enabled to run according to its settings.
When a process flow is triggered to run it is placed in a queue for processing as soon as possible. Sometimes the run will happen immediately but other times there may be a short wait, depending on how many jobs are running at the time.

Solution

Check - does it include the correct trigger shape settings? If not, you may have a draft version waiting to be deployed - or you may need to update and deploy a new draft.
Check that the process flow is .
Check your for pending jobs. If you see an entry for this run then no action is required - it will be started as soon as possible. If you don't see a pending entry, check the in case the job has already been completed.
If there is no associated entry in your queue or logs and your process flow is deployed & enabled, please for assistance.

Further information

For more information please see the following pages:

Process flow run failures

Introduction

A process flow may fail for a number of reasons - for example, if a mapped field in the source/destination system has changed unexpectedly; if authentication credentials for a connection have expired, or if shape configuration is incorrect.

You might notice the failure whilst observing , or you might have received an advising that an process flow failed to complete.

This guide summarises what to do in the event that a process flow fails.

When a process runs and fails, it's re-tried three times automatically before being stopped and logged as a failure.

Handling a process flow run failure

Step 1 Check the for the process flow. Here you'll find detailed information associated with each step in the flow, so you can identify which shape caused the flow to fail.

If a process flow has failed at a step, consider the following:

Are the authentication credentials provided for the selected connector instance still current? If you need to update credentials, you can .
Are all connection shape settings correct? For example, could the issue be related to a variable or parameter (either missing or defined incorrectly)?
Is the third-party system associated with your connector instance experiencing any issues?
Is the connector instance associated with a custom connector that was built by someone in your own organisation using ? If yes, check that the data schema for the endpoint selected in your step is valid.

If you change credentials for an instance, those credentials will be updated in all process flows where that instance is defined.

Step 2 If the cause of the failure isn't obvious from the log details, for each step in the flow to see if they are as expected. Payloads are available from the , via the view logs option for each step:

Step 3 If you've found the cause of the failure from the logs and need to update the process flow, access the process flow in question and make the required changes. OR If you haven't found the issue and need to investigate further, access the process flow in question and check the settings for each shape.

Required fields are not being tracked

Scenario

When checking the , fields that you expect/want to see are not shown.

Reason

When connector endpoints are configured, fields in the associated data schema can be flagged as tracked. By tracking these fields, they become available for viewing/filtering/selecting wherever tracked data is shown in Patchworks.

If you are not seeing a required field in the tracked fields panel, it's likely that it has not been flagged for tracking in the connector setup.

Solution

The steps below involve updating connector settings. Updating settings for a connector may affect how the connector runs. Please check with Patchworks support if you need to update tracked fields but are not sure about making this change.

Stage 1: check tracked fields for the connector

The first thing to do is access connector settings and check which fields have been flagged for tracking. To do this, follow the steps below.

Step 1 Select connectors & instances from the dashboard navigation menu - all installed connectors for your company profile are displayed.

Step 2 Access settings for the connector that you want to update.

Step 3 Select the endpoints option:

Step 4 Click the name of the first endpoint that you want to update to access its settings.

Most connectors will have multiple endpoints - you will need to update all endpoints that you use (or are likely to use) in process flows.

Step 5 Select the schema/taxonomy tab:

Step 6 Check the tags panel on the right-hand side of the page. Here you'll see a list of fields (from the associated data schema) which have been tagged and - if applicable - set to be tracked:

It's possible that lots of fields will be tagged but not flagged for tracking. Look for a tick in the tracked column to see where tracking is enabled.

The next steps depend upon what you see here:

Stage 2: Update field tag information

My query field does NOT show in the tags panel

If your query field does not show in the tags panel, follow the steps below to add a new tag and flag the field for tracking.

Step 1 Click the add a new tag button:

Step 2 Navigate the field data schema to find and select your query field:

Step 3 Click in the field below to see a list of standard Patchworks tags, then navigate this list to find a suitable tag for your field:

Step 4 Select the tracked checkbox so that it's enabled:

Step 5 Save changes:

My query field DOES show in the tags panel but without a tracked tick

If your query field DOES show in the tags panel but the tracked column is not ticked, follow the steps below to set field tracking.

Step 1 Click the tag that you need to update:

Step 2 Select the tracked checkbox so that it's enabled:

Step 3 Save changes:

Most connectors will have multiple endpoints - you will need to update all endpoints that you use (or are likely to use) in process flows.

Further information

For more information please see the following pages:

Process flow timeout retrieving large payload

Scenario

A process flow run fails and shows a 'timeout' error in the logs. For example:

Reason

are associated with a timeout option, with a default setting based on the underlying third-party system. Typically there's no need to change the default setting but if the payload being pulled/pushed is particularly large and you receive a timeout error, increasing the timeout setting may resolve the issue.

Solution

Step 1 .

Step 2 Click the settings icon for the connection shape that is giving a timeout error:

Step 3 Look for the timeout field and increase the existing value.

We suggest increasing the existing value by +20 seconds.

Step 4 Save changes.

Process flow error when using a webhook connector

Scenario

Your process flow includes a connector which is attempting to hit a webhook and the following error is displayed:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <meta name="robots" content="noindex,nofollow,noarchive" />
    <title>An Error Occurred: Unprocessable Content</title>
    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 128 128%22><text y=%221.2em%22 font-size=%2296%22>❌</text></svg>">
    <style>body { background-color: #fff; color: #222; font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; margin: 0; }
.container { margin: 30px; max-width: 600px; }
h1 { color: #dc3545; font-size: 24px; }
h2 { font-size: 18px; }</style>
</head>
<body>
<div class="container">
    <h1>Oops! An Error Occurred</h1>
    <h2>The server returned a "422 Unprocessable Content".</h2>

    <p>
        Something is broken. Please let us know what you were doing when this error occurred.
        We will fix it as soon as possible. Sorry for any inconvenience caused.
    </p>
</div>
</body>
</html>

Reason

This error can occur if:

The webhook connector does not include a content-type header
The process flow is not enabled

Solution

Check the connector setup and ensure that header options include a content-type header. For more information see Connector builder header options.
Ensure that the process flow being run is enabled. For more information see Enabling & disabling a process flow.

Your third-party systems go offline

Scenario

There may be occasions where your systems go offline - perhaps due to a general outage, or any number of reasons.

When this happens, syncing to these or downstream systems will be disrupted, resulting in errors reported in your Patchworks . Don’t be alarmed by these errors - they are to be expected, and can be resolved.

Solution

Once your systems are back online, edit any affected process flows and (temporarily) adjust any filter settings to cover the downtime period - then .

Avoid deploying this change as it will affect any future runs.

Required fields are not being tracked

Scenario

When checking the , fields that you expect/want to see are not shown.

Reason

If you are not seeing a required field in the tracked fields panel, it's likely that it has not been flagged for tracking in the connector setup.

Solution

Stage 1: check tracked fields for the connector

The first thing to do is access connector settings and check which fields have been flagged for tracking. To do this, follow the steps below.

Step 1 Select connectors & instances from the dashboard navigation menu - all installed connectors for your company profile are displayed.

Step 2 Access settings for the connector that you want to update.

Step 3 Select the endpoints option:

Step 4 Click the name of the first endpoint that you want to update to access its settings.

Most connectors will have multiple endpoints - you will need to update all endpoints that you use (or are likely to use) in process flows.

Step 5 Select the schema/taxonomy tab:

It's possible that lots of fields will be tagged but not flagged for tracking. Look for a tick in the tracked column to see where tracking is enabled.

The next steps depend upon what you see here:

What you see in the tags panel

Action

Stage 2: Update field tag information

Your next steps will depend on the outcome of your checks at the end of - please expand the appropriate instructions below:

My query field does NOT show in the tags panel

If your query field does not show in the tags panel, follow the steps below to add a new tag and flag the field for tracking.

Step 1 Click the add a new tag button:

Step 2 Navigate the field data schema to find and select your query field:

Step 3 Click in the field below to see a list of standard Patchworks tags, then navigate this list to find a suitable tag for your field:

These tags are used in - what you choose now isn't critical but it can help make mapping more efficient in future. Please see our page for more information.

Step 4 Select the tracked checkbox so that it's enabled:

Step 5 Save changes:

My query field DOES show in the tags panel but without a tracked tick

If your query field DOES show in the tags panel but the tracked column is not ticked, follow the steps below to set field tracking.

Step 1 Click the tag that you need to update:

Step 2 Select the tracked checkbox so that it's enabled:

Step 3 Save changes:

Most connectors will have multiple endpoints - you will need to update all endpoints that you use (or are likely to use) in process flows.