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

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:

• Rename a branch

• Re-sequence a branch

• Delete a branch

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

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

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 and select the required source instance and source query for an existing :

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 or 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:

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:

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

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

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

Any connector instances that have been for your 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 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 - 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:

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:

Step 10 Save your changes.

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

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:

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:

• Contains one of many

• Does not contain one of many

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

• Spaces

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

If you're building multiple process flows with similar requirements for field mappings, you can export the configuration for a map shape, and then import 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 field mappings and associated transformations 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

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

This page provides guidance on using the map shape to configure field mappings between two connections.

Configuring a new map shape

Step 1 Click the source endpoint option:

...source and target selection fields are displayed:

Step 2 Use source and target selection fields to choose the required connector instance and associated endpoints to be mapped - for example:

Step 3 Click the generate automatic mapping button:

...when prompted to confirm this operation, click generate mapping:

Step 4 Patchworks attempts to apply mappings between your given source and target automatically. A mapping rule is added for each source data field and, where possible, a matched target field - for example:

From here you can refine mappings as needed. You can:

• Add a new mapping rule

• Change display names and/or fields in an existing rule

• Add a target mapping for a partial mapping rule

• Map a source field to multiple targets

• Map multiple source fields to a single target

• Add transformations for a mapping rule

• Delete a mapping rule

Step 5

Toggle wrap input payload and wrap output payload options ON/OFF as required.

Where:

• wrap input payload ON. Wraps the incoming payload in an array [ ] ONLY for processing within the map shape.

• wrap output payload ON. Wraps the outgoing payload in an array [ ] ONLY for onward processing.

Click options below for payload examples showing how these options work in practice:

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Step 6 Save changes.

Adding a new mapping rule

You can add as many new mapping rules as required to map data between source and target connections.

Specifying a mapping field manually

There may be times where you don't want to (or can't) use the payload fields dropdown select a field from your source/target data schema. In this case, you simply select the manual input field and enter the full schema path for the required field.

Changing display names or fields in an existing rule

You can change the display name and/or the field associated with the source or target for any mapping rule.

Adding a target mapping for a partial mapping rule

If you've used the automatically generate map option to generate an initial set of mappings, you may find that some source fields could not be auto-mapped. In these cases, a mapping rule is added for each un-mapped source field, so you can either add the required destination or delete the rule.

Mapping a source field to multiple targets

If required, you can map a source field to multiple target fields - for example, you might need to send a customer order number into two (or more) target fields.

Mapping multiple source fields to a single target

Sometimes it can be useful to map multiple source fields to a single target field. For example, you might have a target connection which expects a single field for 'full name', but a source connection with one field for 'first name' and another field for 'surname'.

In this case, you would define mappings for the required source and target fields, then add a transform function to concatenate the two source fields.

Deleting a mapping rule

When you choose to delete a mapping rule, it's removed from the list immediately. However, the deletion is not permanent until you choose to save the mapping shape.

Introduction

Field transformations can be defined to change the value of a data field pulled from a source system before it is sent to its target. A transformation is comprised of one or more functions.

This page explains how to add a new transformation for a field mapping, and how to remove functions and transformations.

Adding a new transformation

To add a new transformation for a field mapping, you start by adding a new transformation and then build the required functions. To do this, follow the steps below:

Step 1 Access the required process flow and then edit the map shape to be updated with a transform:

Step 2 Find the mapping that you want to update, then click the transform icon (between source and target elements). For our example, we're going to add a prefix to the 'id' field:

Step 3 Click the add transform button:

Step 4 Use the select a function field to choose the type of function that you need to use (functions are organised by type):

Step 5 Depending on the type of function you select, additional fields are displayed for you to complete. Update these as required - for our example we're adding some text to be added as a prefix:

Step 6 Now we need to confirm which source field this transform field should be applied for - click the add field button:

Step 7 Select the required field:

Step 8 Accept your changes.

Step 9 Add more fields if necessary.

Step 10 When you're satisfied that all required fields have been added, accept changes and then save the shape settings.

