Working with parameters

About parameters

Parameters can be defined throughout the connector builder, in:

• Authentication method URL parameters

• Authentication method headers

• Authentication method body

• Endpoint URL parameters

• Endpoint headers

• Endpoint body

When a process flow runs, any associated API requests are injected with given variable values wherever a corresponding {{key}} is found - this is Irrespective of where parameters are defined

All parameters specified in connector builder API requests must be placed within double-curly brackets - for example: {{store_name}}.

Optional vs default parameters

Depending on where you are in the connector builder, you will encounter both default and optional parameters, where:

• Default parameters are always applied to API requests, whenever it is used.

• Optional parameters are those that users can choose to apply with their own values - either when adding connector instances (in the case of parameters defined for authentication methods) or as filter parameters when configuring connection shapes for process flows.

Irrespective of where parameters are defined, any associated API requests are injected with given default and optional parameter values wherever a corresponding {{key}} is found.

In some places, you can only add default variables, but in others you can add both types. In this case, the variables page is split into two panels - for example:

Default parameters are defined in the top panel, with optional parameters in the lower panel. The sections below explain the use of these parameters in general terms - for specific guidance in a particular context, please use the links provided above.

Default parameters

Default parameters are those which must always be passed into the request URL, header, or body using values that you specify as part of the configuration. They are added as key pairs:

Defined values can be static or dynamic. Default parameters are passed straight into requests - users are never asked to provide values for these.

There is one scenario where a user can influence the value of a default parameter. This is where you define a default parameter value as an endpoint {{variable}}. For an example scenario please see our What if I want to force users to enter their required value for a URL parameter? section.

Optional parameters

Optional parameters are those that you want to expose to your users in process flows, and then pass values that they provide into your API requests (via the URL, header, or body).

Any optional parameters that you define are displayed as filter parameters for a connection shape when a user selects the associated instance/endpoint. Essentially, you are defining filter options for users to apply in process flows. For example:

Adding optional parameters

When you choose to add an optional parameter, you're prompted to complete the fields as below:

Use the following table as a guide for completing these fields:

Field	Summary
Field	Enter a valid parameter field from the API documentation associated with the third-party application that you're building.
Select an operator	Operators determine how matching should be performed on the value given for this field (for example: contains, equal to, greater than or equal to, etc.).
Select a type	Choose the type of field that users will be prompted to update when they set this parameter in process flows. Available options are string, number, specific date, and dynamic date. For examples of these types, please see the Optional parameter type examples section below.
Value	Available value fields depend on your type selection above. For examples, please see the Optional parameter type examples section below.

Optional parameter type examples

As noted above, the parameter type selected determines the user experience of updating this parameter (via connection shapes) in process flows. Below is an example of each parameter type, so you can see the resulting behaviour in a process flow.

String

When a parameter type is set to string, the user is prompted to add their required value in a single text field.

Below we have configured a 'Product Type' parameter with a string type:

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see a 'Product Type' parameter option, with a text field where they can enter a value:

Number

When a parameter type is set to number, the user is prompted to add their required value in a single numeric field.

Below we have configured an 'Order Number' parameter with a number type:

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see an 'Order Number' parameter option, with a text field where they can enter a value:

Dynamic date

When a parameter type is set to dynamic date, the user is prompted to provide a +/- number of seconds, minutes, hours, days, months, years to match on, relative to the current date.

Below we have configured a 'Date Created' parameter with a dynamic date type:

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see a 'Date Created' parameter option, with selectors to choose the required period:

Specific date

When a parameter type is set to specific date, the user is prompted to select a specific date, using a date picker.

Below we have configured a 'created at' parameter with a specific date type:

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see a 'Created At' parameter option, with selectors to choose a specific date:

Updating & removing parameters

Having added a parameter, you can simply click its name to access details in edit mode - for example:

From here, you can edit key and value fields, or choose the delete this entry - for example: