Spark ERP Docs

Appearance

Start a workflow - record changes, schedules, API and webhooks ​

What it is for ​

A workflow must start from something: a person pressing Submit, a record being created, a clock, or another system calling. This page lists every way, with the exact settings.

Triggers are listed in the definition's metadataJson, under triggers. Only the latest published version starts new runs.

1. A record changes ​

json
"metadataJson": "{\"triggers\": [
  {\"type\": \"record\", \"event\": \"created\", \"entity\": \"leave_request\"},
  {\"type\": \"record\", \"event\": \"changed\", \"entity\": \"employee\", \"field\": \"status\", \"from\": \"PROBATION\", \"to\": \"ACTIVE\"},
  {\"type\": \"record\", \"event\": \"updated\", \"entity\": \"loan\", \"filter\": {\"field\": \"previous.amount\", \"op\": \"lt\", \"value\": 1000}}]}"
  • event: created, updated (a real field changed; saves that touch only audit columns do not count), deleted, or changed (one field, optionally from and to).
  • filter uses the same condition grammar as transitions, plus previous.<field> for the value before an update.
  • The run starts with the record's fields at the top level of its data, the whole record under record, recordId, and a _trigger block.
  • Loop guard: changes the workflow engine makes itself (its own create, update and delete nodes) never start workflows, unless a trigger sets "includeWorkflowChanges": true.
  • The system starts the run, so there is no "may this user submit" check. Everything the workflow then does is checked normally.
  • Trigger lists are cached for 60 seconds and refreshed when a definition changes.

2. A schedule ​

json
"metadataJson": "{\"triggers\": [{\"type\": \"schedule\", \"cron\": \"0 9 * * 1\", \"timezone\": \"Asia/Kolkata\", \"context\": {\"report\": \"weekly\"}, \"catchUp\": true}]}"
  • cron has five fields (minute, hour, day of month, month, day of week). Ranges, lists, */n steps and month and weekday names work. A six-field form with seconds is accepted.
  • timezone is an IANA zone, UTC when empty. context is what each run starts with, next to a _trigger block.
  • Each fire has a fixed correlation id, so the same fire is never started twice, even with several servers.
  • Fires are found every 30 seconds and cover the last 5 minutes. After a longer outage, "catchUp": true replays everything missed in the last 24 hours, or set "catchUpMinutes": n (up to 10080). At most 50 missed runs per schedule are started per pass, oldest first.
  • "enabled": false switches one trigger off.

3. Start by API ​

http
POST /api/v1/workflows/{name}/start
{"context": {"customerId": 42}, "correlationId": "order-1042"}
  • Needs the submit right on workflow:<name>, the same as pressing Submit.
  • Sending a correlationId that already has a run returns that run (HTTP 200) instead of a second one (201), so retries are safe.
  • The run's data gets _trigger: {type: "api", actor}.

4. A webhook from another system ​

Opt in with {"type": "webhook"} in triggers. An outside system then posts:

http
POST /api/v1/workflow-hooks/{tenantId}/{workflow}
Authorization: Bearer <token>
Idempotency-Key: order-1042
{"customerId": 42, "total": 1200}
  • The body must be a JSON object up to 256 KB. Its fields become the run's data (names starting _ are dropped), plus _trigger: {type: "webhook"}.
  • A resend with the same Idempotency-Key returns the existing run.
  • Manage the token at GET|POST|DELETE /api/v1/workflows/{name}/webhook (needs manage on the workflow). POST creates or rotates the token and shows it once. Only a hash is stored, and the workflow must be published.
  • Every refusal (no token, wrong token, unknown workflow, trigger not enabled) answers the same bare 401. There is a limit of 60 calls a minute per workflow.

5. From a rule, an action or a page ​

  • A rule with start a workflow in its Then part starts one when a record is saved.
  • A page action can call the workflow bridge to start or decide, so a button can submit a request.
  • A bot or journey step can start workflows too.

6. From inside another workflow ​

A subworkflow task or a For each node starts a child workflow. See How workflows work.

Choosing ​

You wantUse
Every new leave request to go to approvalRecord trigger, created
A status change to start onboardingRecord trigger, changed with from and to
A weekly report, a nightly clean-upSchedule
A button, or your own code, to start itAPI
Another company's system to start itWebhook

Where next ​