Configuration

This section describes the configuration object in depth.

Type reference

Install @datagrok-libraries/compute-api in your package. It re-exports every type referenced on this page — PipelineConfiguration, ValidationResult, all the handler and controller interfaces, PipelineInstanceConfig, PipelineOutline, etc. With those types in scope, your IDE will autocomplete field names and surface required fields as you type, so the prose below focuses on the meaning of each option rather than its TypeScript shape.

Getting started

Workflow providers

An example of a minimal workflow package setup is available here. To register a workflow, create a package function (called a provider) with at least these annotations:

//tags: model
//editor: Compute2:TreeWizardEditor
//input: object params
//output: object result

editor tag is a system tag used by the platform to launch a workflow. Tag model means that it will be added to ModelHub. The function must return an object of type PipelineConfiguration, and accept an input object containing a version field. This structure allows multiple workflow versions to coexist simultaneously.

PipelineConfiguration is a workflow configuration, which is used to define a set of steps and workflow options. Where step is either another workflow, a workflow reference or a script node. Depending on a workflow type, steps are configured slightly differently.

PipelineConfiguration is a discriminated union keyed on the type field:

type value	Variant
'static' (default)	Static workflow — fixed steps array.
'dynamic'	Dynamic workflow — user can add/remove steps from stepTypes.
'action'	Action step — lightweight placeholder, no children.
'ref'	Workflow reference — replaced at load time by another provider's configuration.

Leaves of the tree are script nodes, which use type: 'step' (or omit type).

General conventions

Configuration is a tree of JavaScript objects and arrays of type PipelineConfiguration.

• Most objects will have a mandatory id field, for definitions object id should be unique inside an array, for reference arrays id might be repeated.
• If a field could have configuration objects of different types, field type is used to specify the type. TypeScript will figure out the type of the object and its fields by type field.
• If an item has a corresponding UI element, usually a field friendlyName could be used to customize it.

Common options

Common configuration options

The following fields are available for PipelineConfiguration of types static and dynamic.

id

This id is used in links for paths.

type

There are two workflow types, an action step type, and a reference type, specified by the type field:

• static
• dynamic
• action
• ref

Static workflow is an immutable sequence of steps. It is using field steps to define its steps.

Dynamic workflows have a mutable set of steps that users can add, remove, and reorder at runtime. They use the stepTypes field to define available step templates.

Action step is a lightweight placeholder designed to display actions from outer workflows via visibleOn. It has no child steps and no history.

References are used to reuse configurations returned by providers. References have a different set of fields; however, they are effectively replaced by a workflow configuration.

nqName

This is a full name of the corresponding provider, containing package name and the script name, separated by :. This field is only applicable for workflow references and is not used for nested workflows that are not references.

version

This is just a string, should match a provider input. Not used for nested workflows that are not references.

friendlyName

Optional.

A user-friendly name of a workflow, will be shown in UI.

links

Optional

Links specification, described here.

actions

Optional

Actions specification, described here.

onInit

Optional

Init hook specification, described here.

onReturn

Optional

Return hook specification, described here.

states

Optional

A list of workflow-scoped state slots, declared as an array where each entry is either a bare string id ('meta1') or an object with optional extra fields ({id: 'meta1'}). Both forms may be mixed in the same array. Each id becomes addressable from LQL queries at the same path level as a script IO — but it lives on the workflow itself, not on any script. Use states for:

• values populated once by the onInit hook (for example, the current user, a server-loaded constant, the workflow start time);
• derived values computed from one or more downstream scripts (a summary that several validators want to share);
• bookkeeping flags that links and meta handlers can read.

A state's lifetime matches the workflow instance: it is created when the workflow loads and destroyed when the workflow closes. Writes happen through the usual link controller methods (setAll for data links, setViewMeta for meta links, etc.); reads happen via getFirst / getAll like any other input.

tags

Optional

A list of strings. The primary use case is for annotating that a step/workflow has a certain structural invariant, like the interface concept in programming. Could be matched in links.

