Skip to main content

Configuration

This section describes the configuration object in depth.

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.

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 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

parallel and sequential are accepted as legacy aliases for dynamic. Do not use them in new code.

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 pipelines 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.

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 states, each state is just an object with id. Could be used to store data from onInit hook, or some derived state based on scripts inputs/outputs. These states could be used in links the same way as scripts inputs/outputs.

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.

structureCheck​

Optional

A synchronous function that could do checks on dynamic workflow items themselves (not just inputs/outputs). Receives PipelineOutline input, should return ValidationResult or undefined. Could be used to check an order of steps and give a user errors/warnings if the current dynamic workflow steps state has issues. ValidationResult is the same as described here.

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.

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.

Action steps​

An action step is a lightweight step type designed to display pipeline-level actions in a dedicated place within the workflow tree. Under the hood it is a static pipeline 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 pipeline to the action step, giving them their own card-based UI.

The only required fields are id and type: 'action'. Optional fields: friendlyName, description, tags.

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 structureCheck 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.

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 restrictions here.

viewersHook (Script node)​

Optional

Is a JavaScript function that is used to tweak options of DG.Viewer, potentially based on metadata state. More information about metadata links is available here. Here is the TypeScript signature of viewersHook:

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

ioName is the name of input/output and type is a type of the viewer.

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.

Edge cases​

Keep the following constraints in mind when designing workflows:

  • 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 behavior.
  • 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.
  • Link handler execution order. When multiple links target the same node, they are sorted by nodePriority (higher values run first, default is 0). Links with the same priority execute in traversal order. This applies regardless of which links array the links are defined in.