Calling steps

Suppose that your workflow needs a function that is already performed by another workflow on your system. Rather than attempt to replicate the same function in your workflow, you can add a step to invoke the other workflow as needed. A workflow that invokes another workflow is the calling workflow. A workflow that is invoked by another workflow is the called workflow. On completion, the called workflow returns control to the calling workflow.

From the point of view of the calling workflow, the called workflow is simply another "step" to be performed. You define the called workflow in the workflow definition file for the calling workflow, on the step element (<step>), through a set of elements and attributes.

With the ability to call one workflow from another, you can follow a modular approach to designing workflows. You can include a common, frequently performed, action in one workflow and allow other workflows to call that workflow, as needed. By including one or more called workflows in your design, you can maximize reuse of your code by using "common workflows," and effectively, integrate several workflows together.

Start of change To make a workflow eligible to be called by another workflow, include the isCallable attribute on the workflow metadata element <workflowInfo>, as described in Callable workflows. End of change

How the user interacts with a calling step

In the Workflows task user interface, a step that invokes a called workflow is indicated to the user with the following icon in the Workflow Steps page:
Called Workflow icon

In the Workflows task, when the user reaches a step that calls another workflow, z/OSMF determines whether an instance of the called workflow is already active on the system. If so, the Workflows task redirects focus to the called workflow so that the step owner can complete it. If the called workflow is already completed, the Workflows task displays the Workflows Steps table, showing the step that invoked the called workflow as marked complete.

Otherwise, if the called workflow is not already created, the Workflows task opens to the Create Workflow page so that the user can create the workflow. The user can supply a name for the workflow on the Create Workflow page, or accept the default workflow name.

Coordinating workflow-to-workflow actions

The Workflows schema metadata attributes scope and isCallable can be useful for coordinating workflow-to-workflow actions across a system or sysplex. By setting these attributes in various combinations, you can achieve the following effects:

Restrict the number of instances of a workflow to one instance (a singleton).
Always attempt to use an existing instance of a workflow in response to a calling workflow. Or, always cause a new instance of a workflow to be created, even if an instance exists already.
Limit the use of a callable workflow to the same system or sysplex.

The scope and isCallable attributes are specified on the workflow metadata element (<workflowInfo>), as described in Callable workflows.

Nine combinations of scope and isCallable are possible, as shown in Table 1.

Table 1. Use scope and isCallable to coordinate workflow-to-workflow actions
scope value	isCallable value	Effect on the called workflow
system	system	Workflow is limited to one instance per system, and can be called on that system only. If an instance does not exist, an instance is created.
sysplex	system	Workflow is limited to one instance per sysplex, and can be called from the same system as the calling workflow.
none	system	A new instance is always created. The instance can be called from the same system as the calling workflow.
system	sysplex	Workflow is limited to one instance per system, and can be called from any system in the sysplex. If an instance does not exist, an instance is created. For an automated workflow, if the calling step is performed automatically, the called workflow is searched for only on the calling system. If an instance is found, it is used; otherwise a new instance is created on the calling system.
sysplex	sysplex	Workflow is limited to one instance per sysplex, and can be called from any system in the sysplex. If an instance does not exist, an instance is created.
none	sysplex	A new instance is always created. The instance can be called from any system in the sysplex.
system	none (omitted)	Workflow is not callable.
sysplex	none (omitted)	Workflow is not callable.
none	none (omitted)	Workflow is not callable.

How workflow access type is handled

When a workflow calls another workflow for processing, z/OSMF changes the access type for the called workflow to match the calling workflow. This processing ensures that the requested access type is applied consistently to both of the workflows in a calling relationship.

Note, however, that this processing is not performed when the called workflow is limited to one active instance in the system or sysplex.

Designing a step to call another workflow

To have a step call another workflow, specify the step element (<step>) with the elements for defining a called workflow. The major step elements for defining a called workflow in your workflow definition file are described in Table 2.