Transforms in this section

Introduction

Available transform functions are summarised in the following categories:

Array

Date & time

Number

Other

String

Transforms in this section

Introduction

The custom dynamic date transform function is used to set a target field to the current date and time, based on the date and time that the process flow runs. You can also define rounding and adjustments.

Adding a custom 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 custom dynamic date:

Step 5 Optionally, you can add adjustment settings - for example:

These options are summarised below:

Step 6 Accept your changes:

...then save the transformation:

Step 7 Now you can select a target field in the usual way - for example:

...then:

...then:

Step 8 Once your mapping is complete, the row should be displayed without a source field - for example:

From here you can save changes or add more mapping rules as needed. Next time the process flow runs, the custom dynamic date will be mapped to the given target field.

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

The custom static date transform function is used to set a target field to a given date and time.

Adding a custom 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 custom static date:

Step 5 Click anywhere in the date field, or click the calendar icon, to open a date picker:

Step 6 Set the required date and time.

Step 7 Accept your changes:

...then save the transformation:

Step 8 Now you can select a target field in the usual way - for example:

...then:

...then:

Step 9 Once your mapping is complete, the row should be displayed without a source field - for example:

From here you can save changes or add more mapping rules as needed. Next time the process flow runs, the custom static date will be mapped to the given target field.

Transforms in this section

• Cast to string

• Custom number

• Math

• Round number

Introduction

The math transform function is used to perform a mathematical operation for selected fields. For example, your incoming payload might include customer records, each with a series of numeric value fields that need to be added together so the total can be pushed to a total field in the target system.

Available mathematical operations

The following mathematical operations are available:

• Add

• Subtract

• Multiply

• Divide

Adding a math transform

In the instructions below, we'll step through the scenario mentioned above where our incoming payload includes customer records, each with three value fields (value1, value2, value3) that must be added together and pushed to a total field in the target system.

The steps required are detailed in two stages:

• Stage 1: Add all source fields to be totalled for the mapping row

• Stage 2: Add a concatenate transform function

Stage 1: Add all source fields to be totalled for the mapping row

To begin, we need to update/add the required mapping row so that it includes all source fields that need to be added together and then pushed to the target.

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

Step 2 Find (or add) the mapping row which requires a math transformation. In the example below, we have a row that's currently set to map the source first name field into the destination full name field:

Step 3 On the source side of the mapping row, we need to include all the fields to be used in our mathematical operation. To do this, click the 'pencil' icon associated with the existing source field:

Step 4 Details for the selected field are shown - click the add source field button:

Step 5 Click the 'pencil' icon associated with the new source field:

Step 6 Move down and update the display name and payload fields for the second source field that you want to use - for example:

Step 7 Accept these changes to exit back to your mapping rows - notice that there are now two source fields associated with the row you updated:

Step 8 Repeat steps 3 to 7 to add any more source fields that you need to include in the mathematical operation.

Step 9 Go to stage 2.

Stage 2: Add a math transform function

With all required source fields defined for our mapping row, we can add a math transform function to define the required calculation based on these fields.

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

Step 2 Click the add transform button:

Step 3 Click in the name field and select math from the number section in the list of transform functions:

...math options are displayed:

Step 4 Click in the operator field and select the type of calculation to be performed - you can choose from add, subtract, multiply and divide:

Step 5 Click the add field button:

Step 6 Click in source fields and select the first source field to be used in the calculation:

Step 7 Accept your changes.

Step 8 Click the add field button again:

...and add the next source field to be used - for example:

Step 9 Accept your changes.

Step 10 Repeat steps 8 and 9 to include any more source fields to be used in the calculation. Each time you accept a new source field you'll see the sequence that they will be processed when this transform function runs - for example:

Step 11 Having added all required source fields to be calculated, accept changes:

...then save the function:

Step 12 Ensure that the target field for this mapping row is set as required, then save the map shape. Next time the process flow runs, the mathematical operation will be performed for the given source fields and the total value is pushed to the defined target field. The example below shows an incoming payload before and after the math transformation is applied:

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:

