Endpoint variables

Introduction

We've already seen how variables are defined at instance and authentication method levels. Now we come to the lowest level at which variables can be defined - endpoint variables. 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 the API request associated with an endpoint is initialised) 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 customer_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 the authentication method for a connector and then another {{store_name}} variable on an endpoint, the endpoint value would take precedence.

Adding & configuring an endpoint variable

To add an endpoint variable, follow the steps below.

1

Add a new variable

Click the add new variable button:

2

Configure variable details

Complete details and set options on the add variable page:

The API documentation for the underlying third-party application should provide guidance as to what variables can be passed in requests and how these should be configured.

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 Working with variables). 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'.

3

Save your changes

Click the save button.

4

How will variable values be provided by users?

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, the header, or the body for the endpoint.

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

The API documentation for the underlying third-party application should provide guidance about what and how variables can be passed in requests.

Removing an endpoint variable

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

PreviousAuthenticationNextURL

Last updated