Flow Stores

The flow engine makes various data stores available to flows during their execution.

• Unless otherwise specified, stores are usually key-value structures, like JSON objects
• Stores can be read with variable expressions and JavaScript
• Stores, if writable, can be updated with JavaScript.
• Store values can be anything that serializes to JSON
• Stores are transient, which means they live for the duration of a flow’s execution

Store Quick Reference

Store	JS	Expression	Write	Availability	Conditions
Metadata	$meta	${meta:key}	❌	All flows	🟢
Variables	$vars	${vars:key}	❌	All flows	🟢
Data	$data	${data:key}	🟢	All flows	🟢
Web	$web	${web:key}	🟢	Web flows	🟢
Brand	$brand	${brand:key}	🟢	Web flows	❌
Input metadata	$inmeta	${inmeta:key}	❌	All flows Task flow conditions	❌
* Input	$in	${in:key}	❌	All flows Task flow conditions	❌
* Output	$out	n/a	🟢	JS-capable nodes	❌
* Last	$last	n/a	❌	Conditions only (Task & Web flows)	🟢

* These three stores may either be JSON objects, or arrays of JSON objects

Metadata store

The metadata store makes details about runtime context available to use within flows. When the flow engine executes a flow, it populates this store during the initialization phase, so its content is always available.

JavaScript access: $meta
Expression access: ${meta:some-key}
Writable: ❌ No
Flows: All flows

The metadata store contains:

{
  // #########################  Sirveo build & version

  "build_commit": "b4741a2",
  "build_time": "2023-12-29T23:49:28+02:00",
  "build_version": "0.0.5-alpha",

  // ######################### Flow details

  // id and name of current flow
  "flow_id": "48e2c89d-5504-4e6e-9207-903c413ddc7e",
  "flow_name": "My First Flow",

  // Mode of the flow, as per flow definition
  //   [ task | graph | web]
  "flow_mode": "task",

  // When a flow is executed by another flow, the "root flow"
  //   identifies the top-most flow that started the
  //   subflow call
  "root_flow_id": "4da3dbe9-bff2-44ae-bd92-75def74ec4d3",
  "root_flow_name": "Parent flow",

  // When a flow is executed by another flow, the "parent flow"
  //   identifies the immediate parent flow that executed the
  //   current flow
  "parent_flow_id": "4da3dbe9-bff2-44ae-bd92-75def74ec4d3",
  "parent_flow_name": "Parent flow",

  // Corresponds to "flow_mode", as per the engine
  //   [ unknown | graph | task | web]
  "exec_mode": "unknown",

  // ######################### Runtime details

  // Indicates what executed/invoked the flow
  //   [ test | editor | link | webhook | scheduler | event ]
  //   Note: "test" is only used for our internal unit testing
  "run_source": "editor",

  // Indicates in what context the flow is running.
  //   [ test | live ]
  //     test = flow editor
  //     live = link or webhook
  "run_mode": "test",

  // The number of times that nodes in the flow previously produced
  //   data on error channels
  "node_errors": 0,

  // ######################### current node details (if any)

  "node_id": "419be4f4-6099-4c21-98be-9396fa991136",
  "node_name": "JS Code",

  // ######################### flow status (set by status node)

  // unknown (default) | ok | not-ok | error
  "status": "unknown",
  // user-specified and optional
  "status_message": "",
  // use-specified and optional
  "status_http": ""
}

When a flow is run by a once-off schedule trigger, the metadata store contains additional details about the scheduling flow:

{
  // This value identifies the flow that used the schedule node
  //   to run this flow. Added in release 0.3.4
  "scheduling_flow_id": "6216da64-087b-4c09-8211-6bdfd76aafcd"
}

When a flow is run by an event trigger, the metadata store contains additional details about the triggering event:

{
  "event_id": "a979c766-e8a3-4fb2-ad88-6f1398af148d",
  "event_kind": "usr",
  "event_type": "my.event",
  "event_source": "",
  "event_persistent": true,
  "event_source_id": "",
  "event_timestamp": "2024-01-13T16:45:03.7054365+02:00",
  "event_origin_flow_id": "838c84d5-202d-4165-b716-9640365723aa",
  "event_source_flow_id": "838c84d5-202d-4165-b716-9640365723aa",
  "event_origin_trigger_id": ""
}

See the events reference for what these fields mean.

Variables store

