Skip to main content

Workflow Container job

In briefA Workflow Container job runs another workflow as one step of the current one. The nested workflow is built during its parent's build, waits in Wait Container Job until the container job runs, and the container stays running until the nested run finishes, then settles to match. A container whose sub-workflow can't be built does not fail the parent's build: the reason is kept on the job and in its Status History.

WhereIn the Design module, add a Workflow Container job to a workflow and choose the workflow to embed in its Sub-Workflow picker. The picker offers only workflows marked Sub-Workflow — a switch at the head of the Multi-Instance section on the Overview tab of the workflow's Workflow Settings panel. At run time the nested run appears in Processes, named for its place in the hierarchy; a container that came up empty carries a warning icon on the workflow diagram and in the Job View list, and its reason is on the job's Status History tab.

WhenUse a container when:

  • one workflow should run another as a single step, and wait for it to finish;
  • the same sequence of jobs is shared by several parent workflows;
  • you need to find out why a container failed, has nothing to run, or is still running.

To run one workflow after another without embedding it, use a cross-workflow job dependency instead.

How

  1. Mark the workflow to embed as Sub-Workflow on the Overview tab of its Workflow Settings panel, and deploy it to every environment and date range its parent runs in.
  2. In the parent, add a Workflow Container job and pick the sub-workflow.
  3. Commit and deploy the parent, then build it: the nested run is built with it.
  4. If a container has nothing to run, read the reason on the warning banner, the job's warning icon or its Status History, fix it, and rebuild with overwrite.

The full steps are on Embed another workflow with a Workflow Container.

Notes
  • Turning Sub-Workflow off is refused while a container job in another workflow embeds the workflow, and nothing is saved.
  • The reference is resolved against the workflows deployed for the parent's schedule date, by id first and otherwise by name ignoring case.
  • Nesting is limited to 10 levels, and one build creates at most 250 nested runs within 25 seconds.
  • A running container does not take one of the environment's job slots.
  • When a container ends while its nested run still has jobs running, those jobs finish first; then the nested run is cancelled.
  • A job instance cannot change its container's Sub-Workflow: change it on the job definition and rebuild.
Watch out
  • A sub-workflow must be deployed wherever, and for whenever, its parent is — otherwise the container has nothing to run and fails when it starts.
  • A job-level event naming a workflow that exists only as a nested run can act on that nested run.
  • Deleting or overwriting a parent removes its whole container subtree, and is refused while any nested run in it still has jobs running.