Connector shape

Introduction

The connector shape is used to define which connector instance should be used for sending or receiving data, and then which endpoint.

All connectors have associated endpoints which determine what entity (orders, products, customers, etc.) is being targeted.

Any connector instances that have been added for your installed connectors 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.

If you need more information about the relationship between connectors and instances, please see our Connectors & instances page.

Accessing connector shape settings

When you add a connector shape to a process flow, the connector settings panel 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 - for example:

Configuring settings for a connector shape

Show me

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:

All connector instances configured for your company are available for selection. Connectors and their associated instances are added via the manage connectors page.

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

All endpoints associated with the parent connector for this instance are available for selection.

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:

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

Available filters and variables - and whether or not they are mandatory - will vary, depending on how the connector is configured.

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:

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.

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

Option Summary

Option	Summary
Retries	Sets the number of retries that will be attempted if a connection can't be made. You can define a value between `0` and `2`. The default setting is `1`.
Backoff	If you're experiencing connection issues due to rate limiting, it can be useful to increase the `backoff` value. This sets a delay (in seconds) before a retry is attempted. You can define a value between `1` and `10` seconds. The default setting is `1`.
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`.

Retries

Sets the number of retries that will be attempted if a connection can't be made. You can define a value between 0 and 2. The default setting is 1.

Backoff

If you're experiencing connection issues due to rate limiting, it can be useful to increase the backoff value. This sets a delay (in seconds) before a retry is attempted.

You can define a value between 1 and 10 seconds. The default setting is 1.

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:

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

Option Summary

Option	Summary
Raw	Push the payload exactly as it is pulled - no modifications are made.
First	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, `[{customer_1}]` is pushed as `{customer_1}`. Generally, if your process flow is pulling from a source connection but later pushing just a into a destination connection, you should set payload wrapping to first. 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.
Wrapped	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. The most likely scenario for this is where you have a complex process flow which is assembling a payload from different routes. Setting payload wrapping to wrapped will wrap the entire payload as an array object. So, `{customer_1},{customer_2}{customer_3}` is pushed as `[{customer_1},{customer_2}{customer_3}]` .

Raw

Push the payload exactly as it is pulled - no modifications are made.

First

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, [{customer_1}] is pushed as {customer_1}.

Generally, if your process flow is pulling from a source connection but later pushing just a into a destination connection, you should set payload wrapping to first.

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.

Wrapped

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.

The most likely scenario for this is where you have a complex process flow which is assembling a payload from different routes.

Setting payload wrapping to wrapped will wrap the entire payload as an array object. So, {customer_1},{customer_2}{customer_3} is pushed as [{customer_1},{customer_2}{customer_3}] .

Step 9 If required you can set response handling options:

These options are summarised below:

Option Summary Endpoint method

Option	Summary	Endpoint method
Save response AS payload	Set this option to `on` to save the response from the completed operation as a payload for subsequent processing.	POST PUT PATCH DELETE
Save response IN payload	Set this option to `on` to save the response from the completed operation IN the payload for subsequent processing. This option provides the ability to access the response body via payload variables. 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. By default, the response is saved in a field named `response` - for example: `{"id":123,"response":{"id":123}}` However, when the `save response in payload` option is toggled `on`, you can specify your preferred field name - for example:	GET POST PUT PATCH DELETE
Expect an empty response	Set this option to `on` if you are happy for the process flow to continue if no response is received from this this request.	POST GET

Save response AS payload

Set this option to on to save the response from the completed operation as a payload for subsequent processing.

POST

PUT

PATCH

DELETE

Save response IN payload

Set this option to on to save the response from the completed operation IN the payload for subsequent processing.

This option provides the ability to access the response body via payload variables. 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. By default, the response is saved in a field named response - for example: