> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/~/changes/J8IbZkP6ASUZu2oBhGi2/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape/using-connector-shape-response-scripts.md).

# Using connector shape response scripts

## Introduction

## How it works

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

{% code lineNumbers="true" %}

```php
<?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;
}
```

{% endcode %}

## Implementing a response script

To implement a response script, you should:

1. [Write and deploy the required script](#step-1-write-and-deploy-your-response-script)
2. [Apply the script to your connector shape](#step-2-apply-the-response-script)

### Step 1: Write & deploy your response script

Response scripts are written and deployed in the usual way, via the [custom scripts](/product-documentation/~/changes/J8IbZkP6ASUZu2oBhGi2/marketplace/marketplace-scripts.md) option. However, two additional options can be used for scripts that you intend to [apply via connector shapes](#apply-the-response-script): [response\_code](#response-code) and [message](#message). &#x20;

{% hint style="info" %}
These options are only valid when the script is applied to a [connector step](/product-documentation/~/changes/J8IbZkP6ASUZu2oBhGi2/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md) as a `response script`.&#x20;
{% endhint %}

#### Response code

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

<table><thead><tr><th width="129">Value</th><th>Notes</th></tr></thead><tbody><tr><td>0</td><td>Continue</td></tr><tr><td>1</td><td>Fail the connector step and retry. The connector step is marked as failed and the queue will attempt it again.</td></tr><tr><td>2</td><td>Fail the process flow and queue it to retry. The process flow is marked as failed and queued for a retry.   </td></tr><tr><td>3</td><td>Fail the process flow and do not retry.</td></tr></tbody></table>

#### Message

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

#### Example

<pre class="language-php" data-line-numbers><code class="lang-php"><strong>function handle($data)
</strong>{
    // Stops the flow with a message
    $data['response_code'] = 3
    $data['message'] = 'Flow stopped by response script';

    return $data;
}
</code></pre>

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

<figure><img src="/files/DtttIF3NJQCfIIm3taFt" alt=""><figcaption></figcaption></figure>

## 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`:

{% code lineNumbers="true" %}

```php
<?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'
       ];
     }

```

{% endcode %}

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

{% code lineNumbers="true" %}

```php
<?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'
        ]
      }
```

{% endcode %}

## Related pages

* [Custom scripts](/product-documentation/~/changes/J8IbZkP6ASUZu2oBhGi2/marketplace/marketplace-scripts.md)