Table 2. Major step elements for defining a called workflow in your workflow definition file
Element name	Description	Required or optional
variableMapping	Used to transfer instance variable values between the called workflow and calling workflow, and specify options for sharing variables. More information about this element and its sub-elements is provided in Sharing variables between the calling workflow and called workflow.	Optional.
callingStepWeight	Specifies the relative difficulty of the step compared to other steps within this workflow (a positive integer value 1 – 1000). The Workflows task uses this value in the calculation of the percentage-complete value that is displayed for the calling workflow. The scale is arbitrary; specify it at your discretion. Consider the difficulty of the called workflow as single step among the other steps in the calling workflow.	Required.
callingStepSkills	Specifies a suggested skills category for performing the step, such as "Security administration" or "Network administration." The Workflows task displays this value in the step table for a workflow. This value is free-form; specify it at your discretion.	Optional.
callingStepAutoEnable	Indicates whether the step is to be performed automatically when all prerequisite steps are completed, and no user inputs are required. If callingStepAutoEnable is not specified, the default is false. More information about designing steps to run automatically is provided in Automated steps	Optional.
canCallingStepMarkAsFailed	Indicates whether the step can be marked as Failed manually by the step owner. When set to true, the Review Instructions page in the Step Perform wizard includes the option to allow the step owner to mark a step as Failed manually. When false, this option is not displayed to the user. If canCallingStepMarkAsFailed is not specified, the default is false.	Optional.
calledWorkflowDefinitionFile	Specifies the path name of an external file that contains the workflow definition for the called workflow. This element is optional; it is used only if z/OSMF must create a new instance of the called workflow on the system.	Optional.
calledWorkflowDescription	Specifies a short description of the called workflow. The Workflows task displays this text on the Create Workflow page, when it prompts the user for the workflow definition file.	Required.
calledWorkflowID	The name of the workflow to be called. The combination of calledWorkflowID and calledWorkflowVersion must be unique within the Workflows task.	A selection is required: Either calledWorkflowID or calledWorkflowMD5.
calledWorkflowVersion	The version of the definition file that is used to create the called workflow. The combination of calledWorkflowID and calledWorkflowVersion must be unique within the Workflows task. The Workflows task caches only the latest version of an imported workflow definition file. Therefore, to ensure that the most current version is used, you must update the version value whenever you modify any portion of the workflow definition file, including changes to any sub-files or referenced files. For this reason, when you create a workflow definition file, you might want to complete the development phase on a workstation before you import the workflow definition into the Workflows task.	Optional.
calledWorkflowMD5	An MD5 encrypted value (a 128-bit hash value) that you can use to identify the called workflow.	A selection is required: Either calledWorkflowID or calledWorkflowMD5.

Identifying the called workflow

To invoke a called workflow, the calling step must identify which workflow is to be called. The z/OSMF schema provides two methods for you to uniquely identify the called workflow. Use either of the following approaches:

Specify the workflow ID of the called workflow on the workflow ID element (<calledWorkflowID>). You can further qualify this specification by optionally including the version of the workflow definition of the called workflow on the element (<calledWorkflowVersion>). The version is typically updated by the workflow author whenever any portion of the workflow definition file is changed.
The Workflows task caches only the latest version of an imported workflow definition file. Therefore, to ensure that the most current version is used, you must update the version value whenever you modify the workflow definition. For this reason, when you create a workflow definition file, you might want to complete the development phase on a workstation before you import the workflow definition into the Workflows task.
Specify the called workflow MD5 element (<calledWorkflowMD5>). This element specifies a 128-bit hash value that can be used to identify the called workflow. You can specify this element in place of the workflow ID and version elements.

Note:

No more than one level of nesting of called workflows is permitted in a workflow-to-workflow relationship. Thus, the specified workflow definition cannot contain a step that calls another workflow. End of change

Sharing variables between the calling workflow and called workflow

It is possible to share variables between the calling workflow and the called workflow. Any variables that are defined to either workflow can be shared by using the element <variableMapping>.

This element consists of two sub-elements and their associated attributes, as follows:

Use the element <fromCallingToCalled> to describe the variable values that are to be transferred from the calling workflow to the called workflow.
Use the element <fromCalledToCalling> to describe the variable values that are to be transferred from the called workflow to the calling workflow. To handle variable conflicts, you can optionally include the attribute override= to specify whether the called workflow variables take precedence over the calling workflow variables. The default is override=false.

On each element, you can optionally specify the following sub-elements and attributes:

regExpression

Regular expression. Use this attribute to filter on variable names with one or more wildcard characters. For example, to select all variables prefixed with "setting," you can specify:

<regExpression>^setting.*$</regExpression>

variableName

Name of the variable. Use this element to identify the variable that is to be shared with the target workflow. The variable is also saved in the Workflows task variable pool.

To map this variable to a specific variable in the target workflow, include the attribute mapTo= on the element variableName and set it to the name to the target variable. The behavior of the attribute mapTo= on the element variableName depends on which element is used to pass variables, as follows:

When specified on the element <fromCallingToCalled>, the variables are mapped to the target variables only when a new instance of the called workflow is created in response to the calling step.
When specified on the element <fromCalledToCalling>, the variables are mapped to the target variables on completion of the called workflow.