forceNavigate

Optional

Will force navigate to the workflow view when using back/next buttons. By default non-empty workflows views will be skipped.

disableHistory

Optional

Disables workflow history, useful for nested workflows with nqName set to an empty function with a help file.

customExports

Optional

An array of items, with id, friendlyName and handler, used to define custom exports for workflow data. Handler here is an async function that receives PipelineState and ExportUtils arguments. More information is available here

disableDefaultExport

Optional

Disables the default export, custom exports if provided still can be used.

Workflow types

Static workflows

steps

Is an array of nested PipelineConfiguration items or script node . Each item must have a unique id. This array defines an immutable sequence of steps, but if nested workflows are dynamic, those could be internally mutated.

Dynamic workflows

stepTypes

Is an array of nested PipelineConfiguration items or script node . Each item must have a unique id. There are additional options per each item. Users might add/remove/reorder items from this list during the workflow.

initialSteps

Optional

Is an array of initial steps. Each item is a reference to a stepTypes item, written either as a bare string id ('stepAdd') or as an object with optional initialValues and inputRestrictions. Both forms may be mixed in the same array. The same shorthand applies to the steps array passed at runtime via setPipelineState.

Action steps

An action step is a lightweight step type designed to display workflow-level actions in a dedicated place within the workflow tree. Under the hood it is a static workflow with no child steps and no history. Action steps are always included in the back/next navigation sequence.

Use action steps with visibleOn to route actions from an outer workflow to the action step, giving them their own card-based UI.

id (Action step)

Same as the common id — used in links for paths. Must be unique inside its parent array.

type (Action step)

Must be 'action'. Distinguishes the action step from other variants of PipelineConfiguration.

friendlyName (Action step)

Optional

A user-friendly name for the action step, shown in the navigation tree.

description (Action step)

Optional

Free-form description shown in the action step's UI card.

tags (Action step)

Optional

Same as workflow tags — a list of strings that links can match via tag selectors.

Step definitions

Script nodes

These are end nodes in the configuration graph aka leafs. These nodes provide additional configuration for scripts.

id (Script node)

This id is used in links for paths.

nqName (Script node)

Mandatory script full name.

type (Script node)

Optional

Could be omitted, but the only other possible value is step.

friendlyName (Script node)

Optional

A user-friendly name of a script to show in UI.

actions (Script node)

Optional

Same as workflow actions

tags (Script node)

Optional

Same as workflow tags

initialValues (Script node)

Optional

A key-value object of input initial values. Will override scripts own initial values. Note Initial values don't trigger links, so there should be no data links that are dependent only on inputs with initial values.

inputRestrictions (Script node)

Optional

A key-value object with input initial restrictions. Used with initialValues. Read more about restriction values in Consistency.

viewersHook (Script node)

Optional

A JavaScript function that lets you customize each DG.Viewer that the platform renders for a script IO, optionally reacting to metadata published by meta links. Signature:

(ioName: string, type: string, viewer?: DG.Viewer, meta?: any) => void;

• ioName — the name of the script input or output the viewer is bound to.
• type — the DG.Viewer type string (e.g. 'Scatter plot').
• viewer — the live viewer instance, or undefined if not yet attached. Mutate it in place (viewer.setOptions(...), change column bindings, attach event listeners). The return value is ignored.
• meta — the merged metadata bag for this IO. The hook is re-invoked whenever the metadata changes, so reading from meta is how you make the viewer reactive.

The hook fires once per (ioName, viewer type) combination when the viewer appears, and again on every metadata update. Keep it side-effect-free aside from mutating the supplied viewer.

Additional stepTypes items options

For dynamic workflows, the stepTypes array has additional options available that limit a user's ability to alter the workflow. If more validation logic is needed, a pipelineValidator link can be used.

disableUIAdding

Optional

This dynamic item type cannot be added from the UI.

disableUIRemoving

Optional

