User Guide

Synapse-Workflow-Examples User Guide

Synapse-Workflow-Examples is a Rapid Power-Up that ships example Workflows alongside the documentation for building your own.

To try out the example Workflows, install the Synapse-Workflow-Examples Power-Up and open the Workflows tool in Optic. Expand the synapse-workflow-examples package in the sidebar to see the Workflows it provides.

To read the examples, browse the public synapse-workflow-examples repository on GitHub – each example is its own source YAML file under workflows/, with comments and the surrounding package definition intact.

We strongly recommend validating Workflow YAML against the provided JSON Schemas both during development (in your editor) and in CI/CD pipelines.

Optic Workflows

A Workflow is a declarative description of a piece of Optic UX (its Elements, their layout, and their reactive behavior) distributed inside a Storm package. Workflows are defined under the package’s optic key and rendered by the Workflows tool in Optic.

A Workflow is composed of:

Elements – the visual / interactive pieces of the Workflow. Each Element declares a type that determines what it displays and how the user interacts with it (e.g. stormform, datatable, stormtable, nodeviewer, textarea, markdown, stormeditor). See the Element Reference for the full list and the opts each type accepts.
Layout – where each Element sits in the Workflow grid.
Events, Actions, and vars – the wiring that lets Elements react to user input, to each other, and to Storm.

Each Element maintains a bag of named variables (its vars). Vars live in the browser for the duration of the Workflow session and can come from user input, other Elements, Storm queries, or any combination of these. Reference a var by bare name (myvar) or with a $ prefix for clarity ($myvar); nested dict and array values can be addressed with dotted paths such as $mydict.somekey and $myarray.0.

An Action is an operation executed by an Element in response to a trigger – a subscribed event or direct user input (e.g. clicking a button, submitting a form). Actions can update vars, run Storm queries, render Nodes, surface UI feedback (toasts, spinners, modals), open or navigate to another Workflow, and more. The full catalog appears under Workflow Actions below.

Events are the messages that fan data between Elements. An Element subscribes to events from another Element via subs and declares per-event-type Action lists in its events block; when a matching event arrives, the listed Actions run. See Workflow Events for the available Event types.

Workflows can also coordinate with each other. A Workflow can open another in a modal (openmodal), navigate to it directly (navworkflow), or be launched from the Research tool via Node actions configured on a Storm package.

When designing a Workflow, consider:

Elements – what to display and how to display it.
Layout – how the Elements are arranged in the grid.
Events – which events should fan data between Elements.
Actions – what each Element should do in response to user input or a subscribed event.
Coordination – which other Workflows might open this one, or be opened from it.

Elements

Elements are the primary unit of composition in a Workflow. Each Element can have one or more responsibilities in the Workflow, including displaying data and Nodes, accepting user input, and running Storm queries that CRUD Nodes.

Type-specific opts (the opts object on each Element) are documented per Element type in the Element Reference.

Common Element Properties

Every Element, regardless of type, accepts the following top-level properties. These are applied uniformly across all Element types and are not repeated in the per-Element reference.

Property	Type	Required	Description
`type`	`string`	-	The Element type, e.g. `textarea`, `stormform`, `datatable`. Determines what `opts` are accepted.
`title`	`string`		Title rendered in the Element titlebar.
`opts`	`object`		Type-specific options for the Element. See the Element Reference.
`doc`	`{ markdown: string, tooltip: string }`		Documentation for the Element: tooltip on hover and/or markdown displayed via the Element doc icon.
`disabled`	`string` \| `boolean`		If the Element should be disabled (non-interactive, grayed out). Accepts a static boolean or a `$var` that resolves to a boolean.
`hidden`	`string` \| `boolean`		If the Element should be hidden. Accepts a static boolean or a `$var` that resolves to a boolean.
`style`	`{ border: boolean }`		Basic styling overrides for the Element chrome.
`spinner`	`boolean`		If the Element should display a query-status spinner in the titlebar (drivable from `storm` Actions).
`menu`	`{ items: MenuOption[] }`		Hamburger-menu options to be displayed in the titlebar.
`buttons`	`Button[]`		Buttons positioned in the Element titlebar to the left of the menu. Defined the same way as the entries on a `buttons` Element.
`subs`	`EventSubscription[]`		Subscriptions to events from other Elements; see Subscriptions and Events.
`events`	`{ onnodes: Action[], onvars: Action[] }`		Actions to execute when a subscribed event arrives, keyed by event type.
`oninit`	`Action[]`		Actions to execute before first render. Useful for initializing vars via `updatevars` / `getvars`.
`onload`	`Action[]`		Actions to execute immediately after first render.
`onloaded`	`Action[]`		Actions to execute after every Element in the Workflow has finished its `onload`.
`onchangeview`	`Action[]`		Actions to execute when the user’s active View changes.
`defs`	`any`		YAML anchor scope. Has no runtime effect; useful for defining `&anchor` blocks that are aliased elsewhere in the Element definition.