The variables store contains flow variables, which in turn may contain matching server variables. This store is populated by the flow engine before a flow begins execution.

JavaScript access: $vars
Expression access: ${vars:some-key}
Writable: ❌ No
Flows: All flows

Caution

It is technically possible to configure flows to expose this store’s data in flow output. For example, use this in a JS node:

$out = $vars

See security for more detail and best practices.

Data store

The data store is a general purpose, writable store to persist arbitrary data during flow execution. It is empty by default.

JavaScript access: $data
Expression access: ${data:some-key}
Writable: 🟢 Yes
Flows: All flows

The data store can be manipulated in JS Code nodes. For example:

// set keys & values
$data.my_key = "some value"
$data["my-key"] = "some value"
$data.some_state = true
$data.some_object = { key: 123 }
$data.some_list = [1, 2, 3]

// read key values
if ($data.my_key) {
  /* do something */
}

if ($data.some_state === false) {
  /* do something */
}

let myTempVar = $data.some_state || false

Note

Prior to version 0.2.3, the content of the data store in web flows is AES-encrypted before it is included in responses to the client browser - which mirrors it back to the server - in case it contains sensitive/internal data. The encryption secret is transient, and unique to each client session and web flow initialization.

From version 0.2.3, the data store of web flows is temporarily persisted in the server’s memory and database, and entirely absent from client responses.

Web store

The Web data store contains input from form elements in web flow UI - specifically from block inputs in steps.

JavaScript access: $web
Expression access: ${web:some-key}
Writable: 🟢 Yes
Flows: Web flows only

It is a writable store, so step handlers may populate it with default values at the start of a flow, or update it based on some logic.

Note that the content of this store is shared with web flow clients in browsers.

Brand store

The Brand data store is a special-purpose store used for basic branding of the web flow client UI. It is populated by “Brand” node type in web flows.

JavaScript access: $brand
Expression access: ${brand:some-key}
Writable: 🟢 Yes
Flows: Web flows only

This functionality will be replaced by flow settings during an upcoming release.

Input store

The input store is available in JS Code and JS Condition nodes, and contains the input data that the engine pushed into the node’s input channel.

JavaScript access: $in
Expression access: ${in:some-key}
Writable: ❌ No
Flows: All flows, but only in JS Code and JS Condition nodes

Input metadata store

In addition to the input store, Javascript-capable nodes have access to the input metadata store, which describes details about the content of the node’s input data. This metadata is the useful subset of details that the flow engine generates about data it processes within a flow’s execution.

JavaScript access: $inmeta
Expression access: ${inmeta:some-key}
Writable: ❌ No
Flows: All flows

The input metadata store contains:

{
  // the engine-internal identifier of the data object
  "id": "f2c41419-25ce-49fc-a8d9-9eb9ce22a312",

  // The precise time when this data was created,
  //   within the context of the engine.
  "ts_created": "2024-01-23T16:10:45.6424901+02:00",

  // indicates where the data originated from.
  //   "flow" means flow input.
  //   "node" means a node within the flow.
  "origin": "node",

  // plaintext | bytes
  "data_kind": "plaintext",
  // the byte size of data
  "data_size_bytes": 791,
  // json | none
  "data_format": "json",
  // the format-related type of the input data.
  //   none | any | string | number | boolean | object | array | null
  "data_type": "object",

  // the node ID of the node that generated the data (if any)
  "from_node_id": "f344e6c4-2971-41d9-b00f-923de9aa7c8b",

  // the output channel on which a node emitted the data.
  //   node output channels are visible in graph flows,
  //   and they form the attachment points where nodes
  //   nodes can be connected. having them available in
  //   this store makes them usable in task flows
  //   for implementing advanced logic.
  //   usually "out" or "error".
  "from_node_key": "out",

  // the id of the node into which the data was sent.
  //   will match $meta.node_id
  "to_node_id": "f344e6c4-2971-41d9-b00f-923de9aa7c8b",

  // which node input channel the data was sent into.
  //   almost always "in" (input), but merge nodes
  //     in grpah flows have an "in2" channel.
  "to_node_key": "in"
}

Output store

The output store is available in JS Code and JS Condition nodes. By default, it is a copy of the node’s input store, but can be manipulated or changed, as long as it contains an object ({}), which can be empty.

JavaScript access: $out
Expression access: n/a
Writable: 🟢 Yes
Flows: All flows, but only in JS Code and JS Condition nodes