This dynamic item type cannot be removed from the UI.

disableUIDragging

Optional

This dynamic item type cannot be dragged from the UI.

disableUIControlls

Optional

Disables all of the above.

Reuse and export

Reusing workflows

It is done using a reference object. A returned by the provider function object will just replace a ref object.

id (Reference)

Optional

Not used, id of the returned workflow will be used.

type (Reference)

ref must be provided to distinguish from other configuration types.

provider (Reference)

nqName of the provider function.

version (Reference)

A version string that will be passed as an argument to the provider function.

Workflow versioning

There may be multiple workflow versions available, so to allow a user to launch different workflow versions directly, the following provider function annotation could be used.

//meta.versions: ["2.0", "1.0"]

Note that all versions must not be removed or altered in a non-compatible way, regardless of the meta-annotation, otherwise user's saved state of such workflows could not be loaded. Non-compatible here means that is not possible to get the same results with the same steps and inputs.

For a toplevel workflow all saved users's data across all versions is available.

For nested references items only a specific version workflow data is available.

When creating a new workflow version, all dependent workflows that need to use the updated dependency must also release new versions. This ensures proper version compatibility across the workflow ecosystem.

Custom exports

A custom export function receives two arguments

• treeState of type PipelineState
• utils of type ExportUtils

Export utils contain 4 methods that could reuse standard existing export logic:

• reportFuncCallExcel - creates a standard xlsx blob and exceljs workbook for function call, returns [Blob, ExcelJS.Workbook].
• getFuncCallCustomExports - returns a list of custom exports defined specifically for a particular Func, returns string[].
• runFuncCallCustomExport - runs a custom export defined on a Func based on export name. Returns whatever a custom export returned.
• reportStateExcel - creates a standard xlsx tree export, however for each call an optional callback will be called (if provided). Returns [Blob, Zippable, string], where 3rd is the name of a file.

The callback in reportStateExcel receives an object with the following fields:

• fc: DG.FuncCall
• wb: ExcelJS.Workbook
• archive: Zippable
• path: string[]
• fileName: string
• isOutputOutdated?: boolean
• runError?: string
• validation?: Record<string, ValidationResult>
• consistency?: Record<string, ConsistencyInfo>
• description?: Record<string, string | string[]>

This allows to reuse most of the tree export logic, however individual exceljs workbooks could be customized or replaced/augmented with a different file.

Constraints and review checklist

Use this section as a sanity check before publishing a workflow. The platform will not reject a configuration that violates these guidelines — most of them produce silent misbehaviour instead — so it is worth walking the checklist deliberately.

Topology constraints:

• No cycles in data links. Data links can only reference the same node or nodes that come later in the depth-first traversal order of the tree. Backward references are not supported and will cause undefined behaviour.
• Transitive I/O dependencies require nodePriority. By default, dependencies between inputs/outputs of the same node are not tracked automatically. If you need a chain of links within one node (e.g. a → b → c on the same step), assign nodePriority values to ensure correct execution order — higher-priority links run first. Without explicit priorities, the execution order of same-node links is not guaranteed.
• At most one data link per script input. Multiple data links writing to the same script input race against each other. Use a single data link, or switch the secondary writers to validators / meta links.

Per-link review:

• LQL paths resolve. Every from / to / base segment matches a step id, a script IO name, or a tag that exists in the current configuration. Typos here silently prevent the link from ever firing.
• Restrictions are intentional. When using defaultRestrictions or setAll(..., restriction), pick the value that matches the intended UX: disabled (locked), restricted (editable, marks inconsistency on edit), info (editable, tracked but never marks inconsistency), none (write through with no tracking). See Consistency.

Package structure check:

• Import types from @datagrok-libraries/compute-api, not from @datagrok-libraries/compute-utils (internal paths).
• Provider function has the required annotations. Without them the workflow does not appear in ModelHub.
• Publish with grok publish --release. Debug-mode packages are only visible to the publisher.