|
1 | 1 | --- |
2 | | -title: Child runbooks in Azure Automation |
3 | | -description: Describes the different methods for starting a runbook in Azure Automation from another runbook and sharing information between them. |
| 2 | +title: Create modular runbooks in Azure Automation |
| 3 | +description: This article tells how to create a runbook that is called by another runbook. |
4 | 4 | services: automation |
5 | 5 | ms.subservice: process-automation |
6 | 6 | ms.date: 01/17/2019 |
7 | 7 | ms.topic: conceptual |
8 | 8 | --- |
9 | | -# Child runbooks in Azure Automation |
| 9 | +# Create modular runbooks |
10 | 10 |
|
11 | | -It is a recommended practice in Azure Automation to write reusable, modular runbooks with a discrete function that is called by other runbooks. A parent runbook often calls one or more child runbooks to perform required functionality. There are two ways to call a child runbook, and there are distinct differences that you should understand to be able to determine which is best for your scenarios. |
| 11 | +It is a recommended practice in Azure Automation to write reusable, modular runbooks with a discrete function that is called by other runbooks. A parent runbook often calls one or more child runbooks to perform required functionality. |
12 | 12 |
|
13 | | -## Invoking a child runbook using inline execution |
| 13 | +There are two ways to call a child runbook, and there are distinct differences that you should understand to be able to determine which is best for your scenarios. The following table summarizes the differences between the two ways to call one runbook from another. |
| 14 | + |
| 15 | +| | Inline | Cmdlet | |
| 16 | +|:--- |:--- |:--- | |
| 17 | +| Job |Child runbooks run in the same job as the parent. |A separate job is created for the child runbook. | |
| 18 | +| Execution |Parent runbook waits for the child runbook to complete before continuing. |Parent runbook continues immediately after child runbook is started *or* parent runbook waits for the child job to finish. | |
| 19 | +| Output |Parent runbook can directly get output from child runbook. |Parent runbook must retrieve output from child runbook job *or* parent runbook can directly get output from child runbook. | |
| 20 | +| Parameters |Values for the child runbook parameters are specified separately and can use any data type. |Values for the child runbook parameters have to be combined into a single hashtable. This hashtable can only include simple, array, and object data types that use JSON serialization. | |
| 21 | +| Automation Account |Parent runbook can only use child runbook in the same Automation account. |Parent runbooks can use a child runbook from any Automation account, from the same Azure subscription, and even from a different subscription to which you have a connection. | |
| 22 | +| Publishing |Child runbook must be published before parent runbook is published. |Child runbook is published any time before parent runbook is started. | |
| 23 | + |
| 24 | +## Invoke a child runbook using inline execution |
14 | 25 |
|
15 | 26 | To invoke a runbook inline from another runbook, use the name of the runbook and provide values for its parameters, just like you would use an activity or a cmdlet. All runbooks in the same Automation account are available to all others to be used in this manner. The parent runbook waits for the child runbook to complete before moving to the next line, and any output returns directly to the parent. |
16 | 27 |
|
@@ -50,14 +61,14 @@ $vm = Get-AzVM –ResourceGroupName "LabRG" –Name "MyVM" |
50 | 61 | $output = .\PS-ChildRunbook.ps1 –VM $vm –RepeatCount 2 –Restart $true |
51 | 62 | ``` |
52 | 63 |
|
53 | | -## Starting a child runbook using a cmdlet |
| 64 | +## Start a child runbook using a cmdlet |
54 | 65 |
|
55 | 66 | > [!IMPORTANT] |
56 | 67 | > If your runbook invokes a child runbook with the `Start-AzAutomationRunbook` cmdlet with the `Wait` parameter and the child runbook produces an object result, the operation might encounter an error. To work around the error, see [Child runbooks with object output](troubleshoot/runbooks.md#child-runbook-object) to learn how to implement the logic to poll for the results using the [Get-AzAutomationJobOutputRecord](/powershell/module/az.automation/get-azautomationjoboutputrecord) cmdlet. |
57 | 68 |
|
58 | 69 | You can use `Start-AzAutomationRunbook` to start a runbook as described in [To start a runbook with Windows PowerShell](start-runbooks.md#start-a-runbook-with-powershell). There are two modes of use for this cmdlet. In one mode, the cmdlet returns the job ID when the job is created for the child runbook. In the other mode, which your script enables by specifying the *Wait* parameter, the cmdlet waits until the child job finishes and returns the output from the child runbook. |
59 | 70 |
|
60 | | -The job from a child runbook started with a cmdlet runs separately from the parent runbook job. This behavior results in more jobs than starting the runbook inline, and makes the jobs more difficult to track. The parent can start more than one child runbook asynchronously without waiting for each to complete. For this parallel execution calling the child runbooks inline, the parent runbook must use the [parallel keyword](automation-powershell-workflow.md#parallel-processing). |
| 71 | +The job from a child runbook started with a cmdlet runs separately from the parent runbook job. This behavior results in more jobs than starting the runbook inline, and makes the jobs more difficult to track. The parent can start more than one child runbook asynchronously without waiting for each to complete. For this parallel execution calling the child runbooks inline, the parent runbook must use the [parallel keyword](automation-powershell-workflow.md#use-parallel-processing). |
61 | 72 |
|
62 | 73 | Child runbook output does not return to the parent runbook reliably because of timing. In addition, variables such as `$VerbosePreference`, `$WarningPreference`, and others might not be propagated to the child runbooks. To avoid these issues, you can start the child runbooks as separate Automation jobs using `Start-AzAutomationRunbook` with the `Wait` parameter. This technique blocks the parent runbook until the child runbook is complete. |
63 | 74 |
|
@@ -98,19 +109,6 @@ Start-AzAutomationRunbook ` |
98 | 109 | –Parameters $params –Wait |
99 | 110 | ``` |
100 | 111 |
|
101 | | -## Comparison of methods for calling a child runbook |
102 | | - |
103 | | -The following table summarizes the differences between the two ways to call a runbook from another runbook. |
104 | | - |
105 | | -| | Inline | Cmdlet | |
106 | | -|:--- |:--- |:--- | |
107 | | -| Job |Child runbooks run in the same job as the parent. |A separate job is created for the child runbook. | |
108 | | -| Execution |Parent runbook waits for the child runbook to complete before continuing. |Parent runbook continues immediately after child runbook is started *or* parent runbook waits for the child job to finish. | |
109 | | -| Output |Parent runbook can directly get output from child runbook. |Parent runbook must retrieve output from child runbook job *or* parent runbook can directly get output from child runbook. | |
110 | | -| Parameters |Values for the child runbook parameters are specified separately and can use any data type. |Values for the child runbook parameters have to be combined into a single hashtable. This hashtable can only include simple, array, and object data types that use JSON serialization. | |
111 | | -| Automation Account |Parent runbook can only use child runbook in the same Automation account. |Parent runbooks can use a child runbook from any Automation account, from the same Azure subscription, and even from a different subscription to which you have a connection. | |
112 | | -| Publishing |Child runbook must be published before parent runbook is published. |Child runbook is published any time before parent runbook is started. | |
113 | | - |
114 | 112 | ## Next steps |
115 | 113 |
|
116 | 114 | * [Starting a runbook in Azure Automation](start-runbooks.md) |
|
0 commit comments