Subscriptions and Events

The subs array declares which Elements (and which Event types from each) the current Element should receive Events from:

subs:
  - src: my-stormtable
    events: [ onnodes ]

Each subscription has an src (the iden of the source Element, or the literal $workflow for Workflow-wide events) and an events list (currently onvars and/or onnodes).

The events block then defines the Actions to run when a subscribed Event arrives:

events:
  onnodes:
    - type: loadnodes
  onvars:
    - type: refresh

Element Lifecycle

Elements have three lifecycle hooks for executing Actions outside of subscribed Events:

oninit - runs before the Element renders for the first time. Use it to seed vars (updatevars) or fetch initial state (getvars, callstorm).
onload - runs immediately after the Element’s first render. Use it for setup that needs the rendered DOM to exist (e.g. firing an initial event, focusing a field).
onloaded - runs after every Element in the Workflow has finished its onload. Use this when an Action needs the whole Workflow to be ready (e.g. propagating an initial selection across coordinated Elements).

Type-Specific Opts

Detailed reference documentation for each Element type and the opts it accepts lives in the Element Reference.

Workflow Layout

A Workflow’s top-level layout property controls how its Elements are arranged on screen. Two layout types are supported, distinguished by the type discriminator:

default – the GridStack layout. Elements are placed on a uniform grid via integer x / y cell coordinates with w / h cell spans. Best for traditional dashboard-style layouts with regular cells; this is what’s used when no layout is specified.
cssgrid – a CSS Grid layout. Elements are placed by named area (via grid-template-areas) or line-based syntax, with full control over column and row tracks and gaps. Best when you need non-uniform sizing, responsive behavior, or named regions.

Element placement always lives in layout.elements, keyed by Element iden. Older Workflows may carry an inline layout property on each Element as a backwards-compatibility shim; this form is deprecated and new Workflows should declare every position in the top-level layout.elements block instead.

GridStack layout (`default`)

Property	Type	Required	Default	Description
`type`	`default`	-		Layout discriminator.
`cellheight`	`number`		`48`	Row cell height in pixels.
`elements`	`{ <iden>: { x: number, y: number, w: number, h: number } }`			Per-Element placement, keyed by Element iden. Each entry is a cell-coordinate object.

Each elements entry is a { x, y, w, h } object where x / y are the (zero-based) column / row coordinates of the top-left cell and w / h are the column / row spans.

Example:

layout:
  type: default

  elements:
    toolbar:       { x: 0, y: 0, w: 12, h: 1 }
    results-table: { x: 0, y: 1, w: 8,  h: 6 }
    node-detail:   { x: 8, y: 1, w: 4,  h: 6 }

CSS Grid layout (`cssgrid`)

The cssgrid layout exposes the standard CSS Grid model. rows, cols, gap, and areas accept anything their underlying CSS counterparts (grid-template-rows, grid-template-columns, gap, grid-template-areas) accept. If elements placement is omitted, Elements auto-flow into the grid in declaration order.

Property	Type	Required	Default	Description
`type`	`cssgrid`	-		Layout discriminator.
`rows`	`string` \| `string[]`		`auto`	CSS `grid-template-rows`. Arrays are joined by spaces.
`cols`	`string` \| `string[]`		`auto`	CSS `grid-template-columns`. Arrays are joined by spaces.
`gap`	`string` \| `string[]`		`0px`	CSS `gap`. Arrays are joined by spaces (e.g. `[20px, 0]` for separate row / column gaps).
`areas`	`string`			CSS `grid-template-areas`. Use a YAML literal block scalar to preserve newlines.
`elements`	`{ <iden>: <grid-area> }`			Per-Element placement. Each value is either a named area defined in `areas` or a line-based `<rowstart> / <colstart> / <rowend> / <colend>` string.

Example (auto-flow):

layout:
  type: cssgrid

  rows: repeat(2, minmax(512px, 1fr))

