childjob

Task Purpose

Some jobs share a need for the same set of task sequences. For this situation, a separate workflow containing the set of tasks can be created and the childJob task can be used to run the separate workflow. In addition to making workflows resuable, child jobs reduce the complexity of workflows by reducing them to a smaller set of childJob tasks. This improves the readability of workflows. The childJob task also enables users to run multiple iterations of that same workflow in parallel or sequentially.

Task Properties

ChildJob task properties are referenced in the table below.

Child Jobs With No Loop

The childJob task starts a job inside the currently running job. The calling or parent job waits for the child to finish (complete or cancel) before progressing to its next task. If the child job is cancelled, it will error and the job will progress along the its error transition. If it completes, job execution will progress along the success transition.

Anything that is a job variable in the child job is placed in an object with a <job_variable__name> : <job_variable_value> key/value pair format. Variables can then be passed up to the parent childJob task via the outgoing schema of the child workflow. Then, if a particular variable is needed, a transformation can be used to query out that key (job variable name).

By default, the Enable Looping slider is off, as seen below.

Figure 1: No Looping

Task Data for No Loop

Pictured below are task details for the child job. The Workflow input is the name of the workflow the childJob task runs. Looping is not enabled. The Workflow Input Job Variable is a string running a Task.

Figure 2: ChildJob Details

Child Job With No Loop Results

The following output shown below is after the child job finishes with status complete (Figure 3). Variables that are passed into the output are determined by the output schema of the child job, which in this case includes the incoming job variables and the _id and initiator job variables.

Figure 3: No Loop Results

Child Jobs That Loop

Multiple iterations (loops) of the same child job can be run using a childJob task sequentially or in parallel by specifying the loopType of the childJob task to be sequential or parallel. An iteration of the child job is run for each element of the input Loop Array, so that the length of the array determines the total number of child jobs run. If run sequentially, each child job iteration is run after the previous child job iteration is finished (complete or cancelled). When run in parallel, all iterations are started at once, and the childJob task finishes after the final child job finishes.

If the childJob task loops and contains a transformation input, the provided transformation is run on each element of Loop Array to produce the job variables required prior to starting each child job. The result of each transformation run is passed into the corresponding child job iteration as job variables. The task allows the creation of transformations locally. If created locally on the task, the outgoing schema of the created transformation is set as the input schema of the child workflow. A single incoming schema is created by default with $id and currentValue. When the childJob task is run, each element of Loop Array is passed as currentValue in the transformation. If additional input schemas are added to the transformation besides currentValue, these additional schemas are added as additional JST parameters that can be passed in via the childJob task. This allows users to define specific values that do not change across iterations.

If the childJob task loops and contains a Loop Array input with no transformation, each element of the input Loop Array is passed into the corresponding child job iteration directly as input job variables. In this case, it is required that each element is type object, with the same <job_variable__name> : <job_variable_value> key/value pair format used with non-looping child jobs.

A childJob task that loops will result in an error if all the child jobs are cancelled. If at least one child job is complete, the task ends in status "complete". The job variables (determined by the output schema) and final status of each child job iteration is returned in the task output under the loop property.

When a parent job is cancelled which contains a childJob task that loops, all non-completed loop iterations will also be cancelled. Any loop iterations that have not yet been created, such as when the Loop Array has a large number of elements, will never run.

Figure 4: Loop Settings

ChildJob Loop Index Variable

To reference (access) the index value within a childJob that is being executed as a loop, an additional job variable named the childJobLoopIndex is available to prevent users from having to manually pass the index via data array.

To use the childJobLoopIndex variable:

1. Open the task in a workflow that is a child of a runChildJob task in a parent workflow.
2. Switch the Reference Task to “job”.
3. Select the dropdown for Reference variable to enable the field.
4. Click Edit and type “childJobLoopIndex”.
5. Click Save to retain the changes.

This code snippet shows where childJobLoopIndex is correctly passed to the child job loop iteration in a child workflow. Indexing starts at 0.

Figure 5: childJobLoopIndex Example

ChildJob With Loop And Transformation Example

In the following example, the child workflow named child is run with the Loop Type set to Parallel. The same task details are used as shown above in the non-looping child job case. The following sections walk through the creation of a transformation locally to run on each element of Loop Array.

Parallel Loop Settings

Figure 6 below displays the Loop Settings prior to the addition of a transformation. If no transformation is provided, the child job will directly pass in each element of Loop Array as job variables to the child job. If any element is not type object, the childJob task will error. A new transformation can be created by clicking the Create New Transformation ( + ) button to the right of the transformation. Existing transformations can also be used.

Figure 6: Loop Settings No Transformation

Local Transformation Creation

Figure 7 shows what this transformation would look like. Note that currentValue is conected to getProperty which is then connected to each corresponding outgoing schema.

Figure 7: Transformation Set

Results After Complete Child Job Task

The following shows the results of the above created child job task. The task and the child job have completed successfully.

You can also query the loop results of childjob after it has finish running. The results will be wrapped in an object that has "status" which indicates if all the items finished running or not, and a "loop" field which is an object array that has results for each run.

Figure 8: Looping Result

ChildJob With Loop And No Transformation

If the childJob task loops, but contains no transformation, the elements of the Loop Array are passed in directly as job variables to the child job. Note that transformations are the preferred route to take for child job looping.

Viewing Task Details for a ChildJob

To open task details for a child job, navigate to the Job Details page within Operations Manager, and click the menu button (⋮) and select the View option to open the task details dialog.

Figure 9: Job Details ChildJob