Endpoint variables

Introduction

We've already seen how variables are defined at instance and authentication method levels - the final level that variables can be defined at is on endpoints. Any variables added here are only applicable to the associated endpoint:

Typically, these are variables that you want your users to update when they configure a process flow connection shape with an instance of your connector, using this endpoint.

When the process flow runs (i.e. when API requests are performed) the information provided by your user is injected into any corresponding {{variable}} tokens found in the endpoint requests.

For example, you might define an endpoint to retrieve a single customer record, and require your user to specify the required ID at runtime:

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.

Adding a variable for an endpoint

To add a variable for an endpoint, follow the steps below.

Step 1 Click the add new variable button:

Step 2 Complete details and set options on the add variable page:

What can I enter here?

The API documentation for the underlying third-party application should provide guidance about what variables can be passed in requests. The example below is from Shopify's API documentation:

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). However, it's worth noting the effect of setting required and configurable by user options in the context of endpoint variables:

• When you add an endpoint variable and choose to make it required, you are effectively saying: 'When a user adds a connection shape to a process flow and selects an instance of this connector together with this endpoint, do not allow them to proceed without providing a value for this variable'.

• When you add an endpoint variable and choose to make it configurable by users, you are effectively saying: 'When a user adds a connection shape to a process flow and selects an instance of this connector together with this endpoint, allow them to provide a value for this variable if they have one but if they don't, let them proceed'.

Step 3 Click the save button.

Step 4 Having added a variable, make sure that you go on to define how any values captured for it should be passed in API requests. Typically, any variable that you define here would then be added to the endpoint URL, or the header, or the body for the endpoint.

How do I know where to put these variables?

The API documentation for the underlying third-party application should provide guidance about what and how variables can be passed in requests. The example below is from Shopify's API documentation:

If you add endpoint variables but don't go on to add them to the endpoint URL, or the header, or the body, the result will be that users are prompted to provide these details but no action will be taken with that information.

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

Removing a connector variable from auth variables

You can remove an endpoint variable by clicking the associated trash icon on the auth variables tab - for example: