Workflows

Named workflows

Workflows let GraphJin expose reviewed operational procedures instead of letting agents improvise multi-step actions.

sources:
  - name: workflows
    kind: workflow
    path: ./workflows
    runtime: javascript
    capabilities:
      workflow.execute: true
      workflow.read: false
      workflow.write: false

graphjin workflow run nightly-report --vars report-vars.json

Workflows can call GraphJin tools and GraphQL when allowed by configuration. They respect declared variables, timeouts, context cancellation, and workflow execution policy.

Files under workflows/ are global workflow definitions. When artifacts.enabled is configured and a request has user_id, gj_artifacts provides a caller-scoped workflow overlay. Execution resolves a user workflow artifact first, then falls back to the global file.

GraphQL control-plane shape

mutation RunWorkflow($vars: JSON!) {
  gj_workflow_execution(insert: {
    workflow_name: "nightly-report"
    variables: $vars
  }) {
    id
    workflow_name
    status
    result_json
    error
  }
}

Workflow rows also appear in gj_catalog, so a model can inspect names, variable contracts, lifecycle metadata, and safety notes before execution.

gj_workflow and save_workflow use the same write policy as saved queries: user artifact when user_id and the artifact store are present, global workflows/*.js only in dev fallback mode.

Safety

Use workflows for bounded operations that need a name, review trail, inputs, and clear failure behavior.

Workflows should declare variables and timeouts. The runtime respects context cancellation and blocks workflow-management tools unless the caller/config explicitly allows them.