Introduction

Process flows are built by dragging and dropping shapes onto a canvas, and then configuring those shapes to work in the way you need to exchange data between connector instances.

Process flows are extremely flexible. You can build something very simple to sync data between two instances with standard field mappings - or build more complex flows, perhaps using custom scripts and/or routing data to different paths based on given conditions.

Prerequisites for building a process flow

Before you start building a process flow, make sure that you've installed a connector and added your required instances for any third-party applications that you want to use.

In this section

• Approaching your first process flow

• Techniques for building process flows

• Best practice for building process flows

• Process flow versioning

• Adding a new process flow

• The process flow canvas

• Process flow shapes

• Shape notes

• Dynamic variables

Introduction

The flexibility of process flows means that there's no 'one size fits all' approach - everyone's requirements are different, and the scope is huge. This level of flexibility is a great advantage but on the flip side - where do you start?

Here, we outline the bare bones of a process flow so you know what to consider as a minimum when getting started for the first time.

Testing

A scratchpad area will be available soon. In the meantime, we suggest registering for a sandbox account and experimenting there.

Make sure you create instances with credentials for your third-party application sandbox accounts, rather than live ones!

Key elements of a process flow

In their simplest form, process flows are defined to receive data from one third-party application and send it to another third-party application, perhaps with some data manipulation in between. Key elements are summarised below.

Process flow versions

Process flow can be associated with three version types: draft, deployed and inactive. Before you get started building process flows, we advise reading our Process flow versioning page to make sure you understand how this works.

Introduction

In this section, we share some insights on best practice for different aspects building process flows.

Pages in this section

• Scripts - best practice

• Multi environment management - best practice

Introduction

This page summarises best practice insights for for working with scripts in process flows. Keep in mind that scripts come in two 'flavours':

• Payload scripts. A script shape is configured to run a given script on the incoming payload.

• Transform scripts. A script transform function is added to a field mapping (in the map shape) - this runs a given script on the associated source field before the mapping is completed.

One script is more efficient than multiple scripts

Generally, doing everything you can in a single script is more efficient than processing multiple scripts - it means less downtime between steps, and less chance of being caught in a queue between scripts.

There are times where deploying multiple scripts is preferable from a management perspective - for example, if you're designing generic scripts to use across multiple process flows. In this case, you trade modularity for speed, in most cases.

Payload scripts are more efficient than transform scripts

Payload scripts (i.e. scripts run via the script shape) are more efficient than transform scripts.

Effectively, a transform script pauses the map shape, calls the script, then merges that response and continues with the map. Multiple script transforms results in multiple pauses - similar to running multiple scripts back-to-back in the process flow itself.

Debugging scripts

The Patchworks script editor allows you to edit scripts and test with a given payload, but for detailed debugging, we advise using an IDE with a debugger to step through the code.

Introduction

Most endpoints have a unique or used to target a specific entity (for example, order_id, customer_id, product_id, etc.). When these are defined, you can enter required values at runtime to target a specific item - for example:

Here, our flow is built to use a connector endpoint (retrieve specific product) that includes a unique variable named ref. When we access connector settings, this variable is surfaced so users can enter a value to target when the process flow runs.

Recommendation

When building process flows, we recommend building an alternative version which allows users to specify such an identifier in connector settings, so single items can be processed most efficiently in the event of a sync issue - for example:

Related pages

Adding shapes

To add a shape to a process flow, click the + icon at the point you want to place it - for example:

...then choose the type of shape to add:

Accessing shape settings

To access settings for an existing shape, click the associated 'cog' icon - for example:

The settings panel is displayed, so you can configure the shape as required - don't forget to save changes.

Changing a shape name

When a shape is dropped into the canvas, it's labelled with a generic name - 'map', 'flow', 'split', etc. Sometimes it can be useful to modify these names to something more specific - for example, to give a hint of what the shape's purpose in your flow (particularly if you have multiple shapes of the same type!).

To change the name, simply access shape settings, then click the 'edit' icon associated with the name at the very top of the settings drawer - for example:

The name field can now be edited - update the current name as needed, then click save at the bottom of the settings drawer:

Removing shapes

To remove a shape, click the associated 'cog' icon - for example:

...then click the delete option in the settings panel - for example:

Introduction

When building and testing your process flows before going live, a common requirement is to build process flows that connect to development/staging instances of your third-party systems - this ensures that you're not working with live data during the testing phase.

This page details our suggested procedure for managing this approach in terms of:

Adding process flows with different environments

