Workflows and Services

Use moi-cli workflow to inspect the node catalog, deploy and schedule MOWL workflows, track and recover workflow runs, confirm and publish editor candidates, restore authoring history, and publish workflows as dynamic API services. Complete Configuration and Authentication before running commands; omit --workspace-id when a default workspace is already saved in your local configuration.

Inspect the node catalog and deploy workflows

Inspect available node types and input contracts with workitem-catalog before deploying a native MOWL definition, then create or update the workflow application with workflow deploy:

# Inspect available nodes and a specific node definition
moi-cli -auth pat -o workflow workitem-catalog --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o workflow workitem-catalog-item \
  --workspace-id "$WORKSPACE_ID" \
  --node-id "<node-id>"

# List workflows in the workspace and read a workflow's details
moi-cli -auth pat -o workflow list --workspace-id "$WORKSPACE_ID" --limit 20
moi-cli -auth pat -o workflow get \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID"

Prepare a MOWL definition file workflow.json whose referenced volume files, models, and tables are accessible in the target workspace. When the workflow accepts runtime inputs, prepare fields.json to declare form fields and defaults.json for saved default values:

{
  "fields": [
    {
      "field_id": "text",
      "label": "Text",
      "widget": "text",
      "json_type": "string",
      "bind_to": "vars.text"
    }
  ]
}
{
  "text": "Sample text used to verify output"
}

Deploy the workflow with workflow deploy and save the returned application identifier workflow.id:

moi-cli -auth pat -o workflow deploy \
  --workspace-id "$WORKSPACE_ID" \
  --name 'Document Processing' \
  --workflow-file workflow.json \
  --runtime-fields-file fields.json \
  --default-values-file defaults.json \
  --execution-mode one_shot

In the response, workflow.id is the runnable workflow application ID used by subsequent run, update, and query commands, while deployment.workflow_def_id and deployment.workflow_version_id identify the underlying definition and version. Pass the same --workflow-id "$WORKFLOW_ID" to deploy when updating an existing workflow’s definition (--workflow-file and --dsl-yaml are mutually exclusive).

Start and track workflow runs

Save per-run input values as values.json:

{
  "text": "A small sample"
}

Submit the run request and track execution state and outputs using the returned identifier:

# Submit a run (omit --values-file when no runtime overrides are needed)
RUN_JSON="$(moi-cli -auth pat -o workflow run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --values-file values.json)"

export EXECUTION_ID="$(printf '%s' "$RUN_JSON" | jq -r '.workflow_run.execution_id // empty')"

# Inspect run status and final output
moi-cli -auth pat -o workflow get-run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"

moi-cli -auth pat -o workflow get-run-result \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"

Common run-time options and operational subcommands include:

Scenario

Command or flag

Description

Overwrite saved defaults

workflow run --replace-saved-defaults

Persist the supplied --values-file as the workflow’s new default runtime values.

Track batch file dispatch

workflow get-dispatch-job --workflow-id <id> --dispatch-job-id <id>

Batch file inputs return workflow_run.dispatch_job_id; dispatch completion indicates jobs are enqueued, after which workflow list-runs lists per-file execution_id entries.

Read runs and refresh state

list-runs, list-all-runs, get-run-by-id, refresh-run

List workflow-scoped or workspace-wide runs; use *-by-id subcommands when you only have execution_id.

Inspect import context and files

get-run-import-context[-by-id], list-run-import-files[-by-id], list-file-executions, get-run-node[-by-id]

Read import batch context, per-file execution records, and individual node execution details.

Pause, resume, and retry failures

pause, resume, pause-run, resume-run, retry-run, batch-retry-failed-files

Pause or resume workflow scheduling or an active run, retry a failed run, or retry failed files in bulk.

Rerun from a node branch

get-run-node-rerun-plan, create-run-node-rerun, list-run-rerun-branches, get-run-rerun, cancel-run-rerun

Read the rerun plan and contract hash before creating, inspecting, or canceling a node rerun branch.

Cancel or delete a run

cancel-run, delete-run

Check get-run first to confirm the run is still cancelable, and call get-run again afterward to verify the server-side terminal state.

Warning

workflow cancel-run stops remaining scheduling and unfinished node execution, and does not roll back data already written to databases, volume files, or external services. Enforce a bounded attempt limit and timeout when polling get-run in scripts; if polling times out, retain EXECUTION_ID and inspect the existing run before submitting another run.

Configure cron schedules and volume triggers

Update the trigger configuration of a saved workflow directly with workflow update without resubmitting an editor candidate:

