diff --git a/docs/cli/workflow.mdx b/docs/cli/workflow.mdx index d7f7cd8d99..577558ad34 100644 --- a/docs/cli/workflow.mdx +++ b/docs/cli/workflow.mdx @@ -821,7 +821,7 @@ Use the following options to change termination behavior. ## trace -The `temporal workflow trace` command tracks the progress of a [Workflow Execution](/workflows#workflow-execution) and any [Child Workflows](/encyclopedia/child-workflows) it generates. +The `temporal workflow trace` command tracks the progress of a [Workflow Execution](/workflows#workflow-execution) and any [Child Workflows](/child-workflows) it generates. Use the following options to change the command's behavior. diff --git a/docs/develop/dotnet/child-workflows.mdx b/docs/develop/dotnet/child-workflows.mdx index 0372db060e..feb6469f91 100644 --- a/docs/develop/dotnet/child-workflows.mdx +++ b/docs/develop/dotnet/child-workflows.mdx @@ -38,12 +38,12 @@ This page shows how to do the following: **How to start a Child Workflow Execution using the Temporal .NET SDK** -A [Child Workflow Execution](/encyclopedia/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. +A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. Always block progress until the [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event is logged to the Event History to ensure the Child Workflow Execution has started. -After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) set in the Child Workflow Options. +After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/parent-close-policy) set in the Child Workflow Options. To spawn a Child Workflow Execution in .NET, use the `ExecuteChildWorkflowAsync()` method which starts the Child Workflow and waits for completion or use the `StartChildWorkflowAsync()` method to start a Child Workflow and return its handle. @@ -63,7 +63,7 @@ await Workflow.ExecuteChildWorkflowAsync((MyChildWorkflow wf) => wf.RunAsync()); **How to set a Parent Close Policy using the Temporal .NET SDK** -A [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). +A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). The default Parent Close Policy option is set to terminate the Child Workflow Execution. diff --git a/docs/develop/go/child-workflows.mdx b/docs/develop/go/child-workflows.mdx index ce4c824118..f6c4952d26 100644 --- a/docs/develop/go/child-workflows.mdx +++ b/docs/develop/go/child-workflows.mdx @@ -22,18 +22,18 @@ This page shows how to do the following: **How to start a Child Workflow Execution using the Go SDK.** -A [Child Workflow Execution](/encyclopedia/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. +A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. Always block progress until the [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event is logged to the Event History to ensure the Child Workflow Execution has started. -After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) set in the Child Workflow Options. +After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/parent-close-policy) set in the Child Workflow Options. To be sure that the Child Workflow Execution has started, first call the Child Workflow Execution method on the instance of Child Workflow future, which returns a different future. Then get the value of an object that acts as a proxy for a result that is initially unknown, which is what waits until the Child Workflow Execution has spawned. -To spawn a [Child Workflow Execution](/encyclopedia/child-workflows) in Go, use the [`ExecuteChildWorkflow`](https://pkg.go.dev/go.temporal.io/sdk/workflow#ExecuteChildWorkflow) API, which is available from the `go.temporal.io/sdk/workflow` package. +To spawn a [Child Workflow Execution](/child-workflows) in Go, use the [`ExecuteChildWorkflow`](https://pkg.go.dev/go.temporal.io/sdk/workflow#ExecuteChildWorkflow) API, which is available from the `go.temporal.io/sdk/workflow` package. The `ExecuteChildWorkflow` call requires an instance of [`workflow.Context`](https://pkg.go.dev/go.temporal.io/sdk/workflow#Context), with an instance of [`workflow.ChildWorkflowOptions`](https://pkg.go.dev/go.temporal.io/sdk/workflow#ChildWorkflowOptions) applied to it, the Workflow Type, and any parameters that should be passed to the Child Workflow Execution. @@ -110,7 +110,7 @@ func YourOtherWorkflowDefinition(ctx workflow.Context, params ChildParams) (Chil **How to set a Parent Close Policy for a Child Workflow Execution using the Go SDK.** -A [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). +A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). The default Parent Close Policy option is set to terminate the Child Workflow Execution. diff --git a/docs/develop/go/observability.mdx b/docs/develop/go/observability.mdx index 7528b32295..37dc4723a3 100644 --- a/docs/develop/go/observability.mdx +++ b/docs/develop/go/observability.mdx @@ -161,7 +161,7 @@ Yes. Multiple context propagators help to structure code with each propagator ha - [Passing Context with Temporal](https://spiralscout.com/blog/passing-context-with-temporal) by SpiralScout The [Go SDK](https://github.com/temporalio/sdk-go) provides support for distributed tracing with **_Interceptors_**. -Interceptors uses Temporal headers to create a call graph of a [Workflow](/workflows), along with its [Activities](/activities) and [Child Workflows](/encyclopedia/child-workflows). +Interceptors uses Temporal headers to create a call graph of a [Workflow](/workflows), along with its [Activities](/activities) and [Child Workflows](/child-workflows). There are several tracing implementations supported by the Temporal Go SDK. For an [OpenTracing](https://pkg.go.dev/go.temporal.io/sdk/contrib/opentracing) Interceptor, use `opentracing.NewInterceptor(opentracing.TracerOptions{})` to create a `TracingInterceptor`. diff --git a/docs/develop/java/child-workflows.mdx b/docs/develop/java/child-workflows.mdx index c517cd4aef..a2eebdb94e 100644 --- a/docs/develop/java/child-workflows.mdx +++ b/docs/develop/java/child-workflows.mdx @@ -22,12 +22,12 @@ This page shows how to do the following: **How to start a Child Workflow Execution using the Java SDK.** -A [Child Workflow Execution](/encyclopedia/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. +A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. Always block progress until the [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event is logged to the Event History to ensure the Child Workflow Execution has started. -After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) set in the Child Workflow Options. +After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/parent-close-policy) set in the Child Workflow Options. To be sure that the Child Workflow Execution has started, first call the Child Workflow Execution method on the instance of Child Workflow future, which returns a different future. @@ -150,11 +150,11 @@ Related reads: **How to set a Parent Close Policy for a Child Workflow using the Java SDK.** -A [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). +A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). The default Parent Close Policy option is set to terminate the Child Workflow Execution. -Set [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) on an instance of `ChildWorkflowOptions` using [`ChildWorkflowOptions.newBuilder().setParentClosePolicy`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/ChildWorkflowOptions.Builder.html). +Set [Parent Close Policy](/parent-close-policy) on an instance of `ChildWorkflowOptions` using [`ChildWorkflowOptions.newBuilder().setParentClosePolicy`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/workflow/ChildWorkflowOptions.Builder.html). - Type: `ChildWorkflowOptions.Builder` - Default: `PARENT_CLOSE_POLICY_TERMINATE` diff --git a/docs/develop/php/child-workflows.mdx b/docs/develop/php/child-workflows.mdx index 4cb8e5b83d..7f76c79f94 100644 --- a/docs/develop/php/child-workflows.mdx +++ b/docs/develop/php/child-workflows.mdx @@ -16,12 +16,12 @@ description: Learn how to start a Child Workflow Execution within a parent Workf ## How to start a Child Workflow Execution {#child-workflows} -A [Child Workflow Execution](/encyclopedia/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. +A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. Always block progress until the [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event is logged to the Event History to ensure the Child Workflow Execution has started. -After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) set in the Child Workflow Options. +After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/parent-close-policy) set in the Child Workflow Options. To be sure that the Child Workflow Execution has started, first call the Child Workflow Execution method on the instance of Child Workflow future, which returns a different future. @@ -83,11 +83,11 @@ $childResult = yield Workflow::executeChildWorkflow( #### How to set a Parent Close Policy {#parent-close-policy} -A [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). +A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). The default Parent Close Policy option is set to terminate the Child Workflow Execution. -In PHP, a [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) is set via the `ChildWorkflowOptions` object and `withParentClosePolicy()` method. +In PHP, a [Parent Close Policy](/parent-close-policy) is set via the `ChildWorkflowOptions` object and `withParentClosePolicy()` method. The possible values can be obtained from the [`ParentClosePolicy`](https://github.com/temporalio/sdk-php/blob/master/src/Workflow/ParentClosePolicy.php) class. - `POLICY_TERMINATE` diff --git a/docs/develop/python/child-workflows.mdx b/docs/develop/python/child-workflows.mdx index b77d784994..259e8bbb9a 100644 --- a/docs/develop/python/child-workflows.mdx +++ b/docs/develop/python/child-workflows.mdx @@ -28,12 +28,12 @@ This page shows how to do the following: **How to start a Child Workflow Execution using the Temporal Python SDK.** -A [Child Workflow Execution](/encyclopedia/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. +A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. Always block progress until the [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event is logged to the Event History to ensure the Child Workflow Execution has started. -After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) set in the Child Workflow Options. +After that, Child Workflow Executions may be abandoned using the _Abandon_ [Parent Close Policy](/parent-close-policy) set in the Child Workflow Options. To be sure that the Child Workflow Execution has started, first call the Child Workflow Execution method on the instance of Child Workflow future, which returns a different future. @@ -81,7 +81,7 @@ class GreetingWorkflow: **How to set a Parent Close Policy** -A [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). +A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). The default Parent Close Policy option is set to terminate the Child Workflow Execution. diff --git a/docs/develop/typescript/child-workflows.mdx b/docs/develop/typescript/child-workflows.mdx index 1cfa6ad198..59d5a6b54a 100644 --- a/docs/develop/typescript/child-workflows.mdx +++ b/docs/develop/typescript/child-workflows.mdx @@ -16,12 +16,12 @@ description: Learn how to start and manage Child Workflow Executions using Tempo ## How to start a Child Workflow Execution {#child-workflows} -A [Child Workflow Execution](/encyclopedia/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. +A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. When using a Child Workflow API, Child Workflow–related Events (such as [StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), and [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Event History of the Child Workflow Execution. Always block progress until the [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event is logged to the Event History to ensure the Child Workflow Execution has started. -After that, Child Workflow Executions can be abandoned by using the `Abandon` [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) set in the Child Workflow Options. +After that, Child Workflow Executions can be abandoned by using the `Abandon` [Parent Close Policy](/parent-close-policy) set in the Child Workflow Options. To be sure that the Child Workflow Execution has started, first call the Child Workflow Execution method on the instance of Child Workflow future, which returns a different future. @@ -99,7 +99,7 @@ A Child Workflow Execution is automatically cancelled when its containing scope ### How to set a Parent Close Policy {#parent-close-policy} -A [Parent Close Policy](/encyclopedia/child-workflows#parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). +A [Parent Close Policy](/parent-close-policy) determines what happens to a Child Workflow Execution if its Parent changes to a Closed status (Completed, Failed, or Timed Out). The default Parent Close Policy option is set to terminate the Child Workflow Execution. diff --git a/docs/encyclopedia/child-workflows.mdx b/docs/encyclopedia/child-workflows/child-workflows.mdx similarity index 76% rename from docs/encyclopedia/child-workflows.mdx rename to docs/encyclopedia/child-workflows/child-workflows.mdx index 0dff993094..1f732977c4 100644 --- a/docs/encyclopedia/child-workflows.mdx +++ b/docs/encyclopedia/child-workflows/child-workflows.mdx @@ -2,7 +2,8 @@ id: child-workflows title: Child Workflows sidebar_label: Child Workflows -description: A Child Workflow Execution in the Temporal platform is initiated from another Workflow within the same Namespace. Learn about the feature guides for Go, Java, PHP, Python, TypeScript, and .NET SDKs. Understand the Parent-Child Workflow relationship, including when to use Child Workflows, Parent Close Policies +description: A Child Workflow Execution in the Temporal platform is initiated from another Workflow within the same Namespace. Learn about the feature guides for Go, Java, PHP, Python, TypeScript, and .NET SDKs. +slug: /child-workflows toc_max_heading_level: 4 keywords: - child workflow execution @@ -51,7 +52,7 @@ A Workflow Execution can be both a Parent and a Child Workflow Execution because 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](#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. +Consider the Child's [Parent Close Policy](/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 @@ -60,7 +61,7 @@ This means that if a Parent Workflow Execution utilizes Continue-As-New, any ong ::: -When a Parent Workflow Execution reaches a Closed status, the Temporal Service propagates Cancellation Requests or Terminations to Child Workflow Executions depending on the Child's [Parent Close Policy](#parent-close-policy). +When a Parent Workflow Execution reaches a Closed status, the Temporal Service propagates Cancellation Requests or Terminations to Child Workflow Executions depending on the Child's [Parent Close Policy](/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. @@ -128,7 +129,7 @@ Here are some important differences: - A Child Workflow has access to all Workflow APIs but is subject to the same [deterministic constraints](/workflows#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](#parent-close-policy) of `ABANDON`. +- A Child Workflow Execution can continue on if its Parent is canceled with a [Parent Close Policy](/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. @@ -140,42 +141,3 @@ An Activity usually models a single operation on the external world. Our advice: **When in doubt, use an Activity.** -## Parent Close Policy {#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). - -- [How to set a Parent Close Policy using the Go SDK](/develop/go/child-workflows#parent-close-policy) -- [How to set a Parent Close Policy using the Java SDK](/develop/java/child-workflows#parent-close-policy) -- [How to set a Parent Close Policy using the PHP SDK](/develop/php/child-workflows#parent-close-policy) -- [How to set a Parent Close Policy using the Python SDK](/develop/python/child-workflows#parent-close-policy) -- [How to set a Parent Close Policy using the TypeScript SDK](/develop/typescript/child-workflows#parent-close-policy) -- [How to set a Parent Close Policy using the .NET SDK](/develop/dotnet/child-workflows#parent-close-policy) - -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`](https://github.com/temporalio/api/blob/c1f04d0856a3ba2995e92717607f83536b5a44f5/temporal/api/enums/v1/workflow.proto#L44) 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
+