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

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'
        ]
      }