2: Connector variables
Last updated
Last updated
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:
| Level | Summary |
|---|---|
Connector instance variables defined here can be used when you configure authentication methods. If you're defining multiple authentication methods which share common variables, define them once here and then choose to 'use' them in subsequent authentication methods. | |
Auth variables (whether added directly or picked up and 'used' from predefined connector instance variables) are displayed as fields for your users to complete whenever the associated authentication method is used to add a connector instance. | |
Endpoint variables are displayed as fields for your users to complete whenever they configure a process flow connection shape to use an associated endpoint. |
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.
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.
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:
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.
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.
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.