Example (named areas):

layout:
  type: cssgrid

  cols: 1fr 1fr 200px
  gap: 12px

  areas: |
    header header  sidebar
    main   main    sidebar
    footer footer  footer

  elements:
    title-bar:     header
    results-table: main
    filters:       sidebar
    legal:         footer

Example (line-based placement):

layout:
  type: cssgrid

  cols:
    - 1fr
    - 1fr
    - 200px
  rows: auto 1fr 40px

  elements:
    # <rowstart> / <colstart> / <rowend> / <colend>
    title-bar:     1 / 1 / 1 / 4
    results-table: 2 / 1 / 3 / 3
    filters:       2 / 3 / 3 / 4
    legal:         3 / 1 / 4 / 4

See CSS Grid Layout on MDN for the full CSS Grid model – grid-template-areas, grid-template-rows / grid-template-columns, grid-area, and gap are all passed through unchanged.

Workflow Events

A Workflow Event is a message broadcast inside a Workflow. An Element subscribes to events from another Element via subs and declares per-event-type Action lists in its events block; when a matching event arrives, the listed Actions run. Events can also cross Workflow boundaries through opt-in mechanisms such as openmodal.subs, which lets an opening Workflow subscribe to Events from Elements in the modal Workflow it just opened.

Two Event types are currently defined:

onvars

Carries the source Element’s vars to subscribers. Inbound vars are automatically merged into each subscribing Element’s var bag. Subscribers typically rerender after handling an onvars Event – either directly from the new vars or after running a Storm query that uses them.

onnodes

Carries one or more Nodes from the source Element to subscribers. While handling an onnodes Event, the inbound Nodes are available to the updatevars Action’s nodes operation and to Storm queries as inbound nodes via the idens query opt.

Workflow Actions

An Action is an operation executed by an Element in response to either an Event or user input. There are many types of Actions that can have a wide variety of effects on the UX of the Workflow.

Each Action is a YAML object with a type field selecting the Action and an opts object holding the type-specific options. Actions are run sequentially in the order they are defined; the chain can be cut short with a stop Action.

The Action Opts table for each Action below summarizes the available options at-a-glance. Opts whose behavior is more nuanced than a single table cell can convey are followed by a deeper-dive paragraph (and additional examples) below the table.

eventfire

Fire an Event into the Workflow, allowing other subscribed Elements to react to the provided data. The Event is fired from the executing Element, so subscribers must list the executing Element’s iden in their subs to receive it.

Property	Type	Required	Default	Description
`event`	`onnodes` \| `onvars`	-		The type of event to fire.
`vars`	`string[]`			For `onvars` events, optionally limit the propagated vars to a specific subset. If omitted, the Element’s full var set is fired.

# fire an onvars Event with only $selected and $mode propagated to subscribers
type: eventfire
opts:
  event: onvars
  vars: [selected, mode]

nodesfire

Fire an onnodes Event into the Workflow. The fired Nodes typically come from the executing Element’s currently rendered or selected Nodes (e.g. a stormtable selection), or from the onnodes Event that the Action is currently handling.

Property	Type	Required	Default	Description
`selected`	`boolean`			If `true`, only fire the currently selected Nodes instead of all rendered Nodes.
`propagate`	`boolean`			If `true`, include the Nodes currently being handled in the fired Event. Only applicable when this Action is executed while handling an `onnodes` Event.

# fire only the user's currently selected Nodes from a stormtable
type: nodesfire
opts:
  selected: true

# propagate the inbound onnodes payload back out as a fresh nodesfire
events:
  onnodes:
    - type: nodesfire
      opts:
        propagate: true

openmodal

Open another Workflow in a modal. Additional opts pass data into the target Workflow and create temporary subscriptions to its Events so the source Element can update while the modal is open. Subscriptions made via subs are torn down automatically when the modal closes.

Property	Type	Description
`iden`	`string`	The iden of the Workflow to open. Required unless `workflow` is provided.
`workflow`	`object`	Optionally define the target Workflow inline instead of referencing one by iden. Ignored if `iden` is set.
`title`	`string`	An optional title to be displayed in the modal header.
`titlevar`	`string`	Resolve the modal title from a var on the source Element.
`dimensions`	`object`	Optional `{ width, height }` overrides for the modal.
`subs`	`EventSubscription[]`	Subscribe to events from Elements inside the opened Workflow.
`events`	`object`	Actions to run for each subscribed Event from the modal Workflow.
`onclose`	`Action[]`	Actions to execute after the modal closes.

