2: Connector variables

Introduction

A variable is a value that can change, depending on conditions or information supplied by the user. Using the Patchworks connector builder, variables can be defined at different levels:

About connector instance variables

The variables tab for a connector is used to define connector instance-level variables :

Users are prompted to provide values for these variables when they add and authenticate an instance of this connector. These values are then applied wherever this instance is used in process flows.

How it works

Any variables defined here are available for use when you move on to define authentication methods for your connector.

If you choose to use one of these variables in an authentication method, the result will be that your users are asked to provide a value for this field when they add an instance of this connector, with the associated authentication method.

Any value that the user provides during instance creation will be used whenever this instance is selected for use in process flows.

When a process flow runs (i.e. when API calls associated with selected endpoints for this instance are made), Patchworks grabs all defined variables and then injects them where a corresponding {{variable}} is found.

In the Patchworks connector builder, variables must be defined in double curly brackets.

Example

A great example of where defining an connector instance-level variable here is useful, can be found in the Shopify API. For any API request, Shopify requires a given store_name - for example:

GET
https://{{store_name}}.myshopify.com/admin/api/2023-04/customers.json

All API calls that users might want to use in process flows are added to the Shopify connector as endpoints. So, when a user configures a connection shape in a process flow and selects a connector instance to use, they will have a list of endpoints associated with the selected instance to choose from - for example:

Whilst you COULD ask your users to enter the appropriate store name whenever they select an endpoint (via an endpoint variable), this would be inefficient, and open to error.

A more efficient, reliable approach is to define a required {{store_name}} variable at the instance level. In doing so, the appropriate store name would be entered just once when an instance of this connector is added - for example:

The value provided here is injected into any {{store_name}} variables found when this instance is used subsequently, in process flows.

Precedence

If two variables with the same key are defined in two different places, we also prioritise them in connector -> connector instance -> endpoint order.

For example, if you define a {{store_name}} variable in an authentication method for a connector and then another {{store_name}} variable on an endpoint, the endpoint value would take precedence.

What you need to do

To add new system variables, follow the steps below:

Step 1 Click the add new system variable button:

Step 2 Complete fields on the add variable page - for example:

The add variables page is the same for all types of variables that you may encounter in the connector builder. For information about these options please see the Working with variables page.

For guidance on configuring variables for specific authentication types, please see our Supported authentication types section.

Step 3 Click save to add this variable to the variables list - for example:

Step 4 Repeat steps 2 and 3 for all required variables.

Step 5 Click next for authentication methods, where you can choose to use these variables, if needed.

Last updated