# 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:&#x20;

<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).&#x20;
{% 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.&#x20;
{% 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></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></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></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></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></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:&#x20;

<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></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)&#x20;

[^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.


---

# 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/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md?ask=<question>
```

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.