Skip to main content

Child Workflows

A Child Workflow Execution is a Workflow Execution that is spawned from within another Workflow in the same Namespace.

A Workflow Execution can be both a Parent and a Child Workflow Execution because any Workflow can spawn another Workflow.

Parent and Child Workflow Execution entity relationship

Parent and Child Workflow Execution entity relationship

A Parent Workflow Execution must await on the Child Workflow Execution to spawn. The Parent can optionally await on the result of the Child Workflow Execution. Consider the Child's Parent Close Policy if the Parent does not await on the result of the Child, which includes any use of Continue-As-New by the Parent.

note

Child Workflows do not carry over when the Parent uses Continue-As-New. This means that if a Parent Workflow Execution utilizes Continue-As-New, any ongoing Child Workflow Executions will not be retained in the new continued instance of the Parent.

When a Parent Workflow Execution reaches a Closed status, the Cluster propagates Cancellation Requests or Terminations to Child Workflow Executions depending on the Child's Parent Close Policy.

If a Child Workflow Execution uses Continue-As-New, from the Parent Workflow Execution's perspective the entire chain of Runs is treated as a single execution.

Parent and Child Workflow Execution entity relationship with Continue As New

Parent and Child Workflow Execution entity relationship with Continue As New

When to use Child Workflows​

There is no reason to use Child Workflows just for code organization. You can use object oriented structure and other code organization techniques to deal with complexities. It is typically recommended to start from a single Workflow Definition if your problem has bounded size in terms of the number of Activity Executions and processed Signals. It is simpler than multiple asynchronously communicating Workflows.

However, there are several valid reasons for using Child Workflows.

Create a separate service​

Because a Child Workflow Execution can be processed by a completely separate set of Workers than the Parent Workflow Execution, it can act as an entirely separate service. However, this also means that a Parent Workflow Execution and a Child Workflow Execution do not share any local state. As all Workflow Executions, they can communicate only via asynchronous Signals.

Paritition problems into smaller chunks​

An individual Workflow Execution has an Event History size limit, which imposes a couple of considerations for using Child Workflows.

On one hand, because Child Workflow Executions have their own Event Histories, they are often used to partition large workloads into smaller chunks. For example, a single Workflow Execution does not have enough space in its Event History to spawn 100,000 Activity Executions. But a Parent Workflow Execution can spawn 1,000 Child Workflow Executions that each spawn 1,000 Activity Executions to achieve a total of 1,000,000 Activity Executions.

However, because a Parent Workflow Execution Event History contains Events that correspond to the status of the Child Workflow Execution, a single Parent should not spawn more than 1,000 Child Workflow Executions.

In general, however, Child Workflow Executions result in more overall Events recorded in Event Histories than Activities. Because each entry in an Event History is a cost in terms of compute resources, this could become a factor in very large workloads. Therefore, we recommend starting with a single Workflow implementation that uses Activities until there is a clear need for Child Workflows.

Represent a single resource​

As all Workflow Executions, a Child Workflow Execution can create a one to one mapping with a resource. It can be used to manage the resource using its ID to guarantee uniqueness. For example, a Workflow that manages host upgrades could spawn a Child Workflow Execution per host (hostname being a Workflow ID) and use them to ensure that all operations on the host are serialized.

Periodic logic execution​

A Child Workflow can be used to execute some periodic logic without overwhelming the Parent Workflow Event History. In this scenario, the Parent Workflow starts a Child Workflow which executes periodic logic calling Continue-As-New as many times as needed, then completes. From the Parent point of view, it is just a single Child Workflow invocation.

Child Workflow versus an Activity​

Child Workflow Executions and Activity Executions are both started from Workflows, so you might feel confused about when to use which. Here are some important differences:

  • A Child Workflow has access to all Workflow APIs but is subject to the same deterministic constraints as other Workflows. An Activity has the inverse pros and cons—no access to Workflow APIs but no Workflow constraints.
  • A Child Workflow Execution can continue on if its Parent is canceled with a Parent Close Policy of ABANDON. An Activity Execution is always canceled when its Workflow Execution is canceled. (It can react to a cancellation Signal for cleanup.) The decision is roughly analogous to spawning a child process in a terminal to do work versus doing work in the same process.
  • Temporal tracks all state changes within a Child Workflow Execution in Event History. Only the input, output, and retry attempts of an Activity Execution is tracked.

A Workflow models composite operations that consist of multiple Activities or other Child Workflows. An Activity usually models a single operation on the external world.

Our advice: When in doubt, use an Activity.

Parent Close Policy​

What is a Parent Close Policy?

A Parent Close Policy determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed out).

There are three possible values:

  • Abandon: the Child Workflow Execution is not affected.
  • Request Cancel: a Cancellation request is sent to the Child Workflow Execution.
  • Terminate (default): the Child Workflow Execution is forcefully Terminated.

ParentClosePolicy proto definition.

Each Child Workflow Execution may have its own Parent Close Policy. This policy applies only to Child Workflow Executions and has no effect otherwise.

Parent Close Policy entity relationship

Parent Close Policy entity relationship

You can set policies per child, which means you can opt out of propagating terminates / cancels on a per-child basis. This is useful for starting Child Workflows asynchronously (see relevant issue here or the corresponding SDK docs).