Global Values

Flows support storing data in global variables; this feature is sometimes referred to as a "blackboard". These variables are scoped to within a single instance of a Flow. Global values can be passed in as a Flow starts up, in order to parameterize the behavior of the Flow; or set within a Flow to implement monitoring at instance level.

Note

Agent version 1.6.14 or higher is required to use global values.

Info

From a programming perspective, these values are global in the sense that they are shared across Flow runtimes (i.e. are accessible from different languages). They are not global in the sense of being shared across different Flow instances, or across different Flows; to share data between sandboxed Flow instances, you should use conventional agent messaging primitives such as Telemetry or Control Messages.

Declaring flow arguments

In order to use global values to parameterize the behavior of a Flow, the values will need to be passed into the Flow as it is started. In order to facilitate this, such global values must be declared ahead of time:

Global values are declared in the flow's manifest, under "arguments" as shown below.

{
  ...
  "arguments": {
    "firstname": {
      "type": "string",
      "default": "Johnny",
      "description": "My flow first name"
    },
    "surname": {
      "type": "string",
      "default": "B Goode",
      "description": "My flow surname"
    }
    "age": {
      "type": "int32"
    }
  },
  ...
}

The "type" field is mandatory (see supported types). The "default" field is recommended: if no default value is declared, a value must be explicitly passed to the Flow at startup, or the start will be rejected. The "description" field is optional and intended for flow documentation.

Once an argument has been declared in the Flow manifest, the Portal will prompt the user to enter required global (argument) values each time

Passing arguments to entry-point

Having declared one or more global values as arguments to a Flow, it may be desired to pass these values into the main entry-point which is invoked when the Flow is started. This is only necessary in the case where the entry-point targets a function which takes positional parameters (e.g. a Javascript function). Mapping of global arguments to positional parameters should be achieved by specifying an "args" field into the relevant object in the "signals" section of the Flow's manifest.

Info

Since Visual Script files do not use positional parameters, when the main entry-point of a Flow is a Node in a Visual Script, no mapping is required. Instead, the value of arguments is accessed directly within the Visual Script itself using the Get Global node.

In the Flow manifest example below, the global values firstname and surname will be passed as the second and third arguments of the registered function my-entrypoint-func() (the second and third, rather than first and second, because the first argument is always the context and is usually ignored).

{
  ...
  "signals": {
    "main": {
      "entry" : ["my-entrypoint-func"],
      "args": ["firstname", "surname"]
    }
  },
  ...
}

Set arguments when starting a Flow

Declared global values can be set when starting a Flow, thus enabling Flows to be run in a parameterised manner. The startFlow() and startFlowAndWait() service calls allow the value of global arguments to be passed in as part of the service request in the "arguments" property of the request:

{
  ...
  "settings": {
    "arguments": {
    	"firstname" : "Jimmy",
    	"surname" : "Jazz",
    	"age" : 27
    },
    ...
  }
}

Access at runtime

Global values can be accessed (get) and modified (set) during the running of a Flow.

Info

You can set new global values at runtime that are not declared in manifest.

JavaScript

In JavaScript, we need to construct a GlobalNode handle to be able to call getValue and setValue as shown below:

import { $ld, $RegisterClass, $ConstructClass } from "loader";

function HelloWorld(ctx, firstname, surname) {
  var globalsNode = $ConstructClass(
    ctx,
    "blackboard.construct_GlobalsNode",
    null
  );
  var age = globalsNode.getValue(ctx, "age");
  console.log(
    "Hello world ! My name is " +
      firstname +
      " " +
      surname +
      ". I'm " +
      age +
      "."
  );
  globalsNode.setValue(ctx, "hasSaidHello", true);
}
$ld.registerCallable(null, "my-entrypoint-func", HelloWorld);

Visual Script

In the visual flow editor, you can leverage Get Global and Set Global node to manage global values: