Run from code

You can start a workflow from code and, if the top-level configuration defines an onReturn hook, receive a return value when the user exits the workflow with the Confirm data button (the check icon in the toolbar). On a regular close, the workflow resolves to undefined.

The result flows like this:

1. The user clicks Confirm data.
2. The onReturn handler runs and calls controller.returnResult(value).
3. Your awaited startWorkflow(...) resolves to that value.

Basic usage

import {startWorkflow} from '@datagrok-libraries/compute-api';

const result = await startWorkflow<MyReturnShape>('SomePackage:SomeWorkflow', '1.0', {});

nqName (first argument) is the workflow provider's package:function identifier. version is passed to the provider in its params, and selects the configuration version the provider returns. It is usually the configuration's version, or one of the versions the provider's meta.versions annotation lists. The third argument is the initial PipelineInstanceConfig; pass {} to start with the provider's defaults.

With initial configuration

For dynamic workflows you can pre-populate the initial step list and per-step values by passing a PipelineInstanceConfig as the third argument. LSP fills in the recursive field shape.

import {startWorkflow} from '@datagrok-libraries/compute-api';
import type {PipelineInstanceConfig} from '@datagrok-libraries/compute-api';

const instanceConfig: PipelineInstanceConfig = {
  id: 'some_workflow',
  steps: [{
    id: 'load',
    initialValues: {deviceClass: 'Bioreactor Class'},
    inputRestrictions: {deviceClass: 'disabled'},
  }],
};

const result = await startWorkflow<MyReturnShape>(
  'SomePackage:SomeWorkflow',
  '1.0',
  instanceConfig,
);

initialValues and inputRestrictions follow the same semantics as the script node fields of the same name. See Consistency for the meaning of restriction values. initialValues of a script step may also hold output values: a step with any output value starts as run, so links that write into it mark its inputs inconsistent instead of changing them.

A workflow entry without steps gets the defaults from its configuration: the steps of a static workflow or the initialSteps of a dynamic one, expanded all the way down. Pass steps: [] for an empty workflow. A listed steps array is built as given, for static workflows too.

On a workflow entry, initialValues fills its states, and skipOnInit: true skips its init hook:

const instanceConfig: PipelineInstanceConfig = {
  id: 'some_workflow',
  initialValues: {startedBy: 'batch import'},
  skipOnInit: true,
  steps: [{id: 'load'}],
};