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 |
|
Persist the supplied |
Track batch file dispatch |
|
Batch file inputs return |
Read runs and refresh state |
|
List workflow-scoped or workspace-wide runs; use |
Inspect import context and files |
|
Read import batch context, per-file execution records, and individual node execution details. |
Pause, resume, and retry failures |
|
Pause or resume workflow scheduling or an active run, retry a failed run, or retry failed files in bulk. |
Rerun from a node branch |
|
Read the rerun plan and contract hash before creating, inspecting, or canceling a node rerun branch. |
Cancel or delete a run |
|
Check |
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.
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 published dynamic services, or publish individual WorkItems as API services and toggle availability. |
Custom operators |
|
List, create, test, enable, disable, and delete workspace custom operators. |
Workflow templates |
|
Manage general workflow templates and native MOWL workflow templates. |
Artifacts, lineage, and block revisions |
|
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 workflowcalls workspace Product APIs and is not used to invoke Genesis model inference endpoints directly.Receiving
execution_idordispatch_job_idfromworkflow runindicates submission or dispatch queuing only; verify terminal node state and outputs withget-runandget-run-result.To modify the graph topology of an accepted editor candidate, update and re-test in the authoring session before running
accept-candidateanddeploy-candidate;workflow updateupdates application-level metadata and schedules only.See Non-Interactive Mode and Automation for
jqextraction and bounded polling patterns in automation scripts.