Docs
Kiwi Flow
Version Current

API reference

Flow control activities

Approval, delay, loops, branching, merge, parallel execution and sub-workflows.

Flow Current 4 min read Updated

Approval, delay, loops, branching, merge, parallel execution and sub-workflows. This page covers 10 activity types.

approval#

Approval. Pause the run until a person (or a member of a role/group) approves or rejects it

This activity is configured through its config block (see the example below) rather than through named inputs.

Output Type Description
output.taskId string The created approval task's id

Config block example:

json
{
  "approval": {
    "assignType": "user",
    "assignedUserId": "alice",
    "title": "Approve refund",
    "message": "{{inputs.amount}} refund for {{inputs.customerId}}"
  }
}

delay#

Delay. Pause workflow execution for a fixed or dynamic duration

Input Type Required Description
seconds number No Seconds to wait (use seconds or milliseconds, not both)
milliseconds number No Milliseconds to wait (use seconds or milliseconds, not both)
Output Type Description
output.delayedMs number Actual delay in milliseconds

Config block example:

json
{
  "delay": {
    "milliseconds": 1000
  }
}

external_task#

External Task. Pause the run until external or manually-completed work reports back, with data

This activity is configured through its config block (see the example below) rather than through named inputs.

Output Type Description
output.taskId string The created external task's id
output.token string The raw bearer token an external system presents to complete/fail this task
output.callbackUrl string Absolute URL an external system POSTs to with { data } to complete this task
output.failUrl string Absolute URL an external system POSTs to with { error } to fail this task

Config block example:

json
{
  "external_task": {
    "title": "Waiting for ERP nightly batch"
  }
}

foreach#

For Each. Iterate over an array and execute a set of activities for each item sequentially

Input Type Required Description
items array Yes Path to the array to iterate over (e.g. a_receive_order.output.lineItems). Required — without it the engine has no collection to loop over.
Output Type Description
output.itemCount number Number of items iterated
output.results array Collected outputs from each iteration

Config block example:

json
{
  "foreach": {
    "items": "inputs.list",
    "itemVariable": "item",
    "body": []
  }
}

if_else#

If / Else. Evaluate a list of conditions top-to-bottom and route execution to the first matching branch

This activity is configured through its config block (see the example below) rather than through named inputs.

Config block example:

json
{
  "branches": [
    {
      "branchId": "b_yes",
      "label": "Yes",
      "condition": {
        "type": "expression",
        "body": "value > 0"
      },
      "next": "a_next"
    },
    {
      "branchId": "b_no",
      "label": "No",
      "condition": null,
      "next": "a_other"
    }
  ]
}

merge#

Merge. Consolidate outputs from multiple upstream activities into a single value using a merge strategy

Operations: combine, array, coalesce, sum, avg. Set with the operation input.

This activity is configured through its config block (see the example below) rather than through named inputs.

Output Type Description
output.merged object The merged result
output.count number Number of sources merged
output.sources array List of contributing activity ids

Config block example:

json
{
  "merge": {
    "strategy": "combine",
    "onConflict": "last_wins"
  }
}

parallel#

Parallel. Execute two or more activity branches concurrently and collect their outputs at the join point

This activity is configured through its config block (see the example below) rather than through named inputs.

Config block example:

json
{
  "parallel": {
    "branches": [
      {
        "id": "b_one",
        "name": "Branch One",
        "activities": []
      },
      {
        "id": "b_two",
        "name": "Branch Two",
        "activities": []
      }
    ]
  }
}

repeat_while#

Repeat While. Repeatedly execute a set of activities while a condition holds true

This activity is configured through its config block (see the example below) rather than through named inputs.

Output Type Description
output.iterationCount number Number of passes executed
output.results array Collected outputs from each pass

Config block example:

json
{
  "repeat_while": {
    "condition": "context.get('globals.status') !== 'done'",
    "maxIterations": 1000,
    "body": []
  }
}

sub_workflow#

Sub-Workflow. Execute a reusable child workflow and map its final global state as outputs

Input Type Required Description
workflowId string No Saved, reusable workflow to run as a nested child (resolved to its latest version). Takes priority over workflowFile if both are set.
workflowFile string No Relative path to the workflow JSON file (legacy file-based resolution, used when workflowId is not set)
Output Type Description
output.* object All final global variables of the child workflow exposed as named outputs

Config block example:

json
{
  "sub_workflow": {
    "workflowId": "wf_abc12345"
  }
}

switch#

Switch. Resolve a variable bag path and route execution to the case whose value matches it

This activity is configured through its config block (see the example below) rather than through named inputs.

Config block example:

json
{
  "switch": {
    "on": "a_prev.output.status",
    "cases": [
      {
        "value": "ok",
        "next": "a_ok"
      },
      {
        "value": "fail",
        "next": "a_fail"
      }
    ],
    "default": "a_fallback"
  }
}