Our suggested practice for adding process flows when you want to work with different environments is detailed in the following sections:

Phase 1: add connectors

Step 1 or required connectors for third-party systems to be integrated in your process flows.

Step 2 of these connectors and specify your DEV/STAGE credentials (i.e. credentials that allow you to access data in your DEV/STAGE environment for the third-party system). It's a good idea to indicate DEV/STAGE as part of the instance name. For example:

Phase 2: build & test process flows

Step 3 Move down to the labels section and apply a label that indicates that this process flow is configured for your DEV/STAGE environment - for example:

Step 6 Test carefully to ensure that the right data (i.e. DEV/STAGING data) is processed as expected.

Phase 3: duplicate flows for production

Phase 4: configure flows for production

Step 2 Update the process flow name as required. You may wish to indicate PRODUCTION as part of the process flow name but this isn't essential if you follow subsequent steps to apply labels.

Step 3 Move down to the labels section. Remove the existing DEV/STAGE label and replace it with a label that clearly indicates that this process flow is configured for your PRODUCTION environment - for example:

Step 4 Save changes.

Step 6 Check all other shapes in your process flow - if instance details are present, ensure that the PRODUCTION instance is selected.

Step 7 Check other shapes in your process flow. Typically, any instance information defined for a connection shape is inherited by subsequent 'child' shapes (which require instance details) in the flow. However, it's always worth double-checking before going live.

Phase 5: housekeeping

At this point, you now have different 'environment flavours' of the same process flow - for example:

Updating process flows with different environments

If you need to update a PRODUCTION process flow, there are two options, summarised below.

Option 1

Option 2

• Remove the 'old' PRODUCTION process flow

Introduction

With our process flow versioning system, you can be sure that a process flow that's currently deployed will never be edited (possibly with breaking changes) while it's in use.

To edit a deployed processed process flow, you take a copy as a and work on that - when you're ready, you can then .

Each time that you , the previously deployed version is saved as an version for future reference and, if required, future use.

Version types summary

At any given time, a process flow can be associated with one of the following version types:

More about version types

Draft

There is always one draft version of a process flow. The draft version can be edited freely without any possibility of changing or breaking the version that's currently . With a draft version, you can add/update , and change the process flow name.

When you're working with a draft version of a process flow, you can take the following actions:

Deployed