Step 1: Write & deploy your response script

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

Introduction

The cast to boolean transform function is used to convert given values to true/false based on PHP logic, but with the option to define overrides for specific input values. For example, consider the following payload:

{
  "fruit_included": 0,
  "fruit1": "apples",
  "fruit2": "oranges",
  "fruit3": "pears",
  "fruit4": "grapes",
  "fruit5": "peaches"
}

Suppose we want to define a mapping for the fruit_included item (line 2) but convert the numeric value to a true/false (boolean) value. Without an override setting, transforming the number to a boolean value would result in the following payload:

{
  "fruit_included": false,
  "fruit1": "apples",
  "fruit2": "oranges",
  "fruit3": "pears",
  "fruit4": "grapes",
  "fruit5": "peaches"
}

This is because standard PHP logic determines that 0 equates to a boolean false value. But in this specific case, a quirk in our source data is such that the 0 value actually means true - hence a list of fruits follows.

So, we need a way to specify an override for this field, where 0 equates to true. We can do this via the other > cast to boolean transform function, thereby achieving the desired result:

{
  "fruit_included": true,
  "fruit1": "apples",
  "fruit2": "oranges",
  "fruit3": "pears",
  "fruit4": "grapes",
  "fruit5": "peaches"
}

Adding a cast to boolean 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 cast to boolean from the other category:

Step 5 In the true values (override) and/or false values (override) fields, enter specific values that should override standard PHP logic:

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

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 round date transform function is used to round source dates to either the start or end of the day, where:

• start of day changes the time to 00:00 for the received date

• end of day changes the time to 23:59 for the received date

So, you can round a given source date before sending the rounded value into a given target field.

Adding a round 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 round date:

Step 5 Choose your required rounding:

Step 6 Accept your changes and save the transformation - at this point your mapping row is displayed without a target. From here, you can go ahead and add a target field:

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 custom format.

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

Internally, the format transform function uses Laravel's date format methods, which in turn call PHP date format methods. Commonly used format specifiers are listed below - full details are available in this Laravel guide.

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"

If your Unix dates are provided as strings, you should convert these to numbers. To achieve this, add a cast to number transform for the date field BEFORE the date format transform function.

Introduction

The custom number transform function is used to map a given number to a target field.

Adding a custom number 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 custom number:

Step 5 Move down to the custom number field and enter your required number - for example:

Step 6 Accept your changes:

...then save the transformation:

Step 7 Now you can select a target field in the usual way - for example:

...then:

...then:

Step 8 Once your mapping is complete, the row should be displayed without a source field - for example:

From here you can save changes or add more mapping rules as needed. Next time the process flow runs, the custom number will be mapped to the given target field.

Introduction

The cast boolean to string transform function is used to change the data type associated with a source field from boolean to string.

Adding a cast boolean 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 boolean to string from the other 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:

Transforms in this section

Introduction

The round number transform function is used to change the number of decimal places for a number value. For example:

"quantity":1.000

...might be changed to:

"quantity":1.0

With the round number transform you can specify the number of decimal places that should be applied to incoming numeric values.

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 round number from the number category:

Step 5 Move to the decimal places field and enter the required number of decimal places required for transformed values - for example:

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

The custom boolean transform function is used to map a value of true or false to a target field.

Adding a custom boolean 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 custom boolean:

Step 5 Move down to the value field and select your required true/false value - for example:

Step 6 Accept your changes:

...then save the transformation:

Step 7 Now you can select a target field in the usual way - for example:

...then:

...then:

Step 8 Once your mapping is complete, the row should be displayed without a source field - for example:

From here you can save changes or add more mapping rules as needed. Next time the process flow runs, the selected custom boolean value will be mapped to the given target field.

Introduction

The cache lookup transform function is used to lookup and use data from a cache created earlier in the flow.

If caches have been or for use in any other process flows, you can reference these in field mapping transformations.

For details please see in our cache section.