Stores

This guide shows how to use the various stores available within flows. The flow stores reference contains a complete description of all stores.

Stores exists in flows to solve three problems:

1. Making runtime information available in flows
2. Making flow variables and server variables available within flows
3. Creating and updating “global state” data across different nodes in flows

The basics to know about using stores are:

• Which stores are available
• How to access store information
• How to modify store information

All stores are accessed and modified in the same manner. We’ll use the JS code node to demonstrate how to work with stores.

The Metadata Store

When Sirveo executes a flow, it does so in a certain context - which could be in the flow editor, or via a webhook or link, or via a schedule or event trigger. This and other contextual information is provided to flows via the metadata store.

Let’s see how to inspect the content of a store.

1. Create a new graph flow
2. Replace the default passthrough node with a JS Code node
3. Place this line in the JS code node: $out = $meta

Then click the run button at the top of the node. The output looks like this:

What does $out = $meta do? It places the contents of the flow’s $meta store in the node’s $out store. See the metadata store reference for details about what each property means.

We could easily make the node output only certain information from the meta store:

Or change behaviour based on whether the flow is running in the editor:

Input & Output Stores

To demonstrate input and output stores in nodes, we can implement the exact behaviour of the passthrough node in a JS code node.

First, use a JS code node to create some test data:

Now add a second node, and connect their out/in channels (drag the out handle onto the in handle):

Open the second node, add $out = $in, and click the run button:

As expected, the first node’s output becomes input the second node.

And we see the passthrough behaviour on the output side:

This is actually the default behaviour of empty JS code nodes:

Why is this useful to know? Because it’s the simplest way to arbitrarily modify input data. For example:

The JS code node populates the content of the $out store with whatever it receives as input. Here, I add a new property to the $out store, which is initially a copy of the $in store. Then after the JS code runs, the node uses the content of $out as the node output.

Input Metadata

Notice in the screenshots how the input and output data indicates that the data is a json:object, and it has a certain (serialized) size (29 b).

The flow engine is doing a lot of work under the hood when it moves data from and to different nodes in a flow. Part of this work is inspecting the content of a node’s output data, and determining its format, data type and size.

The flow engine makes this internal metadata available to nodes as well, which is the purpose of the input metadata store.

Here’s how to access the input metadata store in a JS code node:

Here I’m making the JS code node output both its input, as well as the content of the input metadata store.

Technically, the content of that store contains (almost) everything that the flow engine knows about the specific piece of data that it gave to this node as input. For interest, this metadata is used by the UI to display input and output data in the flow editor.

The Data Store

The data store can be thought of as a place to store arbitrary data for the duration of a flow’s execution. The content of the data store is not part of the input or output data of a flow or a node. This allows the creation of arbitrarily complex stateful logic in flows.

We’ve been using a graph flow so far, but task flows are better suited for stateful logic. Create a new task flow:

By default, a new task flow has a single task level, containing a passthrough node as a placeholder.

Tip

Unlike graph flows which are data driven, task flows provide a different execution model;

• Nodes are organized into one or more task levels
• When a task flow runs, it executes each task level in order, from top to bottom
• For task levels in serial mode, their nodes run left to right
• For task levels in parallel mode, their nodes run concurrently

Double-click the passthrough node, and remove it.

Use the green + NODE button to add a JS code node to the first task level.
Then double-click the new node, and click on its name to change it to “node A”.
Finally, add this code:

$data.my = "value"

Notice that running the node produces empty output data:

However, any information added to the data store is available in other (subsequent) nodes.

To demonstrate this:

• close that node, and add a new task level (with the green + LEVEL button)
• add a new JS code node to the second task level
• rename it to “Node B”

Your task flow now looks like this:

Next, open the second node and add this Javascript:

$out = $data

When you now run the node, notice it’s input says “default input”, which means the flow engine executed the node without any input data.

But it’s output shows the content of the data store, which was modified by the first node:

So in summary, the data store:

• exists in the context of the flow, and not the context of a particular node
• is modified by any node in a flow - JS-capable nodes in particular
• can be read by any node in a flow

Lastly, the content of the data store never makes its way to the flow output, unless a node explicitly includes the data store in its output (like we did above).

Note

Task flows do not perform any implicit routing of data between nodes.

To select the input data for a node in a task flow, use the “change input” button on a node’s configuration.

The Variable Store

The variable store is used to access configured flow variables in a flow’s nodes and conditions (for task and web flows).

Flow variables are typically used to access server variables. For example, I’ll create two server variables, my-url, and my-secret. Only the latter is configured as a secret:

Next, create a new graph flow and remove the default passthrough node. Then add a JS code node, with the following line of code, which causes the node to output the content of the server variable store:

$out = $vars

Lastly, configure two flow variables with keys my-url and my-secret.

When running the flow, the node produces this output:

The $vars store is populated according to the flow’s variable configuration. Any server variables with matching keys are automatically included in the flow’s variable store.

There’s another reason why this example demonstrates how to add server variables to node output:

Caution

You should take care not to accidentally expose server variables in flow output. The flow engine will not prevent you from doing this, and this consideration is important in two scenarios:

• When exposing flows externally with webhooks
• When an HTTP node is configured to send its input data as the HTTP request body

Let’s see how we can use the two items in the server variable store in an HTTP node. In this example, we’ll be using variable expressions (instead of JS code) to place store items into node configuration.

Replace the JS code node with an HTTP Client node.

Then use this expression as the URL:

${vars:my-url}

And change the method to GET.

Running the node then uses the value of the server variable:

We can use the other server variable as an imaginary authentication header in the HTTP node’s configuration:

When running the node again, we can see the actual header value in the output, since the httpbin.org server will echo request details in HTTP responses:

Note that all stores can be accessed via either JS variables, and variable expression. See the flow stores reference for a complete list.

This means that data, metadata, input and other store items can be used in node configuration, using variable expressions like this:

${data:some-key}
${meta:some-key}
${in:some-key}

Note

If the specified key does not exist in the target store, an empty string value is used instead.

Tip

When a key might not exist in a store, a default value can be specified in variable expressions like this:

${vars:some-key||default value}