Using variables

There are three types of variables in Dovetail:

1. (Message) Headers, scope is within a message.
2. Flow properties, scope is within a flow.
3. Tenant variables, scope is within a tenant.

(Message) Headers

Headers, short for Message headers, have the smallest scope of all the variables. Headers are dynamic variables existing in memory on a message level (in an exchange between components).

You can:

• Set a header with the SetHeader (single) or SetHeaders (multiple) component.
• Edit a header with the SetHeader(s) component using the same header name (overwriting it).
• Remove headers from a message with the RemoveHeaders component.
• Send a header to a flow with an Inbound HTTP component by adding it as a parameter:
  • append ?name=value to the url to send a header with headername name and headervalue value to that flow:
    https://[instance].dovetail.world/[environment]/[tenant]/[flow]?name=value
  • send multiple headers by adding an & in between:
    ?name1=value1&name2=value2

Headers are being set every time the flow route is 'followed'. For example; every hour you retrieve new order data in XML as a response from successive http calls. Then you set a header with an xPath expression that sets the value of an orderID element in the XML on a header named orderNumber. The value of the orderNumber header is going to be unique for every unique response.

note

Apart from setting headers in the flow, it is also possible for headers to enter the integration through an exchange with a remote endpoint, i.e. you receive a rate limit header in response to an http call.

tip

It is good practice to use the RemoveHeaders component regularly to remove unnecessary headers in your flow, especially after (Inbound) HTTP, Inbound Email, FTP or Scheduler components.

This ensures you aren't sending sensitive information to endpoints or accidentally misconfigure calls (some endpoints react unexpectedly to headers they don't expect). It also keeps the load on the server lower.

Using headers

To insert the value of a header in a flow you use the expression below, where name is the name of the header.

${header.name}

Input fields in component configuration show a button to indicate you can use headers in that field. Click the button to insert them easily.

Use headers to:

• Send along (meta) data with a message: i.e. Authorization, Content-Type, breadcrumbId, etc.
• Verify and route data based on statuses: i.e. checking HTTP response codes or rate limits.
• Retrieve and insert information: i.e. get an id from one source and use it in the url of a follow up api call, i.e. https://this.api.com/orders/${header.orderNumber}

Flow properties

The scope of flow properties is within a flow. Flow properties are static variables stored in the settings of a flow. They are 'encapsulated' within a flow's configuration whenever you install a flow.

You can:

• Set a flow property in the flow settings by clicking the button. Save the flow to save the properties after you've added them.
• Edit a flow property in the flow settings by clicking on its name / value field and change it, then save your flow.
• Remove a flow property in the flow settings by clicking the button, then save your flow.

Every flow has a couple of predefined flow properties: ID, Name, Tenant, Server and Environment. These properties can't be removed.

note

Values for the Test & Production environment can be different and either value can be empty, only 'Name' is obligatory for a flow property.

Using flow properties

To insert the value of a flow property in a flow you use the expression below, where flowproperty is its name.

#{flowproperty}

Input fields in component configuration show a button to indicate you can use flow properties in that field. Click the button to insert them easily.

Use flow properties to:

• Hold data used more often in the flow: i.e. API base url, usernames / passwords or fixed Api Keys/Authorization tokens.
• Monitor flows: i.e. exception or flow function monitoring (see our guide Management by Exception).

Tenant variables

Tenant variables have the biggest scope within Dovetail. Tenant variables are stored in a database and can be used in all the flows of a tenant. You find an overview of the tenant variables used within your tenant on the Tenant Variables page.

caution

Because tenant variables are stored in a database there is a short time between saving the value of a variable and retrieval. In high-frequency flows, due to parallel processing, retention and retrieval may not occur sequentially, and as a result of the delay, the retrieved value may be older than previously expected.

You can create, edit and remove tenant variables manually on the Tenant Variables page. Use the SetTenantVariable component to create or edit (overwrite) and the RemoveTenantVariable component to remove tenant variables from a flow.

note

The Tenant Variables page shows you when and by who a tenant variable was created and last updated.

Using tenant variables

There are two ways to use a tenant variable in a flow, with the GetVariable component or with an expression.

GetTenantVariable

To use the value of a tenent variable you use the GetTenantVariable component to put it on a header with a specified name, i.e. name. Then simply use the header expression as described before.

${header.name}

Expression

To insert the value of a tenant variable in a flow you use the expression below, where tenantvariable is its name.

@{tenantvariable}

Input fields in component configuration show a button to indicate you can use tenant variables in that field. Click the button to insert them easily.

Use tenant variables to:

• Hold data used more often within a tenant: i.e. API url, usernames / passwords or changing Api Keys/Authorization tokens.
• Dynamic flow performance data: i.e. timestamps of last integration run or statuses wether flows are active.

Last update on Mar 4, 2024