Example of how a called workflow is defined in a step

As an example, assume that your workflow includes a step ("Define User"), which is used to define a user ID and security group to the system security product. Usually, to verify that this setup is done correctly, users would run another workflow. In this example, you add a step to invoke the other workflow directly as a called workflow. When the step owner selects this step to be performed, the Workflows task displays the called workflow, so that the step owner can perform it.

Further assume that a number of variables will be shared between the workflows through the use of the element <variableMapping>. The step that calls the workflow (the calling step) will pass a number of variables on the element <fromCallingToCalled>. Similarly, the called workflow will pass a number of variables to the called workflow, on the element <fromCalledToCalling>.

The definition for a called workflow might be coded as shown in Figure 1.

For illustrative purposes, the example in Figure 1 shows a variety of methods for sharing variables between workflows, as follows:

On the element <fromCallingToCalled>, the step that calls the workflow (the calling step) passes variables in the following ways:
- To pass all variables with "setting" as the variable name prefix, the calling step specifies the element <regExpression>, as follows:
```
<regExpression>^setting.*$</regExpression>
```
- To pass the value of the variable called st_user to the called workflow, the calling step specifies the variable, as follows:
```
<variableName>st_user</variableName>
```
- If an instance of the called workflow is not already created, z/OSMF will create one in response to the called workflow. If so, the element <fromCallingToCalled> ensures that the new called workflow inherits the variables from the calling workflow. In this example, the value of the variable st_uid is passed to the calling workflow, and overlays the existing value of the variable named st_group because the attribute mapTo= is included on the element <variableName>, as follows:
```
<variableName mapTo="st_group">st_uid</variableName>
```
On the element <fromCalledToCalling>, the called workflow shares a number of variables with the calling workflow. Any variables to be copied back to the calling workflow are performed on completion of the called workflow. Here, the override attribute is included, so that the called workflow's variables will override those of the calling workflow:
- To pass all variables with "set" as the variable name prefix, the element <regExpression> is specified, as follows:
```
<regExpression>^set.*$</regExpression>	
```
- To pass the value of variable called st_uid to the calling workflow, and overlay its existing value for the variable named st_gid, the mapTo= attribute is included on the variableName element, as follows:
```
<variableName mapTo = "st_gid">st_uid</variableName>
```
- To pass the variable called st_user to the calling workflow, the variable is specified, as follows:
```
<variableName>st_user</variableName>
```

Figure 1. Example: Defining a called workflow on the step element tag.

<step name="Define User">
	<title>Ensure that the user ID and group are created.</title>

	<description>
			This step verifies that the required user ID and security 
			group are created. This step invokes another workflow (a called workflow), 
			which is identified here based on the workflow ID and version. 
			Alternatively, we could have identified the called workflow using its 
			MD5 hash value.
	</description>
	
	<variableMapping>			
 	<!-- Variables to share with the called workflow. -->	
					<fromCallingToCalled>	     
  
			    	<!-- Use a regular expression to filter the variables. -->		
       		<regExpression>^settin.*$</regExpression>	   

       	 <!-- The following line copies the value of st_uid to the variable st_group. -->
				  	<variableName mapTo = "st_group">st_uid</variableName>   
  
		  		<!-- The following line copies the value of st_user to the called workflow,   
			      		if no st_user variable definition already exists in the called workflow.      
			      		This value also will be saved in the Workflows task variable pool.-->						
						<variableName>st_user</variableName>	   

					</fromCallingToCalled>
  
				<!-- Variables to share with the calling workflow. Here, the override attribute
         is set to true, so that the called workflow's variable values will override 
				  			those of the calling workflow.  -->   	  		
						<fromCalledToCalling override= "true">      	   
								<regExpression>^set.*$</regExpression>							
								<variableName mapTo = "st_gid">st_uid</variableName>
								<variableName>st_user</variableName>							
					</fromCalledToCalling>
		</variableMapping>
  
 	<callingStepWeight>10</callingStepWeight>	
 
		<callingStepSkills>System Programmer</callingStepSkills>
	
	 <calledWorkflowDefinitionFile>\usr\lpp\zosmf\V2R1\samples\workflow_sample_wizards.xml
	 </calledWorkflowDefinitionFile>

	<calledWorkflowDescription>This called workflow is used to help verify that the user 
   and group are created	successfully.</calledWorkflowDescription>
	
	<calledWorkflowID>workflow.sample.wizards</calledWorkflowID>	
	
	<calledWorkflowVersion>1.0</calledWorkflowVersion>
	
</step>