Invoke Playbook

Invoke Playbook

Type: invoke-playbook  ·  Package: Core Activities v1.0.8

Runs another playbook from the same project, optionally passing it input data and receiving its results back. It is the tool to split a large automation into small pieces and reuse logic: instead of copying and pasting the same group of activities in several places, you put it in a sub-playbook and invoke it.

How it works

1. Looks for the playbook set in path inside the project (the path is resolved against the project’s root folder, where project.zoanproj lives).
2. Runs it from start to finish, passing it the values of input, with its own variable space: it does not see or modify the caller’s variables.
3. When it finishes, its outputs are mapped to variables of the current playbook according to outputs, and Playbook '…' completed. is logged.
4. If the sub-playbook fails, the invocation fails with the same error and the same type (catchable with Try / Catch): a business error in the child is still a business error in the parent.

Limits that protect the execution:

• A playbook cannot invoke itself, directly or indirectly (A → B → A): it is detected as recursion and fails.
• The invocation chain allows up to 32 levels of depth.

Required parameters

Parameter	Type	Default	Description
path	string	—	The child playbook to run. Path relative to the project root (e.g. "playbooks/process-invoice.json"); in the Designer you pick it from the project’s list of playbooks.

Optional parameters

Parameter	Type	Default	Description
input	Dictionary	—	Values the sub-playbook receives, as name: value pairs. The names are the child’s input arguments (In or In/Out); in the Designer the editor lists them when you pick the playbook.
outputs	Dictionary	—	{ childOutput: parentVariable } mapping. Only the child’s output arguments (Out or In/Out) cross over; names that are not valid variables or that the child doesn’t return are ignored.

Output

This activity does not return a value of its own: what the child produces reaches the parent variables set in outputs. If a declared output of the child was left without a value, it arrives as null and the child logs a warning.

Example

For each invoice, invoke a sub-playbook that processes it and returns a status:

For Each   items = invoices   itemVariable = invoice
 └─ activities:
      Invoke Playbook
        path    = "process-invoice.json"
        input   = { invoice: invoice, retries: 3 }
        outputs = { status: processingStatus }
      Log   level = info   message = "Invoice processed: " + processingStatus

• input: the child receives invoice and retries as input variables.
• outputs: the child’s status output is stored in the parent’s processingStatus variable.

Each playbook has its own variables

The sub-playbook does not share variables with its caller. Communication happens only through input (to the child) and outputs (back to the parent). This keeps each piece isolated and reusable. See Variable scope.

The parent variable that receives an output (processingStatus in the example) must be declared in the parent to receive the value. If it is not, the output is not assigned and a warning in the log says so. Any valid variable name works, including one-letter names (x, n).

Only relative paths inside the project

path must be a path relative to the project; absolute paths and .. segments are not allowed. This prevents a playbook from running files outside its project.

How the sub-playbook exposes outputs

In the sub-playbook, declare the output in the Arguments panel with direction Out (or In/Out) and give it a value with Set Variable. See Variable scope.

Common errors

Message	Cause and fix
Playbook not found: '…' (looked under '…').	That file does not exist under the project root. Check the path (case, extension, folder) or pick it from the Designer’s list.
Path not allowed: '…'. Paths must be relative and cannot contain '..'.	path is absolute or leaves the project with ... Use a path relative to the project root.
Playbook '…': required input '…' was not provided by the parent.	The child has a required input argument with no default value and input does not include it (or sends it empty). Add it to input.
Recursion detected: '…' is already running in the current chain.	The playbook is already running higher up in the chain (A → B → A). Reorganize the logic so it is not invoked again.
Maximum invocation depth reached (32 levels). Check that there is no playbook cycle.	Too many playbooks invoking each other in a chain. Flatten the structure.
Output '…' was not assigned to '…': …	Warning: the parent variable is not declared or its type is not compatible with the output. Declare it with the right type.
The child’s error message	The sub-playbook failed: the activity fails with the same message (or The child playbook failed. if it has none). Handle it with a Try / Catch around the invocation.

Related activities

• Invoke Process — run a published process, even from another project.
• Variables — how inputs are passed and outputs received.
• Try / Catch — handle a sub-playbook failure.
• Designer overview — projects with several playbooks.