Using connector shape response scripts

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

When a response script is applied, the existing schema/data path defined for the associated endpoint is bypassed. If data is modified by the script, it gets returned in its modified state. If the script does not modify data, the data is returned in its original format

You should consider this in any subsequent shapes where the schema is used - for example: map, filter, flow control, route.

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.

These options are only valid when the script is applied to a connector step as a response script.

Response code

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

Value	Notes
0	Continue
1	Fail the connector step and retry. The connector step is marked as failed and the queue will attempt it again.
2	Fail the process flow and queue it to retry. The process flow is marked as failed and queued for a retry.
3	Fail the process flow and do not retry.
4	Force the connector to re-authenticate and retry the request.

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