Docs
Kiwi Flow
Version Current

API reference

Kiwi Distro activities

Invoke methods and run registered scripts on Kiwi Distro workers.

Flow Current 5 min read Updated

Invoke methods and run registered scripts on Kiwi Distro workers. This page covers 3 activity types.

kiwi_distro_connection#

Kiwi Distro Connection. Opens a connection to a Kiwi Distro middleware instance for later Kiwi Distro Invoke activities to reuse.

Input Type Required Description
middlewareUrl string Yes Kiwi Distro middleware base URL, e.g. https://distro.example.com
clientId string Yes Kiwi Distro OAuth2 client id
clientSecret string Yes Kiwi Distro OAuth2 client secret Secret: stored encrypted.
middlewareCaUrl string No Plain-HTTP URL of the middleware's CA endpoint (e.g. http://mw:6080/ca/cert) — pins the middleware's TLS certificate against that CA. Leave unset to use system trust.
ignoreSsl boolean No Development only: skip middleware TLS validation
Output Type Description
output.connection object The live client — pick this node in a Kiwi Distro Invoke activity's "Connection" field to reuse it

Config block example:

json
{}

kiwi_distro_invoke#

Kiwi Distro Invoke. Call a method on a Kiwi Distro service via the middleware.

Input Type Required Description
connection string No Reuse a Kiwi Distro Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a kiwi_distro_connection node.
middlewareUrl string No Kiwi Distro middleware base URL, e.g. https://distro.example.com (only used when no Connection node is selected above)
clientId string No Kiwi Distro OAuth2 client id (only used when no Connection node is selected above)
clientSecret string No Kiwi Distro OAuth2 client secret (only used when no Connection node is selected above) Secret: stored encrypted.
middlewareCaUrl string No Plain-HTTP URL of the middleware's CA endpoint (only used when no Connection node is selected above)
ignoreSsl boolean No Development only: skip middleware TLS validation (only used when no Connection node is selected above)
service string Yes Kiwi Distro service name to call
method string Yes Method name on the service to call, e.g. "getOrderStatus"
parameters object No Named arguments passed to the method, e.g. {"orderId": 42}
target string No any (default, leave unset — the middleware picks an available worker) | all (fan out to every worker registered for this service, one result per worker) | a specific worker id
filters array No Route the call only to workers whose tags match every criterion (e.g. a worker tagged os=Win-11) — narrows which worker "any"/"all" considers, or validates a specific target still matches.
ttlSeconds number No Optional time-to-live for the request, in seconds
version string No Optional service version to target
Output Type Description
output.status string success | failed | pending (target "any" or a specific worker), or success | partial | failed (target "all")
output.result object The method's return value (target "any" or a specific worker only)
output.error string Failure reason, if any
output.results array One entry per worker — {workerId, status, result, error} (target "all" only)

Config block example:

json
{
  "inputs": [
    {
      "name": "service",
      "value": "orders"
    },
    {
      "name": "method",
      "value": "getOrderStatus"
    },
    {
      "name": "parameters",
      "value": {
        "orderId": 42
      }
    }
  ]
}

kiwi_distro_script#

Kiwi Distro Script. Run a registered Kiwi Distro script on a service and wait for it to finish.

Input Type Required Description
connection string No Reuse a Kiwi Distro Connection node already on the canvas. Leave unset to configure a standalone connection below instead. Can reuse a kiwi_distro_connection node.
middlewareUrl string No Kiwi Distro middleware base URL, e.g. https://distro.example.com (only used when no Connection node is selected above)
clientId string No Kiwi Distro OAuth2 client id (only used when no Connection node is selected above)
clientSecret string No Kiwi Distro OAuth2 client secret (only used when no Connection node is selected above) Secret: stored encrypted.
middlewareCaUrl string No Plain-HTTP URL of the middleware's CA endpoint (only used when no Connection node is selected above)
ignoreSsl boolean No Development only: skip middleware TLS validation (only used when no Connection node is selected above)
service string Yes Kiwi Distro service the script is registered under
script string Yes Registered script name to run
parameters object No Named parameter values passed to the script, e.g. {"month": 8}
env object No Extra environment variables for the script process, e.g. {"API_KEY": "..."}
version string No Specific authorized script version to run. Leave unset for the latest authorized version.
ttlSeconds number No Optional time-to-live for the submitted request, in seconds
pollTimeoutSeconds number No How long to wait for the script to finish before giving up, in seconds (default 900 = 15 minutes)
Output Type Description
output.status string success | failed | timeout — the script's own outcome (distinct from a thrown error, which means the platform itself couldn't run or track it)
output.exitCode number The script process's exit code
output.result object The script's structured return value (from KIWI_OUTPUT_FILE or a KIWI_RESULT_MARKER block), if any
output.resultSource string Where output.result came from: file | marker | none
output.durationMs number Script execution time in milliseconds
output.truncated boolean Whether stdout/stderr were truncated by the worker's output cap
output.stdout string Captured standard output
output.stderr string Captured standard error
output.error string Failure reason, if any
output.requestId string The submitted request id, for correlating with the Kiwi Distro Feedback screen

Config block example:

json
{
  "inputs": [
    {
      "name": "service",
      "value": "orders"
    },
    {
      "name": "script",
      "value": "monthly-report"
    },
    {
      "name": "parameters",
      "value": {
        "month": 8
      }
    }
  ]
}