subs / events

The subs array declares Elements inside the opened Workflow whose Events the source Element wants to receive while the modal is open; events then maps each Event type to the Actions to run on receipt. Both subscriptions and the Actions wired up here are torn down automatically when the modal closes.

type: openmodal
opts:
  iden: ex-pkg-detail-modal
  title: Node Detail
  dimensions:
    width: 800
    height: 600
  subs:
    - src: detail-stormtable
      events: [onnodes]
  events:
    onnodes:
      - type: loadnodes
  onclose:
    - type: refresh

closemodal

Close a specific modal Workflow. Most useful inside Actions defined for a temporary subscription in openmodal.events so that the source Workflow can decide when to dismiss the modal.

Property	Type	Required	Default	Description
`iden`	`string`			The iden of the Workflow modal to close. Defaults to the current modal Workflow.

type: closemodal

loadingmodal

Display (or hide) a modal loading spinner while waiting on other operations. Repeated calls within the opendelay window are coalesced so that brief operations don’t flash a modal at the user.

Property	Type	Description
`show`	`boolean`	If the loading modal should be shown (`true`) or hidden (`false`). Toggles the current state when omitted.
`title`	`string`	Title text shown next to the spinner.
`titlevar`	`string`	Resolve the title from a var on the Element.
`opendelay`	`number`	Milliseconds to wait before actually showing the modal. If a subsequent `loadingmodal` with `show: false` arrives before the delay elapses, the modal never opens.

# show the loading modal, but only if the work doesn't finish within 250ms
type: loadingmodal
opts:
  show: true
  title: Enriching nodes...
  opendelay: 250

navworkflow

Navigate the user to another Workflow in the Workflows tool. The current Workflow is replaced. After the target Workflow has rendered, an onvars and/or onnodes Event can be sent into it for initial render, provided the target Workflow declares matching subscriptions.

Property	Type	Required	Default	Description
`iden`	`string`	-		The iden of the Workflow to navigate to.
`events`	`string[]`			Event types (`onnodes`, `onvars`) to fire into the target Workflow after it has rendered.

# navigate to a sibling Workflow and seed it with the current selection
type: navworkflow
opts:
  iden: ex-pkg-detail
  events: [onvars, onnodes]

researchquery

Provide a Storm query (or a var to resolve one from) and navigate the user to the Research tool to execute it. Optionally select the display mode and storm mode for the Research tool.

Property	Type	Default	Description
`query`	`string`		A static Storm query to execute in the Research tool.
`queryvar`	`string`		Resolve the query from a var on the executing Element. One of `query` or `queryvar` must be provided.
`displaymode`	`force` \| `geospatial` \| `stats` \| `table` \| `timeline` \| `tree`		The Research tool display mode the query should be executed in. Defaults to the user’s current mode.
`stormmode`	`autoadd` \| `lookup` \| `search` \| `storm`	`storm`	The Research tool storm mode. Defaults to `storm` and changes the user’s current mode if necessary.

type: researchquery
opts:
  queryvar: pivotquery
  displaymode: table
  stormmode: storm

browsernav

Open a URL in a new browser tab. The URL can be supplied statically or via a var.

Property	Type	Required	Default	Description
`url`	`string`			A static URL to open.
`urlvar`	`string`			The name of a var holding the URL to open. One of `url` or `urlvar` must be provided.

type: browsernav
opts:
  urlvar: targeturl

storm

Run a Storm query and render the yielded Nodes according to the Element type. The executing Element’s vars are passed into the query. This Action has a variety of opts that can change its behavior. One of either query or queryvar must be set to provide the query to execute.

Property	Type	Default	Description
`query`	`string`		The Storm query to execute. Yielded Nodes are rendered by the executing Element.
`queryvar`	`string`		Resolve the Storm query from a var on the Element.
`inboundnodes`	`string`		A var holding Nodes to inbound to the query when not handling an `onnodes` Event.
`render`	`boolean`	`true`	Set `false` to suppress rendering the yielded Nodes; useful when the Element only cares about side effects.
`spinner`	`boolean` \| `string` \| `object`		Reflect the query’s running state into a spinner.
`feed`	`object`		Forward Storm messages from this query into other Elements.
`console`	`object`		Forward Storm messages to a `stormconsole` Element or the global Console.
`queryopts`	`object`		Extra Synapse Storm Opts for the query. `view`, `idens`, and `vars` are not allowed.
`onstormvars`	`Action[]`		Actions to execute when the Storm query yields workflow var messages (set / update / del / clear).

