About workflows
This topic introduces the terminology and concepts that are helpful for you to understand as you use the Workflows task.
In z/OSMF, a workflow is a guided set of steps that help you perform a common activity on z/OS, such as configuring a software product or component. A workflow guides you through the complete set of steps that are needed to accomplish a goal, and, when dependencies exist, controls the sequence for performing those steps. In this way, a workflow can help to ensure that you perform the steps in the correct order, and that prerequisites and dependencies are identified clearly.
Conceptually, a workflow encompasses both the work to be performed and its performers. By identifying the individual steps to be performed, a workflow allows for these steps to be divided among different areas of an organization, and different members of your team. With a workflow, a project owner can delegate specific items to the team members best suited to carrying out particular tasks.
- Is based on a structured set of steps that are designed by a workflow author. A z/OS organization can write its own workflows or obtain workflows from a third-party source (a workflow provider). z/OSMF includes samples for workflow authors to reference when they are creating workflows.
- Is described to z/OSMF through a workflow definition file. A workflow is created when a user imports the workflow definition file into z/OSMF.
- Identifies the individual steps to be performed and allows for these steps to be divided among different areas of an organization, helping to facilitate user activities on z/OS.
In z/OSMF, the Workflows task allows a z/OS installation to create and manage workflows for performing activities on the z/OS system. The user who is responsible for the workflow and seeing that it gets completed is the workflow owner. The workflow owner assigns workflow steps to users, making them assignees of the step. The user who accepts ownership of a step becomes the step owner.
- The Workflows page displays the existing workflows for an installation, and provides the control point for creating and managing workflows.
- The Steps page displays the steps in a workflow, and provides the control point for managing the steps. From this page, you can select actions for the steps, such as assigning steps, changing ownership of steps, and performing steps.
Terms you should know
- Workflow
- 1. An activity that is associated with the z/OS system, such as configuring a component or product. 2. The instantiation of a workflow in z/OSMF, based on a workflow definition. A workflow consists of one or more units of work to be performed on the z/OS system, as described by the workflow definition. A workflow is created when the Workflows task is used to create an instance of a workflow from a supplied workflow definition file.
- Workflow author
- The person, typically a programmer, who codes the workflow definition file in the XML tagging language.
- Workflow category
- A classification of the activities to be performed in the workflow. The following values are
valid:
- General
- All other workflows
- Configuration
- Workflows that are used to configure system software, such as a product or component
- Provisioning
- Workflows that are used to provision z/OS middleware, such as a Db2 or IMS. Provisioning workflows are used with IBM Cloud Provisioning and Management for z/OS.
- Workflow definition
- The logical structure of a workflow, represented as a series of one or more steps. The workflow definition identifies the various system objects and actions that constitute activities on z/OS and the rules for performing those activities. The workflow definition includes all of the information that is specified in, or referenced by, the primary XML file (the workflow definition file) and possibly other files that are included by the workflow definition file. This content typically includes information about the workflow (such as name and version), step definitions, variable definitions, file templates, and bundle files.
- Workflow definition file
- The primary XML file for a workflow definition. A workflow is stored in z/OSMF when its workflow definition file, and optionally, a workflow variable input file, is imported into the Workflows task.
- Workflow variable input file
- An optional file that supplies default values for one or more of the input variables that are defined in the workflow definition file. The workflow variable input file is specified as input when the workflow definition file is imported into the Workflows task. Typically, a workflow provider might supply a workflow variable input file to save users from having to manually enter inputs when they perform a workflow. By limiting user interaction, a workflow variable input file can help to simplify the user experience of performing a workflow.
- Output file
- A file that is created by a step, as the result of running a program. Typically, the file holds the results of a batch job, shell script, or REXX exec program. It can be used by other steps or workflow instances.
- Global variable
- A variable definition that is available to all workflow instances. The Workflows task saves global variables in a repository that is called the global variables pool.
- Instance variable
- A variable definition that is available to only to instances of a particular workflow.
- Workflows task
- The task in the z/OSMF navigation area that allows users to interact with workflows on z/OS.
- Workflow owner
- The user who is given ownership of the workflow through the Workflows task. The workflow owner is responsible for delegating the work in the workflow to users to perform (the step assignees).
- Workflow provider
- The source of the workflow definition file, which is typically IBM or a software vendor.
- Step
- A single, logical unit of work in a workflow. Consider each step to describe a specific activity to be performed on the system. A step is available to be performed when the workflow owner assigns the step to a user, and the user accepts ownership of the step.
- Step owner
- The user who accepts ownership of a step and therefore responsibility for performing the step.
- Automation processing
- The processing of a workflow that contains one or more automated steps. A workflow that is comprised entirely of automated steps can complete with little or no user intervention. When automation processing is started on the workflow, the workflow runs to completion or until it is stopped by another condition, such as a user request or an error.
- Automated step
- A step can be designed to run automatically (without user interaction) when it is in Ready state. Such a step is referred to as an automated step. A workflow that is comprised entirely of automated steps can complete with little or no user intervention. In the Workflow Steps table, automated steps are identified in the column Automated.
- Parallel-steps workflow
- A workflow with automated steps that can be run in parallel (concurrently). When a parallel-steps workflow is started, the Workflows task locates all of the automated steps with Ready status, and attempts to run these steps concurrently. The failure of an automated step does not stop automation processing for the other automated steps. Processing continues until all of the automated steps are completed or failed, or the user stops automation processing by using the Stop Automation action on the Workflows page.
- Called workflow
- A workflow that is started by another workflow for execution. Conceptually, a called workflow is a step in the workflow that calls it (the calling workflow).
- Conditional step
- A step that can be performed when a logical condition is satisfied on the z/OS system or in the Workflows task. For example, a conditional step might become eligible to be performed if a job that is run by another step ends with a particular return code. A conditional step remains unavailable to be performed as long as the condition is not satisfied.
- Feedback step
- A step that includes a feedback form with questions for the step owner to answer at the conclusion of a step.
- Immediate execution step
- A template step that runs an executable program in real time, such as a REXX exec or UNIX shell script. Contrast with a batch execution step, which is a template step that runs a program as a batch job.
- REST step
- A step that issues a REST API request, such as a GET or PUT request.
- Template step
- A step that is designed to run an executable program, such as a JCL job, a REXX exec, or a UNIX
shell script. On completion, the results can be made available to other steps, in the form of
variables or an output property file. Depending on how the program is processed, a template step is
either of the following:
- Immediate execution step, which runs a program in real time
- Batch execution step, which runs a program as a batch job.
- Archived workflow
- When a workflow is archived, its information is saved in z/OSMF for future reference. The workflow is no longer active, but its information can be viewed by the workflow owner, using the Workflows table action Open Archived Workflows. When an archived workflow is no longer needed, it can be deleted from z/OSMF by the workflow owner.
Prerequisite steps and dependent steps
Some steps have dependencies on other steps in the workflow. A step that cannot be performed until another step is completed is said to depend on a prerequisite step. When prerequisite steps exist, the Workflows task displays the steps for you to see and act on.
To satisfy a prerequisite step, you must either complete the step or skip it. A step is considered complete when it is performed (through the Perform action) or overridden (through the Override Complete action). If you decide to skip a step, you can select it with the Skip action. The Workflows task treats skipped steps as completed.
Through the enforcement of state changes, Workflows task ensures that prerequisite steps are satisfied (completed or skipped) before dependent steps can be performed.
If a prerequisite step is a parent step (has substeps), z/OSMF treats all of the substeps in the parent step as prerequisites.
Conditional steps
A conditional step is available to be performed based on whether a logical condition is satisfied. For example, a conditional step might become eligible to be performed if a job that is run by another step ends with a particular return code. A conditional step remains unavailable to be performed while the condition is not satisfied. A conditional step, which depends on a logical condition, is different from a dependent step, which depends on a particular step being completed.
Optional steps
A
step might be indicated in the workflow as an optional step;
the text (optional) is added as a prefix to the step
title. The optional designation means that the step might not be applicable
to your environment. For an optional step, you must determine whether
the step is to be completed or skipped.
To ensure that a workflow is followed to completion, z/OSMF does not allow a workflow to reach 100 percent complete unless all of its steps are completed or skipped. If you determine that a particular step is not applicable to your environment, you can skip the step (through the Skip action). Doing so removes the step from the Percent Complete calculation for the workflow so that the omission of the step does not prevent the workflow from reaching 100-percent completion.
Steps and substeps
Each step can contain substeps, which can also contain substeps. Up to five levels of nesting are possible. A workflow can contain up to 500 steps and substeps (a combined total).
In the Steps page, step titles are numbered to indicate the sequence in which steps are to be performed. The first step in the Workflow Steps table starts with number 1.
Substeps are shown with indented titles. A substep shares the numerical value with its parent, but with '.x' appended to its step number, where 'x' is a numerical value that starts with 1. For a substep nested five levels deep, for example, the step number is indicated in the form 'x.x.x.x.x'.
Step automation in the Workflows task
A step can be designed to run without user intervention. Such a step is referred to as an automated step. When an automated step is present in a workflow, the step owner can allow the step to run automatically, or can choose to perform the step manually.
A workflow might have both automated steps and non-automated (manually performed) steps. A workflow with at least one automated step is considered to be an automated workflow.
In the Workflow Steps table, automated steps are identified in the column Automated. When automated steps are ordered consecutively in a workflow, a request to run the first automated step begins a process in which each subsequent automated step can run to completion, or until one of the steps encounters a condition that stops the processing of steps. A workflow that is comprised entirely of automated steps can run to completion without user intervention.
- Completion of all steps.
- Processing reaches a non-automated step.
- Processing reaches an automated step for which one or more required variables are not satisfied.
- Processing reaches an automated step for which variable conflicts exist, and the user is prompted to resolve the conflict.
- Processing reaches an automated step that is not currently eligible for automatic processing. That is, the step is Unassigned, Assigned, Not Ready, or Submitted.
- Processing reaches an automated step that is suspended.
- Processing reaches a step that is not owned by the user who started automation processing for the workflow.
- Processing is stopped through a user request.
- An error is encountered.
For workflows that contain automated steps, z/OSMF creates notifications to inform step owners of the automation progress. At the completion of an automated step or a sequence of automated steps, z/OSMF creates a notification to inform the step owner of the step status. If processing reaches a manual step that requires user interaction before the workflow can continue, z/OSMF creates a notification for the step owner to prompt for action.
- Completion of the automated step
- Completion of all automated steps in the workflow
- Automation is started through request
- Automation is stopped through user request
- Automation is stopped at a suspended step
- An error is encountered during the processing of an automated step.
Using a wizard or dialog to complete a step
- For an automated step, the Workflows task displays a dialog, called the Perform Automated Step dialog to confirm your selection for the step and any subsequent automated steps.
- For a manual step, the Workflows task displays a wizard, called the Step Perform wizard to guide you in the completion of the step. The wizard contains instructions for you to follow, which are detailed directions for what you must do to perform the step to completion. Depending on the requirements of the step, the Workflows task might first prompt you for installation-specific values and then use these values to provide you with tailored instructions.
For a manual step, the wizard might consist of textual instructions only, such as describing a system change that you must perform manually before you can return to the Workflows task. Or, the wizard might also include guided assistance in performing some work that is necessary for completing the step, such as submitting a batch job, shell script, or REXX exec. The Step Perform wizard can include none, one, or more types of assistance, depending on the step definition within the workflow definition.
When you perform a step, follow the instructions (and actions, if any) and then press Finish on the instructions page to have the step marked complete.
The states of a step
A step moves through different states during its lifecycle. The choice of actions that can be performed against the step depend on its current state.
- Unassigned state
- Assigned state
- Not ready state
- Ready state
- In Progress state
- Complete state.
- Complete (Override) or Skipped, instead of Complete
- Conflicts, for a step that creates an output properties file
- Submitted or Failed, for a step that submits a job to run on z/OS.
Throughout the step lifecycle, this flow might vary, depending on whether the step changes ownership or is reset to a previous state. Through the enforcement of state changes and a history collection function, the Workflows task allows users to track the step through each of these stages.
For any action that causes a state transition, the user can optionally provide a comment. The Workflows task records comments as part of the state transition in the workflow history. Thus, each action can have its own comment, with supplementary, user-supplied information. The commenting function in the Workflows is present for all actions, with the exception that no comments are solicited for the Perform action.
As with performing system changes manually, use caution in performing the steps of a workflow. Using the Workflows task, you can repeat steps as needed, to correct mistakes. However, for some system changes it might be necessary for you to manually undo a change on your system to correct mistakes. In such cases, consult the workflow instructions from the workflow provider for recommendations about undoing the results of a step.
Available actions for a step
A step is available to be performed when the workflow owner assigns the step to a user (the assignee), the assignee accepts ownership of the step, thus becoming the step owner, and the step has no unsatisfied prerequisite steps.
| Action | Description | Applicable State | Available to |
|---|---|---|---|
| Properties | Display the Step Properties page so that you can view the properties for the selected step. To enable this action, select 1 step only. | All step states. | All users. |
| Accept | Display the Accept dialog so that you can accept ownership of steps that are assigned to you. | Assigned state. | Workflow owner and the step assignees. |
| Perform | Display the Perform tab of the Step Properties page so that you can perform the selected step. To enable this action, select 1 step only. | Available when step state is:
|
Step owner. |
| Skip | Display the Skip dialog so that you can bypass the performing of a step. | All step states. | Workflow owner and the step owner. |
| Status | Display the Status tab of the Step Properties page so that you can view the completion status of the last job to be submitted when the step was performed. To enable this action, select 1 step only. | Available when step state is:
|
Workflow owner and the step owner. |
| Override Complete | Display the Override Complete page so that you can mark a step as complete to indicate that the work was performed outside of the Workflows task. | All step states. | Workflow owner and the step owner. |
| Resolve Conflicts | Display the Input Variables tab of the Step properties page so that you can resolve conflicts between variables in the output file and existing variables for the Workflows task. | Available when the step state is Conflicts. | Workflow owner and the step owner. |
| Change Called Workflow | Display the Change Called Workflow dialog so that you can modify the current selection of a called workflow. | Available when the step state is Conflicts. | Workflow owner and the step owner. |
| Add Assignees | Display the Add Assignees page so that you can assign one or more steps to users. | All step states. | Workflow owner and the step owner. |
| Remove Assignees | Display the Remove Assignees page
so that you can remove one or more assignees from a step. This action is available only when the selected steps have assignees. |
All step states. | Workflow owner and the step owner. |
| Take Ownership | Display the Take Ownership dialog so that you can assume ownership of a step from the current step owner. | Available when the step state is:
|
Workflow owner and the step assignees. |
| Return | Display the Return dialog so that you can cancel your acceptance of a step, thus making the step available for another assignee to accept. | Available when the step state is:
|
Step owner. |
| Request Assignment | Display the Request Assignment dialog so that you can request to be assigned the selected steps. | Available when the step state is:
|
Workflow owner and the step assignees. |
Parent steps and descendant leaf steps
Two step types exist: parent steps and leaf steps. A parent step is one that consists of descendant steps (substeps). A leaf step has no substeps; conceptually, it cannot be broken down further.
- Unassigned
- Not Ready
- In Progress
- Skipped
- Complete
- Override Complete
- Conflicts.
| When the descendant leaf steps are: | The parent step is: |
|---|---|
| All in Unassigned state | Unassigned |
| All in Ready state | In Progress |
| All in Not Ready state | Not Ready |
| All in Complete state | Complete |
| All in Override Complete state | Override Complete |
| All in Skipped state | Skipped |
| All in Conflicts state | Conflicts |
| A mix of Complete, Override Complete, or Skipped | Complete |
| Any other combination of states. | In Progress |
When you select a parent step in the Workflow Steps table, you select all of its descendant steps. Actions that are taken on the parent step, such as Assign, apply to the substeps, too.
The Perform tab and the Status tab in the properties page for a parent step are always disabled. Any meaningful information from the workflow provider about the parent step is contained in the Description field in the General tab of the Properties for Step page.
- If a step is in the Assigned state, and all of its assignees are removed through the Remove Assignees action, the Workflows task resets the step to the Unassigned state. Otherwise, the step remains in the Assigned state as long as at least one user is assigned to it.
- The step changes to the Ready state when its prerequisites are satisfied. If so, z/OSMF creates a notification to inform the step owner that the step is now ready to be performed.
- If a step is in the Ready state and one of its prerequisite steps changes to an incomplete state, such as In Progress, z/OSMF resets the Ready step to Not Ready to indicate that a prerequisite is no longer satisfied.