# 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
(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).
{% 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`.
{% endhint %}
#### 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`:
{% code lineNumbers="true" %}
```php
(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
(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)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET 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?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.