While I was building SMA runbooks in the past couple of months I bumped into this rather strange error. So happen few days ago, I tried to call (invoke) a child runbook, from a parent runbook function. SMA returned an error “Root element is missing” I simplified the structure so it looks like this…
Function Call:
It seems, that you are not able to call a PowerShell Child-Runbook within a function in the Parent-Runbook workflow . Why would you want to do that anyway? Well, I wanted to prevent code duplication and simplify the code, therefore I dumped everything into a function.
The same, more widely known error happens, if you try to call a runbook within an inlinescript, for example like this…
Inlinescript Call:
If you try to call the runbook via cmdlet Start-SmaRunbook it is possible to start the Child-Runbook in both cases…
Function Call:
Inlinescript Call:
Although you are capable to call the runbook via Start-SmaRunbook, there are some pro and contra. Microsoft has published a very good series of blog posts about SMA explaining the differences between both techniques either invoking runbooks inline or call the runbook via SMA web service (Start-SmaRunbook).
Comparison of Child Runbooks that are Invoked Inline versus Started with Start-SmaRunbook
Invoked Inline
- Pro
- Parent and child runbooks run in he same job, so there are fewer jobs in the system, which allows other runbooks to run.
- The parent runbook waits for the child runbook to finish before continuing, so the parent runbook can directly get any return data from the child.
- Exceptions thrown by the child runbook and stream output produced by the child are associated with the parent job, which can make troubleshooting easier, because there is only one job to investigate.
- Runbook input parameters can be of any type, primitive to complex.
- Con
- The parent runbook must wait for the child runbooks to complete, which can increase the overall time for the parent runbook to complete.
- You cannot use a variable or parameter in the parent runbook to pass in the name of an inline child runbook.
- The child runbook must be published before the parent runbook is published.
Started with Start-SmaRunbook
- Pro
- The parent and child runbooks run in different jobs, which allows the parent to spin off multiple jobs that can run in parallel.
- The parent runbook does not wait for the child runbooks, and so can continue processing while the child runbooks run.
- You can use a parameter or variable in the parent runbook to pass in the name of the runbook to invoke.
- Con
- Parent and child runbooks run in different jobs, so exceptions and stream output are stored separately and must be tracked down separately, which may make troubleshooting more difficult.
- More jobs are created in the system which can cause job limits to be reached and block other runbooks from running.
- Getting return data from a child runbook job is not straightforward.
- Runbook input parameters are restricted to primitive types, array, and object, because they must survive the JSON serialization of objects that occurs with the call through the web service.
I hope this gives you some insights.