inboundnodes

Allows supplying inbound nodes to the query from a var when not handling an onnodes Event. This is useful when it is necessary to inbound nodes to a query that is not in direct reaction to an onnodes event. Nodes are inbounded to the query in the same way as handling an onnodes Event via the Storm query opt idens. Note that this opt will be ignored when the Action is handling an onnodes Event.

Example:
# handle an onnodes event and stash the nodes in the $stashednodes var.
events:
  onnodes:
    - type: updatevars
      opts:
        operations:
          - type: nodes
            name: $stashednodes
            path: $nodes

# ... the rest of your Workflow ...

# later (e.g. user button click or other interaction) run a Storm query with the nodes from $stashednodes inbound.
type: storm
opts:
  # pivot from the inbound nodes to inet:ipv4 nodes
  query: -> inet:ipv4
  inboundnodes: $stashednodes

spinner

Configure any spinners that should reflect the running status of the query. Can be set to true to bind to the spinner on the executing Element, the iden of another Element to bind to that Element’s spinner, or a dict with element and button values to spin a button on a particular Element. button requires idx (the zero-based index of the button; titlebar buttons are first, followed by Element-type buttons), and may provide temporary spinningtext to override the button text while the spinner is active.

Example:
spinner:
  element: <elementiden>
  button:
    idx: 0
    spinningtext: 'Updating...'

feed

Forward Storm messages from this query into other Elements. Each entry maps a target Element iden to either a list of Storm message types to forward, or true to forward all messages. This lets one Element drive a query while distributing the results across several display Elements (e.g. a querybar running a query that fills a stormtable and logs to a stormconsole).

Example:
feed:
  ex-stormtable: [node]
  ex-other-selective: [node, warn, err]
  ex-other-all: true

console

Forward Storm messages to either a stormconsole Element in the Workflow or the global Console tool. mesgs filters the forwarded message types; omit it to forward everything. clear: true clears the target console before the query runs.

Workflow stormconsole Element:
console:
  iden: ex-stormconsole
  clear: true
  # optionally output only specified message types
  # mesgs: [print, warn, err]
Global Console:
console:
  global: true
  # optionally output only specified message types
  # mesgs: [print, warn, err]

# run a query, render the resulting nodes, and spin the executing Element's spinner
type: storm
opts:
  query: inet:fqdn=$fqdn -> inet:dns:a -> inet:ipv4
  spinner: true

callstorm

Run a query using callStorm and handle the return value according to the Element type. The executing Element’s vars are passed into the query. Unlike storm, callstorm does not yield Nodes; the query must return(<value>) and the executing Element consumes that return value.

Property	Type	Required	Default	Description
`query`	`string`	-		The query to execute via `callStorm`. The query must `return(<value>)`; the expected shape depends on the executing Element.
`inboundnodes`	`string`			A var holding Nodes to inbound to the query when not handling an `onnodes` Event.

inboundnodes

Allows supplying inbound nodes to the query from a var when not handling an onnodes Event. This is useful when it is necessary to inbound nodes to a query that is not in direct reaction to an onnodes event. Nodes are inbounded to the query in the same way as handling an onnodes Event via the Storm query opt idens. Note that this opt will be ignored when the Action is handling an onnodes Event.

Example:
# handle an onnodes event and stash the nodes in the $stashednodes var.
events:
  onnodes:
    - type: updatevars
      opts:
        operations:
          - type: nodes
            name: $stashednodes
            path: $nodes

# ... the rest of your Workflow ...

# later (e.g. user button click or other interaction) run a callStorm query with the nodes from $stashednodes inbound.
type: callstorm
opts:
  inboundnodes: $stashednodes
  # do some operation on the nodes
  query: |
    [ :someprop=$newvalue ]
    return((true))

getvars

Run a query using callStorm that returns a dict of vars to set onto the executing Element. Each key in the returned dict becomes a var on the Element. Typically used in oninit to seed the Element with state derived from the Cortex.

Property	Type	Required	Default	Description
`query`	`string`	-		The Storm query to execute via `callStorm`. Must return a dict whose keys become vars on the Element.

type: getvars
opts:
  query: |
    return((
      {
        "displayname": $lib.user.profile.get(name),
        "defaulttag": "rep.foo",
      }
    ))