# Schedule a daily run at 07:00 Asia/Shanghai
moi-cli -auth pat -o workflow update \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-mode cron \
  --cron-expression 'CRON_TZ=Asia/Shanghai 0 7 * * *'

# Read back execution_mode, cron_expression, and trigger_summary
moi-cli -auth pat -o workflow get \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID"

# Switch back to manual one-shot execution
moi-cli -auth pat -o workflow update \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-mode one_shot

Cron expressions accept five fields (minute hour day-of-month month day-of-week) or six fields with a leading seconds field (such as CRON_TZ=Asia/Shanghai 0 0 7 * * *); when CRON_TZ= is omitted, the server defaults to Asia/Shanghai. For volume-triggered execution, pass --execution-mode volume_trigger with --volume-trigger-file trigger.json and inspect the expected schema via moi-cli schema workflow deploy --argument volume-trigger-file.

Confirm and publish editor candidates

Workflow candidates generated in an editor authoring session are stored on the server. After reviewing the canvas, compilation output, and test report in the authoring task, record task_id, artifact_id, and proposal_id from that candidate and run accept-candidate followed by deploy-candidate:

export ACCEPT_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')"

# 1. Accept the candidate proposal and save the full acceptance receipt
moi-cli -auth pat -o workflow accept-candidate \
  --workspace-id "$WORKSPACE_ID" \
  --task-id "$TASK_ID" \
  --artifact-id "$ARTIFACT_ID" \
  --proposal-id "$PROPOSAL_ID" \
  --idempotency-key "$ACCEPT_KEY" \
  > acceptance.json

# 2. Publish the accepted candidate as a workflow application
moi-cli -auth pat -o workflow deploy-candidate \
  --workspace-id "$WORKSPACE_ID" \
  --name 'Document Processing' \
  --acceptance-file acceptance.json \
  --execution-mode one_shot

acceptance.json contains the server-issued candidate_ref, accepted_at, and candidate snapshot; if a request times out, retain the original ACCEPT_KEY to check task state and replay idempotently. deploy-candidate requires a prior accept-candidate receipt: if the proposal is bound to an existing workflow, omitting --workflow-id still updates that bound workflow, and an explicit --workflow-id must match the bound target.

Test and submit projects in authoring tasks

Inside the runtime environment of a live workflow authoring task (which injects the endpoint, workspace, and short-lived task credentials automatically), validate and submit a local project directory with test-candidate and submit-candidate:

export WORKFLOW_PROJECT_DIR="/path/to/current/project"

# Upload regular files under workflow/, operators/, and tests/ and run the full suite
moi-cli -o workflow test-candidate --project-dir "$WORKFLOW_PROJECT_DIR" > test-report.json

# Diagnose a single test case (filename under tests/cases/ without directory prefix)
moi-cli -o workflow test-candidate --project-dir "$WORKFLOW_PROJECT_DIR" --case main.json

# Re-evaluate assertions against the previous suite run when only checks changed
moi-cli -o workflow test-candidate --project-dir "$WORKFLOW_PROJECT_DIR" --verification-only

# Submit the candidate after the full suite passes without further file changes
moi-cli -o workflow submit-candidate --project-dir "$WORKFLOW_PROJECT_DIR" > candidate.json

Verify status and execution_coverage.suite in test-report.json before submitting (re-run the full test-candidate suite whenever workflow definitions, operators, or test inputs change), then check ok, diagnostics, and test_status in candidate.json. The client uploads regular files only, rejects symlinks, and treats --project-dir as mutually exclusive with --json and --json-file. Subsequent accept-candidate calls use the candidate artifact_id returned by the authoring task; candidate_id in candidate.json identifies the submission record only.

To inspect or release temporary scratch resources allocated to the authoring task:

moi-cli -o workflow observe-test-scratch --json '{}'
moi-cli -o workflow reset-test-scratch --task-id "$TASK_ID"

Warning

workflow observe-test-scratch has provisioning side effects: if scratch resources have not yet been initialized for the task, it creates the scratch database and input/output volumes before returning table and file samples (check truncated on returned samples). workflow reset-test-scratch applies only to tasks still in the working state, deleting tracked scratch databases, volumes, and knowledge base resources and returning state: released.

Inspect and restore authoring history

Candidate authoring history is tracked per conversation context (context_id). Paginate through historical candidates and restore a compiled candidate into a new pending proposal:

# Paginate candidate history for a workflow authoring context
moi-cli -auth pat -o workflow history \
  --workspace-id "$WORKSPACE_ID" \
  --context-id "$WORKFLOW_CONTEXT_ID" \
  --limit 20 --offset 0 > history.json

