1 of 9

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 trigger shape 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 which version of the process flow is deployed - 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 enabled.
Check your run queue 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 run logs 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 contact Patchworks support 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.

Re-syncing a previous payload

Introduction

If a process flow fails to complete successfully, you'll see the run displayed in your logs with a failure status - if appropriate, you can use the retry option to run it again.

However, there may be occasions when some time has passed since a flow failed, therefore a retry would not necessarily pick up the same data as the original run. Or, you want to re-sync a specific item in a payload.

This guide walks through the steps required to retrieve the original payload from a failed run and pass this into the process flow to run again.

Most endpoints have a variable or parameter used to target a specific entity (for example, order_id, customer_id, product_id, etc.). When building a process flow, we recommend building an alternative 'flavour' that allows users to specify a unique identifier to target at runtime - this is the most efficient way to sync/re-sync specific items. For more information please see our Targeted syncs - best practice page.

However, if you don't have a process flow in place for targeted syncs, the steps detailed here can be followed.

The steps

This task is documented in four stages:

Find the payload to be synced We need to find the payload from the failed process flow that needs to be passed in again, manually.
Skip shapes Since we're passing in the required data manually, we must prevent (temporarily) all shapes up to and including the point the payload was taken from running again.
Initialise the flow manually with the payload Run the flow manually, passing in the payload found in stage 1.
Reinstate skipped shapes Remove the 'skip' option from shapes so the process flow runs normally next time.

This task requires us to (temporarily) prevent some shapes in your process flow from running. As such, please ensure that you complete this task at a time when the process flow is not scheduled to run automatically.

Stage 1: Find the payload

First, we locate and copy the initial payload so it can be passed in again, manually.

The 'initial' payload is the payload you want to pass into the flow to be synced. In the simplest case, this is a payload generated from a first connector step that receives data, but there may be times when you need to take a payload from further down the flow - for example, you might want to process a single-item payload generated from a flow control shape.

Any payloads associated with a process flow run can be accessed retrospectively, via your run logs. To do this, follow the steps below.

Step 1 Select run logs from the left-hand navigation menu:

Step 2 At the top of the run logs table, click the filter icon associated with the status column:

...and select the failure option (so only failed runs are displayed):

Here we assume that you are re-syncing data because a run has failed. If this isn't the case, you can filter by any status to find the required run - however, beware of duplicating data if you re-use data from a run set to anything other than a failure status.

Step 3 Click the ellipses associated with the run that you want to access, then select the view logs option:

Step 4 Logs are displayed with each step in the flow listed in the lower panel - for example:

Our example shows that our flow failed at the assert step, with only a connector step before. So in this case, we need to obtain the entire payload from the previous connector step.

You can retrieve the payload from whichever step in your process flow is most appropriate. In our example, we want to re-sync ALL original data from the connector shape but if - for example - you are looking for a specific record and your process flow includes flow control, this is most likely to be the place to find it.

Step 5 Click the 'eye' icon associated with the shape that you want to view.

...and look for payloads in the lower panel:

These are payloads that were available at the end of the step - you might have a single payload or (for example, if your data is paginated or has been through flow control) you might have multiple payloads as per this example.

Step 6 Click the 'eye' icon associated with the first payload:

...and the payload is displayed:

Step 7 Check the payload to ensure that it contains the right data, then scroll to the end and look to see if the displayed data is truncated - if it ends with a [trimmed] marker, the full payload can't be displayed:

Step 8 What you do next depends on whether the displayed payload ends with a [trimmed] marker:

Stage 2: Skip shapes

Having obtained the required data, we must ensure that all shapes up to including the step associated with your payload are NOT processed the next time the process flow runs.

To do this, access settings for each shape and toggle the skip option on:

With the exception of the trigger shape (which can't and doesn't need to be skipped), you must skip ALL shapes up to and including the shape where you copied the required payload.

For more information about the skip shape option please see our Skipping shapes page.

Stage 3: Initialise the flow manually with payload

Now we're ready to run the process flow manually, passing in the payload copied in stage 1.

Step 1 Select initialise flow with data from the actions bar:

...a payload window is displayed:

Step 2 Paste in the payload that you copied in stage 1, then click the initialise flow button:

Step 3 Ensure that the process flow runs without errors, and check that data has synced as expected.

Stage 4: Reinstate skipped shapes

Having ensured that data has synced successfully, we can reset skipped shapes so the process flow runs normally next time.

To do this, access settings for each shape that you skipped in stage 2 and toggle the skip option back to off:

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:

Operation timed out after 30000 milliseconds with 0 bytes received

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

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.

Re-syncing a previous payload

Introduction

If a process flow fails to complete successfully, you'll see the run displayed in your logs with a failure status - if appropriate, you can use the retry option to run it again.

This guide walks through the steps required to retrieve the original payload from a failed run and pass this into the process flow to run again.

However, if you don't have a process flow in place for targeted syncs, the steps detailed here can be followed.

The steps

This task is documented in four stages:

Find the payload to be synced We need to find the payload from the failed process flow that needs to be passed in again, manually.
Skip shapes Since we're passing in the required data manually, we must prevent (temporarily) all shapes up to and including the point the payload was taken from running again.
Initialise the flow manually with the payload Run the flow manually, passing in the payload found in stage 1.
Reinstate skipped shapes Remove the 'skip' option from shapes so the process flow runs normally next time.