loadnodes

Render the Nodes from an onnodes Event payload according to the Element type. By default the Element’s currently rendered Nodes are replaced.

Property	Type	Required	Default	Description
`append`	`boolean`		`false`	If `true`, append to the currently rendered Nodes instead of replacing them.

# display every onnodes payload, accumulating across multiple events
events:
  onnodes:
    - type: loadnodes
      opts:
        append: true

selectnodes

Select Nodes that have already been rendered in the Element. Useful only in Elements that support Node selection (e.g. stormtable, datatable). When handling an onnodes Event the Event Nodes are selected by default; all and idensvar override that.

Property	Type	Required	Default	Description
`all`	`boolean`			Set `true` to select all currently rendered Nodes. Takes priority over Event Nodes and `idensvar`.
`idensvar`	`string`			A var resolving to an array of Node idens to select. Takes priority over Event Nodes.

type: selectnodes
opts:
  idensvar: pinnednodes

hidenodes

Hide rendered Nodes in the Element. When handling an onnodes Event the Event Nodes are hidden by default; all and idensvar override that.

Property	Type	Required	Default	Description
`all`	`boolean`			Set `true` to hide all currently rendered Nodes. Takes priority over Event Nodes and `idensvar`.
`idensvar`	`string`			A var resolving to an array of Node idens to hide. Takes priority over Event Nodes.

# hide every node currently rendered in the table
type: hidenodes
opts:
  all: true

selectdata

Select rendered data rows by iden. The data-row equivalent of selectnodes, used by Elements that render arbitrary record data (e.g. datatable).

Property	Type	Required	Default	Description
`idensvar`	`string`			A var resolving to an array of row idens to select.

type: selectdata
opts:
  idensvar: highlightrows

updatedata

Update rendered data rows in place. Used by Elements like datatable to mutate one or more rows without re-streaming the full table.

Property	Type	Required	Default	Description
`rowvar`	`string`			A var holding a single row dict to update.
`rowsvar`	`string`			A var holding an array of row dicts to update.

type: updatedata
opts:
  rowvar: editedrow

hidedata

Hide rendered data rows by iden. The data-row equivalent of hidenodes.

Property	Type	Required	Default	Description
`idensvar`	`string`			A var resolving to an array of row idens to hide.

type: hidedata
opts:
  idensvar: dismissedrows

updatevars

Update vars on the Element with a series of operations of different types. Each operation has type to specify the type of operation and name to specify the var to update.

Property	Type	Required	Default	Description
`operations`	`Operation[]`			The operations to execute to update the vars. See Operations.

Operations

Each entry in operations is one of the following types.

set

Set a var to a static value.

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to set.
`value`	`any`	-		A static value to set.

Example:

type: updatevars
opts:
  operations:
    - type: set
      name: $myvar
      value: 'My Static Value'

var

Set a var based on another var. Useful for plucking out nested vars to the top level as needed.

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to set.
`var`	`string`	-		The name of the var (or dotted path) to resolve to a value.

Example:

type: updatevars
opts:
  operations:
    - type: var
      name: $myvar
      var: $somenesteddata.subkey.foo

fmtstr

Set a var to a string using a format string syntax. Existing vars can be referenced, along with nodes in an onnodes Event currently being handled.

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to set.
`fmtstr`	`string`	-		A string with `{$var}` interpolations.

Var example:

type: updatevars
opts:
  operations:
    # using the $somevar var
    - type: fmtstr
      name: $mystr
      fmtstr: 'Hello {$somevar}!'

Nodes example:

# handling an onnodes Event
events:
  onnodes:
    - type: updatevars
      opts:
        operations:
          # using the first node from the onnodes Event we are currently handling
          - type: fmtstr
            name: $mystr
            fmtstr: 'Hello {$nodes.0.props.name}!'

toggle

Toggle the boolean value of a var. If the var is not set, the first toggle will set the value to true. If the var exists and is a boolean it will be toggled. If the var exists and is not a boolean a warning will be logged.

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to toggle.

Example:

type: updatevars
opts:
  operations:
    - type: toggle
      name: $mytoggle

del

Delete a var, resetting it to be undefined.

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to delete.

Example:

type: updatevars
opts:
  operations:
    - type: del
      name: $bye

callstorm

Set a var to the return value of a Storm query executed with callStorm.