# Restore a selected compiled candidate as a new proposal
export RESTORE_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
moi-cli -auth pat -o workflow restore-history \
  --workspace-id "$WORKSPACE_ID" \
  --context-id "$WORKFLOW_CONTEXT_ID" \
  --request-id "$RESTORE_REQUEST_ID" \
  --task-id "$RESTORE_TASK_ID" \
  --artifact-id "$RESTORE_ARTIFACT_ID" > restored.json

Key fields when interpreting history.json and restored.json:

  • total_tasks counts authoring tasks (a single task can produce zero or multiple candidate items); advance pagination by offset + limit until reaching total_tasks.

  • current reflects the accepted candidate in the current conversation and saved_workflow reflects the saved workflow version; either field can be empty or updated from another conversation, so inspect both independently.

  • restore-history accepts compiled candidates only (failed source-code entries cannot be restored as compiled candidates), returns a new artifact_id and proposal_id under the source task_id, and resets test status without overwriting the saved workflow. Re-test the restored proposal before running accept-candidate and deploy-candidate.

Publish workflow API services and manage operators

To publish a MOWL workflow as a callable dynamic API service, prepare service.json (inspect field definitions via moi-cli schema workflow deploy --argument dynamic-service-file; input_schema and output_schema are JSON-encoded strings, and ui_resource can be omitted when no HTML interface is attached):

{
  "service_name": "document_service",
  "input_schema": "{\"type\":\"object\"}",
  "output_schema": "{\"type\":\"object\"}",
  "result_mode": "oneshot",
  "ui_resource": {
    "file_id": "<workspace-html-file-id>",
    "mime_type": "text/html"
  }
}

Deploy with --execution-mode dynamic_service (append --workflow-id "$WORKFLOW_ID" when updating an existing workflow):

moi-cli -auth pat -o workflow deploy \
  --workspace-id "$WORKSPACE_ID" \
  --name 'Document Service' \
  --workflow-file workflow.json \
  --execution-mode dynamic_service \
  --dynamic-service-file service.json

Warning

When updating a dynamic service that already has an HTML page attached, passing --dynamic-service-file without ui_resource clears the existing HTML page binding. Include the original ui_resource object in service.json whenever you want to preserve that page.

Beyond dynamic services, workflow also manages WorkItem API services, custom operators, workflow templates, and artifact lineage revisions (inspect JSON payloads via moi-cli schema workflow <subcommand>):

Area

Subcommands

Description

Dynamic and WorkItem API services

invoke-dynamic-service, invoke-workflow-dynamic-service, get-workitem-api-service, publish-workitem-api-service, invoke-workitem-api-service, enable-workitem-api-service, disable-workitem-api-service

Invoke published dynamic services, or publish individual WorkItems as API services and toggle availability.

Custom operators

custom-operators, create-custom-operator, get-custom-operator, get-custom-operator-code, get-custom-operator-source, test-custom-operator, update-custom-operator, enable-custom-operator, disable-custom-operator, delete-custom-operator

List, create, test, enable, disable, and delete workspace custom operators.

Workflow templates

workflow-templates, get-workflow-template, create-workflow-template, create-mowl-workflow-template, update-workflow-template, update-mowl-workflow-template, delete-workflow-template

Manage general workflow templates and native MOWL workflow templates.

Artifacts, lineage, and block revisions

catalog-file-lineage-overview, artifact-lineage-overview, artifact-output-blocks, artifact-node, artifact-node-output-blocks, artifact-block-revisions, create-artifact-block-revision, switch-artifact-effective-revisions, artifact-node-block-revisions, create-artifact-node-block-revision, switch-artifact-node-effective-revisions, create-artifact-node-rerun, create-target-artifact-node-revision-rerun

Inspect Catalog file and workflow artifact lineage, manage output block revisions, and trigger downstream node reruns from a target revision.

Limitations and notes

  • moi-cli workflow calls workspace Product APIs and is not used to invoke Genesis model inference endpoints directly.

  • Receiving execution_id or dispatch_job_id from workflow run indicates submission or dispatch queuing only; verify terminal node state and outputs with get-run and get-run-result.

  • To modify the graph topology of an accepted editor candidate, update and re-test in the authoring session before running accept-candidate and deploy-candidate; workflow update updates application-level metadata and schedules only.

  • See Non-Interactive Mode and Automation for jq extraction and bounded polling patterns in automation scripts.

Last updated on