When building connectors with the connector builder, you need to add/update variables and parameters in most stages of the process. Whilst the purpose of these will vary (for example, endpoint and authentication variables are needed for different things), techniques for adding and managing variables and parameters is always the same.
Parameters can be defined throughout the connector builder, in:
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}}.
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 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 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:
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
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
Value
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.
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:
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:
When a runs, any associated API requests are injected with user-provided variable values wherever a corresponding {{variable}} is found.
All variables added to connector builder API requests should be placed within double-curly brackets - for example: {{product_type}}.
The sections below explain the use of variables in general terms - for specific guidance in a particular context, please use the links provided .
When you choose to add or edit a variable, the add variable or manage variable page is displayed:
To edit a variable, simply click the variable name to open the standard variable settings page - for example:
From here, you can make your required changes and click the save button.
In the case of a locked variable, you can change the name that users see for the associated field when they are asked to provide a value.
As such, we need to rename the To do this, click the field name and update the display name as appropriate - for example:
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 section below.
Available value fields depend on your type selection above. For examples, please see the section below.
Options on this page are the same, irrespective of whether you're adding/managing , or . Use the table below as a guide for completing this page:
The remaining fields on this page determine if/how your users will interact with this variable when of this connector:
In some cases, a variable may be locked - these are variables which are required by Patchworks to perform a particular function (for example, default variables associated with ). In this case, you can't change settings or remove the variable, but you can .
Key
The name to be used by Patchworks internally, when referencing this variable.
Display name
The field label that users will see if they are asked to enter a value for this variable.
Alias
The name used by the actual system when referencing this variable.
Default value
Enter a default value to be shown when this field is displayed to users. The maximum number of characters permitted is 1024.
Is this required?
Toggle this option on to make this a mandatory field when a user either:
is asked to provide credentials for a new instance (in the case of connector and auth variables)
configures a connection shape with a given endpoint (in the case of endpoint variables).
Is this configurable
Toggle this option on to make this an optional field when a user either:
is asked to provide credentials for a new instance (in the case of connector and auth variables)
configures a connection shape with a given endpoint (in the case of endpoint variables).
Is this for advanced users only?
Advanced variables are those which 'regular' users would not typically need to see or change, but which advanced users might want to change in exceptional cases.
With this option toggled on, the field for this variable is hidden in an advanced section
when a user either:
is asked to provide credentials for a new instance (in the case of connector and auth variables)
configures a connection shape with a given endpoint (in the case of endpoint variables).
Only select this option if this is a variable that 'regular' users would NOT typically need to see or change - but which advanced users might want to change in exceptional cases.
For example, the content-type variable might typically be set too application/json but you need to allow for edge cases in NetSuite, where an advanced user might want to change it to application/xml.
Is this variable a secret?
Toggle this option on if values entered for this field are sensitive. Secret variables are stored in HashiCorp Vault.
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.