Property	Type	Required	Description
`name`	`string`	-	The name of the var to set.
`query`	`string`	-	A query that should `return(<value>)`.
`inboundnodes`	`boolean` \| `string`		`true` to use the current `onnodes` Event payload, or the name of a var holding stashed Nodes.

Example:

type: updatevars
opts:
  operations:
    - type: callstorm
      name: $mystormreturn
      query: return(([1, 2, 3]))

nodes

Set a var from the Nodes in the onnodes Event currently being handled. path is a dotted path into the Event payload (e.g. $nodes.0.props.name).

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to set.
`path`	`string`	-		A dotted path into the array of Nodes (e.g. `$nodes.0.props.name`).

Example:

# handling an onnodes Event
events:
  onnodes:
    - type: updatevars
      opts:
        operations:
          # store the :name prop of the first node
          - type: nodes
            name: $nodename
            path: $nodes.0.props.name

          # store the entire node(s) for use with storm / callstorm Action inboundnodes opt.
          - type: nodes
            name: $stashednodes
            path: $nodes

clipboard

Set a var to the current contents of the system clipboard. Useful for paste-driven workflows where the user has already copied an iden, query, or value somewhere else.

Property	Type	Required	Default	Description
`name`	`string`	-		The name of the var to set.

Example:

type: updatevars
opts:
  operations:
    - type: clipboard
      name: $pastedvalue

delvars

Reset vars on the Element so they are no longer present. The bulk equivalent of a del updatevars operation, applied as a single Action across multiple vars.

Property	Type	Required	Default	Description
`vars`	`string[]`			List of var names to reset. If omitted, all vars on the Element are reset.

# clear out user-input vars on form reset
type: delvars
opts:
  vars: [searchterm, scopefilter]

updateopts