The deployed version of a process flow is the one that's currently in use (if it's enabled) or ready for use (if it's disabled).

Inactive

Working with versions

Accessing process flow versions

You can view all versions of a process flow via the settings panel.

Understanding which version you're viewing

When you access a process flow, the version being viewed is noted in the title bar. If you are viewing a deployed or inactive version, you'll see a message advising that edits cannot be made, and the version number is displayed beneath the title.

Switching between versions

To switch between different versions of a process flow, access the versions list and select the required entry.

Deploying a draft or inactive version

Copying to draft

Deleting an inactive version

Whilst it's often useful to refer back to an inactive version of a flow for a reminder of how things used to be set up, you may wish to remove older, inactive versions.

Introduction

The process flow canvas is where you build and test your process flows in a smart, visual way. This is where you define if, when, what, and how data is synced.

Finding your way around the process flow canvas

The process flow canvas has four main elements - a , an , a , and a (hidden unless activated) :

Options in the actions bar are summarised below:

Introduction

Shapes detailed in this section are available as standard, for all core subscription tiers:

• Assert

• Branch

• Connection

• Filter

• Flow control

• Manual payload

• Map

• Notify

• Route

• Run process flow

• Set variables

• Split

• Track data

• Trigger

• Try/Catch

Introduction

When adding filters for a string-type field, there may be times when standard operators can't achieve what you need. For example, when defining multiple filter conditions, the default condition is AND - so ALL specified filters must be met for a match. But what if you need an OR condition?

For more complex filtering requirements, regex can be used.

Regex filter example

Let's take the following payload:

[
    {
        "fruit": "apples pears grapes"
    },
    {
        "fruit": "grapes peaches raspberries"
    },
    {
        "fruit": "peaches"
    },
    {
        "fruit": "melon"
    }
]

Suppose we want to retrieve any items where the value of the fruit field contains peaches OR apples. We might be tempted to add two string-type filters in the filter shape:

However, this wouldn't return any matches because we'd be looking for any records where peaches AND apples are present. Instead, we can define one string-type filter with regex:

Introduction

Process flow settings are used to manage settings and behaviour for the process flow as a whole:

Understanding process flow settings

Process flow settings are summarised below.

- 2 hours UTC

Standard shapes

Advanced shapes

Introduction

The connector shape is used to define which connector instance should be used for sending or receiving data, and then which endpoint.

Any connector instances that have been added for your installed connectors are available to associate with a connector shape. Any endpoints configured for the underlying connector will be available for selection once you've confirmed which instance you're using.

Accessing connector shape settings

When you add a connector shape to a process flow, the connector settings panel is displayed immediately, so you can choose which of your connector instances to use, and which endpoint.

To view/update the settings for an existing connector shape, click the associated 'cog' icon to access the settings panel - for example:

Configuring settings for a connector shape

Follow the steps below to configure a connector shape.

Step 1 Click the select a source integration field and choose the instance that you want to use - for example:

Step 2 Select the endpoint that you want to use - for example

Step 3 Depending on how your selected endpoint is configured, you may be required to provide values for one or more variables.

Step 4 Save your changes.

Step 5 Once your selected instance and endpoint settings are saved, go back to edit settings:

Now you can access any optional filter options that are available - for example:

Step 6 The request timeout setting allows you to override the default number of seconds allowed before a request to this endpoint is deemed to have failed - for example:

The default setting is taken from the underlying connector endpoint setup and should only be changed if you have a technical reason for doing so, or if you receive a timeout error when processing a particularly large payload.

Step 7 Set error-handling options as required. Available options are summarised below:

Step 8 Set the payload wrapping option as appropriate for the data received from the previous step:

This setting determines how the payload that gets pushed should be handled. Available options are summarised below:

Step 9 If required you can set response handling options:

These options are summarised below:

{"id":123,"response":{"id":123}}

Step 10 Save your changes.

Introduction

You can use the assert shape is typically used for testing purposes -you can define a static payload which is used to validate that the current payload (i.e. the payload generated up to the point that the assert shape is encountered) is as expected.

Accessing assert payload shape settings

To view/update the settings for an existing assert shape, click the associated 'cog' icon:

This opens the options panel - for example:

Configuring settings for a new assert shape

To configure an assert shape, all you need to do is paste the required payload and save the shape for example:

Introduction

To configure a database connection, add a connector shape to your process flow in the normal way and select the required source instance and source query for an existing database connector:

Having selected a source instance, you'll know if you're working with a database connector because the subsequent field requires you to choose a source queryrather than a source endpoint.

Generally, database connector settings work on the same principles as 'normal' connectors but there are differences, depending on whether you're using a query that receives or sends data.

Receive queries

When a connector shape is configured with a receive type query (i.e. you're receiving data from a database), you'll see settings sections for variables, error handling, and response handling:

These options are summarised below.

Receive options

Response data

When a process flow runs using a receive type query, received data is returned in a payload. You can view this data in logs - for example:

Send queries

When a connector shape is configured with a send type query (i.e. you're sending data to a database), you'll see settings sections for variables, database, error handling, and response handling:

These options are summarised below.

Send options

About item paths

The items path field is used to run the associated query for multiple items (i.e. database rows) in a single operation, by looping through all items in a given array:

Here, specify the field name in your payload associated with the array to be targeted.

The items path field can't be used to target individual payload items. For this, you'd need an alternative approach - for example, you might choose to override query and provide a more specific query to target the required item.

Response data

When a process flow runs using a send type query, the default behaviour is for the response from your database to be returned as the payload. You can view this in logs - for example:

Related pages

• Building a database connector

• Working with queries

Introduction

The branch shape allows you to add shapes to multiple, distinct paths in a process flow, which are executed sequentially. Paths are executed one at a time, in the configured sequence, using the same incoming payload.

For complex scenarios, branching means you can split the logic in your flow, so it's easier to build, understand, and manage. For example, a common scenario for syncing orders between two systems is to:

1. Pull orders from the source system

2. Check if customer record exists in the destination system

3. If not, create it

4. Check if the address exists in the destination system

5. If not, create it

6. Decrement stock record in the destination system

7. Send order info to the destination system

This can all be achieved using one, long process flow however, the branch shape provides the ability to organise the steps logically. So:

1. Branch 1 creates/updates customer records

2. Branch 2 creates/updates address records

3. Branch 3 updates stock records

4. Branch 4 sends the orders to a warehouse system

Need to know

• The same data (i.e. any payload(s) that hit the branch shape) flows down every branch.

• All steps in a branch must be completed before the next branch starts.

• If one branch fails, any subsequent branches will not start.

• Nested branch shapes are permitted - so you can have a branch shape within a branch.

• The maximum number of branches for any branch shape is 6.

Adding a branch shape

Step 1 In your process flow, add the branch shape in the usual way:

Step 2 The shape is added to your flow with two path stubs - for example:

Step 3 Click the settings icon for the branch shape:

Step 4 Branch names are shown for the two placeholders:

...you can change these names as appropriate - for example:

...and add more branches if needed:

Step 5 Once all branches have been added, save changes:

...the branch shape is updated and you'll see a placeholder stub for each branch you added in the previous step:

Step 6 Now you can add shapes to each branch in the normal way. As soon as you add your first shape to a branch, empty shapes are added to the others - for example:

...click on these placeholders to replace them with the required shape from the shapes palette:

Managing branches

Having added branches to a branch shape, you may wish to:

These tasks are completed from branch shape settings:

Renaming a branch

You can rename a branch at any time - simply overwrite the existing name and save shape settings:

Re-sequencing branches

A branch must have at least one shape added to its path before it can be re-sequenced in settings:

If you attempt to re-sequence a branch that has no associated shapes in its path, you'll be prevented with a 'no entry' indicator:

Deleting a branch

When a branch is deleted, it's removed entirely - any shapes currently defined in its path are also removed. To delete a branch, click the associated delete button:

Managing branch paths

Shapes are added to branch paths in the normal way. Each path is just a flow that you build by adding shapes from the shapes palette and configuring them as needed.

Introduction

The Patchworks SFTP connector is used to work with data via files on SFTP servers in process flows. You might work purely in the SFTP environment (for example, copying/moving files between locations), or you might sync data from SFTP files into other connectors, or you might use a combination of both! For example, a process flow might be designed to:

1. Pull files from an SFTP server

2. Use the data in those files as the payload for subsequent processing (e.g. sync to Shopify)

3. Move files to a different SFTP server location

This guide explains the basics of configuring a connection shape with an SFTP connector.

About the Patchworks SFTP connector

Authentication

When you the Patchworks SFTP connector from the and then , you'll find that two authentication methods are available:

Endpoints

When you add a connection shape and select an SFTP connector, you will see that two endpoints are available:

Here:

• SFTP GET UserPass is used to retrieve files from the given server (i.e. to receive data)

• SFTP PUT UserPass is used to add/update files on the given server (i.e. to send data)

Configuring SFTP endpoints

Having selected either of the two SFTP endpoints, configuration options are displayed. The same options are used for both endpoints but in a different sequence, reflecting usage:

These fields are summarised below:

Using an {{original_filename}} variable

In this scenario, we can't know the literal name of the file(s) that the SFTP PUT UserPass endpoint will receive. So, by setting the path field to {{original_filename}}, we can refer back to the filename(s) from the previous SFTP connection step.

Using an {{original_path}} variable

The {{original_path}} variable is used to replicate the path from a previous SFTP connection step. It's most typically used with the SFTP PUT UserPass endpoint.

Using a {{current_filename}} variable

The {{current_path}} variable is used to reference the filename within the current SFTP connection step.

For example, you might want to move existing files to a different SFTP folder. The rename FTP command is an efficient way to do this - for example:

Here, we're using the FTP rename command to effectively move files - we're renaming with a different folder location, with current filenames:

rename:store1/completed_orders/{{current_filename}}

Creating SFTP folders dynamically based on timestamps

Script code

The following four lines of code should be added to your script:

$timestamp = round(microtime(true) * 100);
$meta = $data['meta'];
$meta['original_filename'] = 'FIXED_TEXT' . '_' . $timestamp . '.xml';
$data['meta'] = $meta;

SFTP connection shape path

The path in your SFTP connection shape should be set to:

{{original_filename}}

How it works

Syncing SFTP data to another target connector

Much of the information above focuses on scenarios where you are working with files between different SFTP locations. However, another approach is to take the data in files from an SFTP server and sync that data into another Patchworks connector.

When a process flow includes a source connection for an SFTP server (using the SFTP GET UserPass endpoint) and a non-SFTP target connector (for example, Shopify), data in the retrieved file(s) is used as the incoming payload for the target connector.

More information

For information about working with regular expressions, please see the link below:

Introduction

When a connector is built, default filters can be applied at the API level, so when a process flow pulls data, the payload received is has already been refined.

However, there may be times where you want to apply additional filters to a payload that's been pulled via a - for example, if the API for a connector does not support particular filters that you need.

Need to know

When specifying a filter value, the maximum number of characters is 1024.

Accessing filter shape settings

To view/update the settings for an existing filter shape, click the associated 'cog' icon:

Configuring settings for a new filter shape

Follow the steps below to configure a filter shape.

Step 1 Select a source integration and endpoint to determine where the incoming payload to be filtered originates.

Step 2 Click the add new filter button:

Step 3 Filter settings are displayed:

From here, you can select a field (from the data schema associated with the source endpoint selected in step 1) - for example:

Alternatively, you can toggle the manual input option to ON and add a manual path.

Step 4 Use the remaining operator, type and value options to define the required filter.

Step 5 Use the keep matching? toggle option to choose how matched records should be treated:

Here:

• If the keep matching? option is toggled OFF, matched records are removed from the payload before it moves on down the flow for further processing.

• If the keep matching? option is toggled ON, matched records remain in the onward payload, and all non-matching records will be removed.

Step 6 Click the create button to confirm your settings.

Step 7 The filter is added to the filter shape - you can now add more filters if needed:

Available data types

When defining a filter, you can choose from the following types:

Related information

Introduction

There may be times when you need to define a filter based on incoming data matching one of many given values. Conversely, you might want to define a filter based on incoming data NOT matching one of many given values. This can be achieved using the following operators in string-type filters:

Using these operators, you can specify a comma-separated list of values that a record must have/not have in a string-type field, to be a match.

Contains one of many

The contains one of many operator is used to match incoming records if the value of a given field DOES match any item from a provided (comma delimited) list of values. For example, consider the following payload of customer records:

[
    {"name": "John Smith",  "country": "FR"},
    {"name": "Bob Jones",  "country": "BE"},
    {"name": "Hank Smith",  "country": "AU"},
    {"name": "Jane Smith",  "country": "DE"},
    {"name": "Jack Jones",  "country": "SE"},
    {"name": "Hank Smith",  "country": "US"},
    {"name": "Paul Smith",  "country": "IE"}
]

Suppose you only want to process customer records with a European country code in the country field (which is a string type field).

You can add a filter for the country field and select the contains one of many operator - then provide a comma-separated list of acceptable country codes as the value:

The resulting payload would only include records where the country field includes one of the specified values - i.e.:

[
    {"name": "John Smith",  "country": "FR"},
    {"name": "Bob Jones",  "country": "BE"},
    {"name": "Jane Smith",  "country": "DE"},
    {"name": "Jack Jones",  "country": "SE"},
    {"name": "Paul Smith",  "country": "IE"}
]

Does not contain one of many

The does not contain one of many operator is used to match incoming records if the value of a given field DOES NOT match any items from a provided (comma delimited) list of values. For example, consider the following payload of customer records:

[
    {"name": "John Smith",  "country": "FR"},
    {"name": "Bob Jones",  "country": "BE"},
    {"name": "Hank Smith",  "country": "AU"},
    {"name": "Jane Smith",  "country": "DE"},
    {"name": "Jack Jones",  "country": "SE"},
    {"name": "Hank Smith",  "country": "US"},
    {"name": "Paul Smith",  "country": "IE"}
]

Suppose you only want to process customer records that do NOT have US or AU in the country field (which is a string type field).

You can add a filter for the country field and select the does not contain one of many operator - then provide a comma-separated list of unacceptable country codes as the value:

The resulting payload would only include records where the country field does NOT include one of the specified values - i.e.:

[
    {"name": "John Smith",  "country": "FR"},
    {"name": "Bob Jones",  "country": "BE"},
    {"name": "Jane Smith",  "country": "DE"},
    {"name": "Jack Jones",  "country": "SE"},
    {"name": "Paul Smith",  "country": "IE"}
]

List syntax notes

When defining your 'many values' list as the value for a contains one of many or a does not contain one of many filter, there are a couple of things to keep in mind:

Format

It's important that your 'many values' are specified as a comma-separated list - so in our example:

FR,BE,DE,SE,IE 

...will match as required, but:

FR BE DE SE IE 

...will NOT match as required.

Spaces

Any spaces included in your 'many values' list ARE considered when matching. For example, consider our original payload:

[
    {"name": "John Smith",  "country": "FR"},
    {"name": "Bob Jones",  "country": "BE"},
    {"name": "Hank Smith",  "country": "AU"},
    {"name": "Jane Smith",  "country": "DE"},
    {"name": "Jack Jones",  "country": "SE"},
    {"name": "Hank Smith",  "country": "US"},
    {"name": "Paul Smith",  "country": "IE"}
]

Suppose we are using the contains one of many operator to match all European countries and the value field is defined as below:

FR,BE,DE,SE, IE 

Notice that the final IE list item is preceded by a space. This means that our filter will only match the IE country code if it's preceded by a space in the payload, so the output would be:

[
    {"name": "John Smith",  "country": "FR"},
    {"name": "Bob Jones",  "country": "BE"},
    {"name": "Jane Smith",  "country": "DE"},
    {"name": "Jack Jones",  "country": "SE"}
]

Our IE record (line 8 in the payload) isn't matched because there's no space before the country code in the country field.

Introduction

The flow control shape can be used for cases where you're pulling lots of records from a source connection, but your target connection needs to receive data in small batches. Two common use cases for this shape are:

• A target system can only accept items one at a time

• A target system has a maximum number of records that can be added/updated at one time

The flow control shape takes all received items, splits them into batches of your given number, and sends these batches into the target connection.

Demo

Adding & configuring a flow control shape

Step 1 In your process flow, add the flow control shape in the usual way:

Step 2 Select a source integration and endpoint to determine where the incoming payload to be split originates - for example:

Step 3 Move down to the batch level field and select that data element that you are putting into batches. For example :

Step 4 In the batch size field, enter the number of items to be included in each batch. For example:

Step 5 By default, the payload format is auto-detected but you can set a specific format here if you prefer:

Step 6

If you're creating batches of one record, you can toggle ON the Do not wrap single records in an array option if you want the output to be this:

{
    "field": "value",
    "field": "value",
    "field": "value"
}

...rather than this:

[{
    "field": "value",
    "field": "value",
    "field": "value"
}]

Step 7 Save the shape. Now when you run this process flow, data will be split into batches of your given size.

Introduction

The Patchworks FTP connector is used to work with data via files on FTP servers in process flows. You might work purely in the FTP environment (for example, copying/moving files between locations), or you might sync data from FTP files into other connectors, or you might use a combination of both! For example, a process flow might be designed to:

1. Pull files from an FTP server

2. Use the data in those files as the payload for subsequent processing (e.g. sync to Shopify)

3. Move files to a different FTP server location

This guide explains the basics of configuring a connection shape with an FTP connector.

About the Patchworks FTP connector

When you add a connection shape and select an FTP connector, you will see that two endpoints are available:

Here:

• FTP GET is used to retrieve files from the given server (i.e. to receive data)

• FTP PUT is used to add/update files on the given server (i.e. to send data)

Configuring FTP endpoints

Having selected either of the two FTP endpoints, configuration options are displayed. The same options are used for both endpoints but in a different sequence, reflecting usage:

Transforms in this section

• Custom dynamic date

• Custom static date

• Format date

• Round date

Introduction

Typically, a process flow run is triggered and a request for data is made via a connector shape - if the request is successful, data is retrieved and the flow continues.

However, there may be scenarios where you need to control whether the connector shape or process flow run should fail or continue based on information returned from the connection request. To achieve this, you can apply a response script to your connector shape.

How it works

When a response script is applied to a connector shape, the script runs every time a connection is attempted. The script receives the response code, headers, and body from the request and - utilising response_code actions - returns a value determining whether the connector shape/flow run continues or stops.

Response scripts are just like any other custom script, except they receive additional information from the request - see lines 11 to 14 in the example below:

<?php

/**
 * Handler function.
 *
 * @param array $data [
 *      'payload'   => (string|null) the payload as a string|null
 *      'variables' => (array[string]string) any variables as key/value
 *      'meta'      => (array[string]string) any meta as key/value
 *      'flow'      => (array[mixed]) current flow data, including variables
 *      'response'  => [
 *           'headers' => ['Content-Type' => 'application/json', .......],
 *           'body' => '....',
 *           'status' => 200
 *      ]
 *    ]
 *
 * @return array $data Structure as above, plus 'logs' => (array[string]) Logs to be written to flow run log after script execution
 */

function handle($data)
{
    return $data;
}

Implementing a response script

To implement a response script, you should:

1. Write and deploy the required script

2. Apply the script to your connector shape

Step 1: Write & deploy your response script

Response scripts are written and deployed in the usual way, via the custom scripts option. However, two additional options can be used for scripts that you intend to apply via connector shapes: response_code and message.

Response code

The response_code determines how the process flow behaves if a connection request fails. Supported response_code values are:

Message

The message is optional. If supplied, it is output in the run logs.

Example

<?php

function handle($data)
{
    // Stops the flow with a message
    $data['response_code'] = 3
    $data['message'] = 'Flow stopped by response script';

    return $data;
}

Step 2: Apply the response script

To apply your response script, access settings for the required connector shape and select your script from the response script dropdown field.

Examples

Scenario 1

Here we handle the scenario where a connection response appears OK because the status code received is 200, but in fact the response body includes a string (Invalid session) which contradicts this. So, when this string is found in the response body, we want to retry the process flow.

In this case, we return a response_code of 2 with an message of Invalid session:

<?php
/**
 * Handler function.
 *
 * @param array $data [
 *      'payload'   => (string|null) the payload as a string|null
 *      'variables' => (array[string]string) any variables as key/value
 *      'meta'      => (array[string]string) any meta as key/value
 *.     'response'  => [
 *           'headers' => ['Content-Type' => 'application/json', .......],
 *.          'body' => '....',
 *           'status' => 200
 *      ]
 *    ]
 */
function handle($data)
{
    handle invalid session error in PVX
    $data['response']['status'] = 200;
    $data['response']['body'] = 'Invalid session';
      if (str_contains($data['response']['body'], 'Invalid session')) {
        return [
         'response_code' => 2 // retry flow
         'message' => 'Invalid session'
       ];
     }

Scenario 2

Here we show how the payload received from a connection request is checked for an order number and an order status - retrying the process flow if a particular order status is found:

<?php
/**
 * Handler function.
 *
 * @param array $data [
 *      'payload'   => (string|null) the payload as a string|null
 *      'variables' => (array[string]string) any variables as key/value
 *      'meta'      => (array[string]string) any meta as key/value
 *.     'response'  => [
 *           'headers' => ['Content-Type' => 'application/json', .......],
 *.          'body' => '....',
 *           'status' => 200
 *      ]
 *    ]
 */
    // check if order is ready to be processed yet
      $data['payload'] = [
        'order_id' => 1,
        'status' => 'Pending',
      ]
      if ($data['payload']['status'] === 'Pending') {
        return [
          'response_code' => 2, // retry flow
          'message' => 'Order not ready for processing, adding flow back to queue'
        ]
      }

Related pages

• Custom scripts

Introduction

You can use the manual payload shape to define a static payload to be used for onward processing. For example, you might define an email template that gets pushed into an email connection, or you might want to test a process flow for a connector that's currently being built by your development team.

Need to know

• The maximum number of characters for a single payload is 100k. Anything larger than this may cause the process flow to fail.

• Any text-based data format is supported (JSON, XML, CSV, plain)) however, keep in mind that subsequent shapes in the flow may only support JSON and XML.

Accessing manual payload shape settings

To view/update the settings for an existing manual payload shape, click the associated 'cog' icon:

This opens the options panel - for example:

Configuring settings for a new manual payload shape

To configure a manual payload shape, all you need to do is paste the required payload and save the shape for example:

Introduction

Mappings are at the heart of Patchworks.

When we pull data from one system and push it into another, it’s unlikely that the two will have a like-for-like data structure. By creating mappings between source and target data fields, the Patchworks engine knows how to transform incoming data as needed to update the target system.

The illustration below helps to visualise this:

In process flows, the map shape is used to define how data fields pulled from one connector correlate with data fields in another connector, and whether any data transformations are required to achieve this.

Accessing map shape settings

The map shape includes everything that you need to map data fields between two connections in a process flow. When you start to create mappings, there are two approaches to consider:

• Auto-generating mappings

• Adding mappings manually

Having added a map shape to a process flow, click the associated 'cog' icon to access settings:

Auto-generating mappings between connections

The generate automatic mapping option is used to auto-generate mappings between your selected source and target connections.

All Patchworks prebuilt connectors (i.e. connectors installed from the Patchworks marketplace) adopt a standardised taxonomy for tagging common fields found in data schemas for a range of entity types (customers, orders, refunds, products, fulfillments, etc.). So, if your process flow includes connections to sync data between two prebuilt connectors, it's highly likely that auto-generating mappings will complete a lot of the work for you.

Once auto-generation is complete, mapping rows are added for all fields found in the source data - for example:

Where matching tags are found, the mapping rows will include both source and target fields (you can adjust these manually and/or apply transformations, as needed).

Any fields found in the source data which could not be matched by tag are displayed in partial mapping rows, ready for you to add a target manually.

Auto-generating mappings for custom connections

If your process flow includes custom connections (i.e. connectors that have been built by your organisation, using the Patchworks connector builder), you can still use the generate automatic mapping option. The success of this will depend on whether field tagging was applied to your connector during the build:

• If yes, your custom connector will behave like any of our prebuilt connectors when it comes to auto-generated mappings, adding fully mapped rows for all matched tags.

• If no, Patchworks won't be able to match any source fields to a target automatically - partial mapping rows are added for all source fields found, ready for you to add a target manually.

Adding mappings manually

It's very easy to add individual mapping rows manually, using the add mapping rule option:

We recommend that you always try the automatic mapping option first and then manually add any extra rows if needed. However, there's no reason that you couldn't add all of your mappings manually if preferred.

Introduction

The array join transform function is used to join elements of an array as a string, with a user-defined delimiter. For example, you might have product data in an array:

{
  "fruit_in": [
    "Apples",
    "Oranges",
    "Pears",
    "Grapes"
  ]
}

...and need to convert these items to a string before pushing to a single destination field (with each item in the string delimited by a character of your choice):

{"fruit_out":"Apples,Oranges,Pears,Grapes"}

Adding an array join transform

Step 1 In your process flow, access settings for your map shape:

Step 2 Select the add transform icon for the required mapping rule - for example:

Step 3 Click the add transform button:

Step 4 Click in the name field to access a list of all available transform functions, then select join from the array category:

Step 5 In the delimiter field, enter the character that you want to use to delimit each array field in the string:

Step 6 Click the add field button:

Step 7 Click in source fields and select the source field to be used for this transform:

Step 8 Accept your changes (twice).

Step 9 Save the transform. You'll notice that the transform icon is updated to indicate that a transform function is present for the mapping row - for example:

Introduction

If you're building multiple process flows with similar requirements for field mappings, you can the configuration for a map shape, and then that configuration into another map shape.

When a map shape configuration is exported, a JSON file is generated and saved (automatically) to the default download folder for your browser. All and associated are exported. You can then import this file to any other map shape within:

• The same process flow

• Other process flows for your company profile

• Other process flows for any of your linked company profiles

Exporting a mapping configuration

To export the configuration for a map shape, follow the steps below:

Step 1 Access the required process flow, then click the settings icon for the map shape that you want to export:

Step 2 Click the export map button:

Step 3 The configuration is exported and saved to your default downloads folder. The filename is always map.json.

Importing a mapping configuration

To import a mapping configuration into a map shape, follow the steps below:

Step 1 Access the required process flow, then click the settings icon for the map shape that you want to update:

Step 2 Click the import map button:

Step 3 Navigate to the downloaded map configuration file on your local drive, then select it.

Step 4 Having selected a valid mapping configuration file to import, the import completes immediately.

Introduction

Available transform functions are summarised in the following categories:

Array

Date & time

Number

Other

String

Introduction

The cast to string transform function is used to change the data type associated with a source field from number to string. For example, you might have an id field in a source system that's stored as string value, but your destination system expects the id to be a number.

Adding a cast to string transform

Step 1 In your process flow, access settings for your map shape:

Step 2 Select the add transform button for the required mapping rule - for example:

Step 3 Click the add transform button:

Step 4 Click in the name field to access a list of all available transform functions, then select cast to string from the number category:

Step 5 Click the add field button:

Step 6 Click in source fields and select the source field to be used for this transform:

Step 7 Accept your changes (twice).

Step 8 Save the transform. You'll notice that the transform icon is updated to indicate that a transform function is present for the mapping row - for example:

Introduction

The format transform function is used to change a date value to a different format. For example:

"created_at":"2023-10-26T07:51:07-04:00"

...might be changed to:

1698321067

A range of predefined date formats is available for selection, or you can set your own .

Adding a format date transform

Step 1 In your process flow, access settings for your map shape:

Step 2 Select the add transform button for the required mapping rule - for example:

Step 3 Click the add transform button:

Step 4 Click in the name field to access a list of all available transform functions, then select format from the date category:

Step 5 Click in the format field to select a predefined date format that incoming dates should be converted to:

Step 6 Click the add field button:

Step 7 Click in source fields and select the source field to be used for this transform:

Step 8 Accept your changes (twice).

Step 9 Save the transform. You'll notice that the transform icon is updated to indicate that a transform function is present for the mapping row - for example:

Common format specifiers for custom dates

Day-related

The following characters are commonly used to specify days in custom format dates.

Month-related

The following characters are commonly used to specify months in custom format dates.

Year-related

The following characters are commonly used to specify years in custom format dates.

Time-related

The following characters are commonly used to specify times in custom format dates.

Usage notes

Unix Epoch format

Unix Epoch dates must be received as a number, not a string - i.e.:

1701734400 rather than "1701734400"