> 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/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md).

# Connector shape

## Introduction

The **connector** shape is used to define which connector [instance](/product-documentation/connectors-and-instances/working-with-instances.md) should be used for sending or receiving data, and then which **endpoint**.

Any connector **instances** that have been [added](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) for your [installed connectors](/product-documentation/connectors-and-instances/working-with-connectors/accessing-your-connectors.md) 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.

{% hint style="info" %}
If you need more information about the relationship between connectors and instances, please see our [Connectors & instances](/product-documentation/connectors-and-instances/connectors-and-instances-introduction.md) page.
{% endhint %}

{% hint style="info" %}
A single incoming payload for [any process flow shape](https://open.gitbook.com/~site/site_dIV1g/~/revisions/9dTvdvRJIRVZQXuBMMnJ/process-flows/building-process-flows/process-flow-shapes) should not exceed 500MB.

We recommend processing multiple, smaller payloads rather than one single payload (1000 x 0.5MB payloads are more efficient than 1 x 500MB payload!).

For payloads up to 500MB, consider adding a[ flow control shape](https://open.gitbook.com/~site/site_dIV1g/~/revisions/9dTvdvRJIRVZQXuBMMnJ/process-flows/building-process-flows/process-flow-shapes/standard-shapes/flow-control-shape) to batch data into multiple, smaller payloads. Payloads exceeding 500MB should be batched at source.
{% endhint %}

## Accessing connector shape settings

When you add a **connector** shape to a **process flow**, the [connector settings panel](#configuring-settings-for-a-new-connection-shape) 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 [settings panel](#configuring-settings-for-a-new-connection-shape) - for example:

<div align="left"><figure><img src="/files/mzjrf6IajYY5BpXs9L1N" alt="" width="315"><figcaption></figcaption></figure></div>

## Configuring settings for a connector shape

<details>

<summary><img src="/files/JOYoP4EdSu7WJ3CMdAAS" alt="" data-size="line"> Show me</summary>

![](/files/pIka7U7WHOmBJjIymGzG)

</details>

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:

<div align="left"><figure><img src="/files/YDHu7kqbGJZY7se2w9K4" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
All connector [instances](/product-documentation/connectors-and-instances/working-with-instances.md) configured for your company are available for selection. **Connectors** and their associated **instances** are added via the [manage connectors page](/product-documentation/connectors-and-instances/working-with-connectors/accessing-your-connectors.md).
{% endhint %}

{% hint style="info" %}
If you select an instance that's associated with a database connector, subsequent connector settings will vary from those detailed here - please see [Configuring a database connection](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape/configuring-a-database-connection.md) for more information.
{% endhint %}

**Step 2**\
Select the **endpoint** that you want to use - for example

<div align="left"><figure><img src="/files/g8NG3zLufJgwHMvmuQfd" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
All **endpoints** associated with the parent **connector** for this **instance** are available for selection.
{% endhint %}

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

<div align="left"><figure><img src="/files/mzjrf6IajYY5BpXs9L1N" alt="" width="315"><figcaption></figcaption></figure></div>

Now you can access any optional filter options that are available - for example:

<div align="left"><figure><img src="/files/AKKtEVOMPC21at5SLHWA" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Available filters and variables - and whether or not they are mandatory - will vary, depending on how the connector is configured.
{% endhint %}

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

<div align="left"><figure><img src="/files/iLTd7cFYhhmVptf8I79F" alt="" width="375"><figcaption></figcaption></figure></div>

The default setting is taken from the underlying connector endpoint setup and should only be changed if you have a technical reason for doing so, or if you receive a [timeout error when processing a particularly large payload](/product-documentation/process-flows/troubleshooting-process-flows/process-flow-timeout-retrieving-large-payload.md).

**Step 7**\
Set **error-handling** options as required. Available options are summarised below:

| Option                      | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retries                     | <p>Sets the number of retries attempted if a connection can't be made. You can define a value between <code>0</code> and <code>2</code>. The default setting is <code>1</code>.<br><br>It's important to note that each retry counts as an <a href="/pages/HbzTGbVdtvNIdHpdRKBc">operation</a>. For more information, please see <a href="/pages/dge01kkRAoIkH1ScGoiR#connector-retries-and-operations">Connector retries & operations</a>.</p> |
| Backoff                     | <p>If you're experiencing connection issues due to rate limiting, it can be useful to increase the <code>backoff</code> value. This sets a delay (in seconds) before a retry is attempted.</p><p>You can define a value between <code>1</code> and <code>10</code> seconds. The default setting is <code>1</code>.</p>                                                                                                                          |
| Allow unsuccessful statuses | If you want the process flow to continue even if the connection response is unsuccessful, toggle this option `on`. The default setting is `off`.                                                                                                                                                                                                                                                                                                |

**Step 8**\
Set the **payload wrapping** option as appropriate for the data received from the previous step:

<div align="left"><figure><img src="/files/gY4s0DSU5cbbB3J7oo8K" alt="" width="375"><figcaption></figcaption></figure></div>

This setting determines how the payload that gets pushed should be handled. Available options are summarised below:

| Option  | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Raw     | Push the payload exactly as it is pulled - no modifications are made.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| First   | <p>This setting handles cases where your destination system won't process array objects, but your source system sends everything (even single records) as an array. So, <code>\[{customer\_1}]</code> is pushed as <code>{customer\_1}</code>.</p><p>Generally, if your process flow is pulling <a data-footnote-ref href="#user-content-fn-1">multiple records</a> from a source connection but later pushing just a <a data-footnote-ref href="#user-content-fn-2">single record</a> into a destination connection, you should set <strong>payload wrapping</strong> to <strong>first</strong>.</p><p>When multiple records are pulled, they are written to the payload as an array. If you then strip out a single record to be pushed, that single record will - typically - still be wrapped in an array. Most systems will not accept single records as an array, so we need to 'unwrap' our customer record before it gets pushed.</p> |
| Wrapped | <p>This setting handles cases where your destination system is expecting a payload to be wrapped in an array, but your payload contains a series of 'unwrapped' objects.</p><p>The most likely scenario for this is where you have a complex process flow which is assembling a payload from different routes.</p><p>Setting <strong>payload wrapping</strong> to <strong>wrapped</strong> will wrap the entire payload as an array object. So, <code>{customer\_1},{customer\_2}{customer\_3}</code> is pushed as <code>\[{customer\_1},{customer\_2}{customer\_3}]</code> .</p>                                                                                                                                                                                                                                                                                                                                                             |

**Step 9**\
If required you can set **response handling** options:

<div align="left"><figure><img src="/files/HG3M3UkjFf2bxtHTM5yW" alt="" width="375"><figcaption></figcaption></figure></div>

These options are summarised below:

<table><thead><tr><th width="133">Option</th><th width="439">Summary</th><th>Endpoint method</th></tr></thead><tbody><tr><td>Save response<br>AS payload</td><td>Set this option to <code>on</code> to save the response from the completed operation as a payload for subsequent processing.</td><td><p>POST</p><p>PUT</p><p>PATCH</p><p>DELETE</p></td></tr><tr><td>Save response<br>IN payload</td><td><p>Set this option to <code>on</code> to save the response from the completed operation IN the payload for subsequent processing.</p><p>This option provides the ability to access the response body via <a href="/pages/HC31VdrWhJMUz0LwmCJx">payload variables</a>. This can be useful for cases where an API returns a successful response despite an error - by inspecting response information from the payload itself, you can determine whether or not a request is successful.<br><br>By default, the response is saved in a field named <code>response</code> - for example:</p><pre class="language-json"><code class="lang-json">{"id":123,"response":{"id":123}}
</code></pre><p>However, when the <code>save response in payload</code> option is toggled <code>on</code>, you can specify your preferred field name - for example:<br><br><img src="/files/xXiiJhJ2GfmrCOIB584f" alt=""></p></td><td><p>GET<br>POST</p><p>PUT</p><p>PATCH</p><p>DELETE</p></td></tr><tr><td>Expect an<br>empty response</td><td>Set this option to <code>on</code> if you are happy for the process flow to continue if no response is received from this this request.</td><td>POST<br>GET</td></tr></tbody></table>

**Step 10**\
Save your changes.

[^1]: For example: GET all customer records)

[^2]: For example, if you've configured a [filter](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/filter-shape.md) shape to pick a specific customer from a payload.