Update opts on the Element with a series of operations. Operations have the same shape as updatevars operations (see [Operations](#operations)), but the result is written into the Element’s opts rather than its vars. Most commonly used together with refresh to swap an Element into a new configuration at runtime.

Property	Type	Required	Default	Description
`operations`	`Operation[]`			The operations to execute to update the opts. Same shapes as `updatevars` operations.

# patch the columns and emptymesg opts on a datatable from current vars
- type: updateopts
  opts:
    operations:
      - type: var
        name: $columns
        var: $newcolumns
      - type: set
        name: $emptymesg
        value: 'No matching rows.'
- type: refresh

refresh

Refresh the Element from its current opts and vars. Has no opts. Pair with updateopts or updatevars when an Element needs to re-render after a runtime configuration change.

type: refresh

toast

Display a toast popup to let the user know about success, warnings, or errors. The message and title can be supplied statically or resolved from vars; the toast can also be mirrored to the global Console.

Property	Type	Default	Description
`mesg`	`string`		The message text to display in the toast.
`mesgvar`	`string`		Resolve the message from a var. Takes priority over `mesg` when set.
`title`	`string`		An optional title displayed above the message. For backwards compatibility, if the title matches a level keyword (`success`, `warn`, `error`) it is used as the level instead.
`titlevar`	`string`		Resolve the title from a var.
`level`	`error` \| `success` \| `verbose` \| `warn`	`'success'`	The toast level.
`levelvar`	`string`		Resolve the level from a var.
`timeout`	`number`	`3000`	Milliseconds to keep the toast visible. `0` keeps it open until the user dismisses it.
`console`	`boolean`	`true`	If `true` (the default), also write the message to the global Console tool. Set `false` to suppress.

type: toast
opts:
  level: success
  title: Done
  mesgvar: resultmesg
  timeout: 4000

stop

Stop the current chain of Actions. Has no opts. Typically used inside a filter to bail out of an Action chain after a warn / error toast or a failed validation step.

# bail out of the chain if validation failed
- type: callstorm
  opts:
    query: return($lib.dict(ok=$ok, mesg=$mesg))
- type: filter
  opts:
    cond: $not($ok)
    actions:
      - type: toast
        opts:
          level: error
          mesgvar: mesg
      - type: stop

sendfocus

Send focus to a specific Element or to a specific part of an Element when supported by the Element type. Useful for steering keyboard input after an Action chain (e.g. focusing the first field of a form after opening it).

Property	Type	Description
`field`	`string`	For `stormform` and `nodeeditor` Elements, the field to focus. `stormform` requires the field’s `iden`; `nodeeditor` requires the prop name.
`button`	`number`	For `buttons`, `stormform`, and `nodeeditor` Elements, the zero-based index of the button to focus.
`tabiden`	`string`	For `tabs` Elements, the iden of the tab to select (and focus).

# focus the 'searchterm' field on the form after rendering
type: sendfocus
opts:
  field: searchterm

setclipboard

Copy a value to the system clipboard as text. Either clipvalue (static) or clipvar (from a var) must be supplied.

Property	Type	Description
`clipvalue`	`string`	A static string to copy.
`clipvar`	`string`	The name of a var whose value should be copied.
`pretty`	`boolean`	If `true`, pretty-print the value (e.g. JSON-format an object) before copying.

type: setclipboard
opts:
  clipvar: shareableurl

uploadfile

Open a file upload modal that pushes the uploaded bytes into the active Cortex Axon. By default a file:bytes Node is created for each upload; that can be suppressed with skipcreatenode.

Property	Type	Default	Description
`multiple`	`boolean`	`false`	Allow selecting multiple files in the upload modal.
`accept`	`string`		Comma-separated list of accepted file extensions or MIME types (e.g. `'.pdf, .txt, image/*'`).
`header`	`string`	`'Upload File'`	Optional header text shown in the modal.
`uploadplaceholder`	`string`	`'Select a file'`	Placeholder text for the file upload input.
`urlplaceholder`	`string`	`'URL to download (https://os.int/file/intel.txt)'`	Placeholder text for the URL upload input.
`fileparsertoggle`	`boolean`	`false`	If `true`, show the `fileparser.parse` toggle in the modal.
`skipcreatenode`	`boolean`		If `true`, do not create a `file:bytes` Node for the uploaded bytes.
`filesvar`	`string`	`'$files'`	Name of a var that will be set to the array of SHA-256 hashes for the uploaded file(s).

type: uploadfile
opts:
  header: Upload report
  accept: '.pdf, .txt'
  multiple: false
  filesvar: uploadedshas

oauthreq

Initiate an OAuth2 authorization flow against a configured OAuth2 provider. The provider is identified by its iden, supplied either statically or via a var.

Property	Type	Required	Default	Description
`iden`	`string`			The iden of the OAuth2 provider to use.
`idenvar`	`string`			Resolve the OAuth2 provider iden from a var. One of `iden` or `idenvar` must be provided.

type: oauthreq
opts:
  iden: oauth-provider-iden

JSON Schemas

JSON Schemas that document and validate Workflows and Packages containing Workflows are available to download from your Optic instance:

Schema for a standalone Workflow yaml file
https://<youroptic>/schemas/workflow.schema.json

Schema for a package yaml file
https://<youroptic>/schemas/pkg-workflows.schema.json

Examples

Workflows are defined under the top-level optic key in a Storm package definition. Individual workflow definitions can be included in-line, or as a separate file in workflows/<workiden>.yaml. Files from the workflows/ directory are automatically embedded when the Synapse genpkg tool is used.

Workflow and Element iden values (keys in definition) must be unique, and can only include alphanumeric, _, or - characters. To avoid URL path collisions, workflow idens should be namespaced, e.g. <pkgname>-<workflow name>.

name: foopkg
version: 1.0.0

modules:
  - ...

commands:
  - ...

optic:
  displays:
    - title: Workflow title for Optic sidebar
      workiden: foopkg-inline
    - title: Another title
      workiden: foopkg-fromdir

  workflows:
    foopkg-inline:
        desc: An inline complete workflow definition
        ...

    # Additional workflows from ``workflows/`` directory would be included here by the Synapse genpkg tool

Packages can be generated (and pushed) using the Synapse genpkg tool.

User Guide

Synapse-Workflow-Examples User Guide

Optic Workflows

Elements

Common Element Properties

Subscriptions and Events

Element Lifecycle

Type-Specific Opts

Workflow Layout

GridStack layout (default)

CSS Grid layout (cssgrid)

Workflow Events

onvars

onnodes

Workflow Actions

eventfire

nodesfire

openmodal

closemodal

loadingmodal

navworkflow

researchquery

browsernav

storm

callstorm

getvars

loadnodes

selectnodes

hidenodes

selectdata

updatedata

hidedata

updatevars

Operations

set

var

fmtstr

toggle

del

callstorm

nodes

clipboard

delvars

updateopts

refresh

toast

stop

sendfocus

setclipboard

uploadfile

oauthreq

JSON Schemas

Examples

GridStack layout (`default`)

CSS Grid layout (`cssgrid`)