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/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

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

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

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:

SFTP connection shape path

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

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: