Parameters
Last updated
Last updated
Most operations will have parameters of some kind. To define them you simple click on 'Parameters' beneath the operation.
In this example a 'Path parameter' (id) was specified so that is added to the parameters automatically. Path parameters are added and removed directly in the 'Path' by declaring them there. Example: '/{resource}/{id}' where both 'resource' and 'id' are path parameters.
Query parameters are very commonly used by REST APIs. They are added at the end of the 'Path', after a '?' and separated by a '&'. But you do not have to worry about any of that, just add query parameters by clicking the 'NEW QUERY' button and the connector will take care of all the details. If you want add multiple parameters at once there is a convenient shortcut accessible by right clicking on 'Parameters' and selecting 'Add multiple query parameters'. You can then enter as many (within reason) parameters as you like. Choose how they are separated (comma, semicolon or new line) and what type they should all be (typically string). You can also decide whether the parameters are required or not.
The parameters in the example above were all of type 'String', which probably is the most common type you'll use. There are however multiple types available, more information about the different types can be found later in this page.
Query parameters can be set to be an 'Empty value parameter'. This means that if set to "true" the parameter will be included in the query but without a value. If for instance parameters 'x' and 'y' are defined and set to 'true' the url called by REST connector could look something like this:
http://theurl?otherParameter=someValue&x&y
Form parameters are added to your operation by clicking the 'NEW FORM' button. Form parameters requires you to also set a 'Content-Type' header on the operation - 'application/x-www-form-urlencoded' for GET or 'application/x-www-form-urlencoded' or 'multipart/form-data' for POST. If you are sending a file (binary data) you must use 'multipart/form-data'. If you do not set any header, the tool will force you to do so when clicking the 'Create/update connector' button. Form parameters cannot be used at the same time as body parameters.
Body parameters can be used with POST, PUT and PATCH operations. Typically they are used to send object data to an API. Objects are defined as models, see Models for more information. You can use model transformations on the model before it is sent to remote API, see Model transform for more information. Body parameters cannot be used at the same time as form parameters, and you can have only one body parameter in an operation.
Header parameters, or custom headers, are parameters that are sent as http headers to the API. One common use case is to send API keys in a header. If the API you are creating a connector for requires this, there are however other options available than creating a custom header, read more in the section 'API Keys' in Authorization schemes for more information.
Matrix parameters are parameters that are added to the 'Path' before any query parameters. They are separated by a ';'. If you for example has an operation 'op1' with two matrix parameters defined, 'm1' and 'm2' and one query parameter 'q1' which at runtime have the values 'm1Value', 'm2Value' and 'q1Value' the 'Path' (url) would look something like: 'https://site/api/op1;m1=m1Value;m2=m2Value?q1=q1Value'.
String
Path
Query
Form
Body
Header
Matrix
x
x
x
x
x
x
Strings is a very common parameter type. Default to this if you do not know the type. String supports 'Type formats'. Currently only 'date-time' will have an impact on runtime - causing the parameter to be treated as a datetime. The 'Required' constraint is used to force the Flow designer to provide a value, but the other constraints ('Max length' etc) are by default not enforced, but can be setup to be so under 'Advanced' on the root of connector overview.
Integer
Path
Query
Form
Body
Header
Matrix
x
x
x
x
x
x
Integer supports 'Type formats'. Currently only 'int64' will have an impact on runtime - causing the parameter to be treated as a 64-bit integer (instead of a 32-bit integer). The 'Required' constraint is used to force the Flow designer to provide a value. The other constraints ('Is exclusive maximum' etc) are by default not enforced, but can be setup to be so under 'Advanced' on the root of connector overview.
Number
Path
Query
Form
Body
Header
Matrix
x
x
x
x
x
x
Number is a used to support floating-point values. Number supports 'Type formats'. Currently only 'float' will have an impact on runtime - causing the parameter to be treated as a 32-bit floating-point value (instead of 64 bit one). The 'Required' constraint is used to force the Flow designer to provide a value, but the other constraints ('Is exclusive minimum' etc) are by default not enforced, but can be setup to be so under 'Advanced' on the root of connector overview.
Boolean
Path
Query
Form
Body
Header
Matrix
x
x
x
x
x
x
Simple type which allows true or false as value. Can be set to 'Required', forcing the Flow designer to provide a value.
Object
Path
Query
Form
Body
Header
Matrix
x
Used to send objects (instances of models) to an API. The header 'Content-Type' must be set, typically to 'application/xml' or 'application/json'. See Models for more information. Can be set to 'Required', forcing the Flow designer to provide a value.
File
Path
Query
Form
Body
Header
Matrix
x
Only supported on POST, PUT or PATCH operations with the header 'Content-Type' set to 'multipart/form-data'. Can be set to 'Required', forcing the Flow designer to provide a value. Will translate to a 'Stream' in the workflow. One example how to get hold of a 'Stream' is via the 'File Gallery' in 'User Step'. If you select 'upload to single' and output variable name is 'value1', then you can do a variable mapping to a File parameter with 'value1.data'. The uploaded file will have filename= 'unknown'
FileGallery
Path
Query
Form
Body
Header
Matrix
x
Very much similar to 'File', but accepts a record that corresponds to what a file gallery from a user step produces. Either you select a record from the file gallery or you provide a stream (in member 'Data') and any filename you want in member 'Filename'.
Stream
Path
Query
Form
Body
Header
Matrix
x
Used to send binary data to API. Similar to the 'File' parameter type, but for body parameters. From a workflow perspective used in the same way. The header 'Content-Type' must be set to 'application/octet-stream'. Can be set to 'Required', forcing the Flow designer to provide a value.
Computed parameter
Path
Query
Form
Body
Header
Matrix
x
x
x
x
x
Computed parameters is described here.
Array
Path
Query
Form
Body
Header
Matrix
x
x
x
x
x
x
Arrays are supported by all parameters, but will behave a bit differently depending on the parameter type. Can be set to 'Required', forcing the Flow designer to provide a value. 'Unique items' constraint is only for documentation purposes at the moment, but this can change in a future release of Flow.
At it's core arrays are of course collections of something. But you must define what the collection consist of.
For query, form, header and matrix parameters the 'inner type' can be 'String', 'Integer', 'Number', 'Boolean' or 'Array'. You define how the different items of the array are separated by selecting one of the following:
Csv. Comma separated, example: param=item1,item2,item3
Ssv. Space separated, example: param=item1 item2 item3
Tsv. Tab separated (''), example: param=item123
Pipes. Separated by '|' char, example param=item1|item2|item3
Multi. The parameter is repeated multiple times. Example for query parameter: param=item1¶m=item2¶m=item3. Multi is not supported for Path parameters.
For body you can use 'String', 'Integer', 'Number', 'Boolean' and 'Array' as well. But also 'Object'. When set to 'Object' the separation format has no effect.
When the 'inner type' is string you have the option to specify 'Available options'. The use of this is best described with an example:
Consider the operation 'GetOrdersByStatus'. As a parameter you can set the parameter 'status' with what statuses you are interested in. Available statuses are 'Pending payment', 'Processing', 'Approved' and 'Shipped'. To do this the API uses a query parameter array with csv separation. An example call would look like: 'https://store/api/GetOrdersByStatus?status=Approved,Shipped' to get all orders that are either 'Approved' or 'Shipped'. You can of course just specify a query parameter of type array with inner type string and csv separation and that is fine. You will then end up in Flow with something like this:
Either the Flow designer uses 'Single row' and provides one value or defines a table earlier in the workflow with multiple values. Either way, the Flow designer has to know which values are valid and the risk that something is misspelled etc is not neglectable.
A better way is to use 'Available options'.
This would result in the following in the machine step:
The options are identified as 'c1', 'c2', 'c3' etc, so if you want to setup the record outside of the machine step you can use those names. Example:
The record 'status' can then be used in machine step:
