Specifying the workflow metadata

Use the workflow information element (<workflowInfo>) to specify metadata for the workflow, such as the workflow identifier, description, version, and vendor, and possibly other details. The Workflows task displays the metadata to users in the Workflows table and the Properties for workflow page. Users can use the metadata values for filtering or configuring the workflows view.

The workflow information element is required.

You can specify the following sub-elements for the workflow information element:

parallelSteps

For a workflow with automated steps, this property indicates whether the automated steps can be run in parallel (concurrently), thus possibly completing more quickly. For a parallel-steps workflow, set this property to true. Otherwise, if this property is omitted or set to false, automated steps are run one-by-one in the sequence in which they appear in the workflow, starting from the top of the workflow definition.

workflowID

Short, arbitrary value that identifies the workflow. This element is required.

This element can include the optional attributes scope and isCallable. For more information, see Workflow scope and Callable workflows.

workflowDefaultName

Default name for the workflow. The default name is shown in the Workflow name field of the Workflows task when a user creates the workflow. The user can accept this name, or specify a different name.

The workflow name:

Must be unique in the Workflows task.
Can contain up to 100 characters. Leading and trailing white space is ignored.
Must not contain the characters for ampersand ('&'), forward slash ('/'), logical or ('|'), greater than ('>'), or less than ('<').

The workflow name is not case-sensitive; for example: MyWorkflow and MYWORKFLOW are the same workflow.

This element is optional. If you omit it, the Workflows task assigns a name to the workflow, based on the following convention:

<workflow-description> – Workflow_<number>

where:

workflow-description is the description from the workflow definition file
number is the first available number, beginning at 0. If you later delete this workflow, its number can be reused by the Workflows task.

workflowDescription

Short description of the workflow. This element is required.

When a workflow is imported into z/OSMF, the Workflows task uses the workflow description (specified in the <workflowDescription> tag) to create a default workflow name, which the user can change.

workflowVersion

Version of the workflow definition. This element is required.

The Workflows task caches only the latest version of any imported workflow definition file. Therefore, to ensure that the most current version is used, you must update the version value whenever you change any portion of the workflow definition. This includes changes to the primary XML file or any sub-files or referenced files. For this reason, when you author a workflow definition, you might want to complete the development phase on a workstation before you import the workflow definition into the Workflows task.

vendor

Name of the workflow provider. This element is required.

Table 2 describes the elements that make up the workflow metadata.

Figure 1 shows an example of the metadata XML tags for a workflow.

Figure 1. General metadata for a workflow


<workflowInfo>
   <parallelSteps>true</parallelSteps>
   <workflowID scope="system" isCallable="system">SampleWorkflow</workflowID>
   <workflowDefaultName>WORKFLOW#001</workflowDefaultName>
   <workflowDescription>A simple workflow</workflowDescription>
   <workflowVersion>1.0</workflowVersion>
   <vendor>XYZ, Inc.</vendor>   
   <General/> <!-- This element is empty, and completely optional. -->
</workflowInfo>

Workflow scope

It is possible to have multiple instances of a workflow run at the same time, on the same system or sysplex. However, in some cases you might need to restrict a workflow to one instance only, which can be useful for coordinating actions across a system or sysplex. In z/OSMF workflows, this concept is referred to as the singleton scope for the workflow.

To set the singleton scope for a workflow, specify the optional attribute scope on the workflow metadata element (<workflowInfo>). Specify the scope attribute with one of the following values:

system: A maximum of one instance of this workflow can exist on any one system in the sysplex.
sysplex: A maximum of one instance of this workflow can exist in the sysplex.
none: No limit exists for the number of instances of this workflow. For a callable workflow, this setting means that a new instance is always created on the calling system.

Workflow scope has ramifications for callable workflows. You might, for example, determine that a new instance of the workflow should always be created in response to a calling workflow. Or, you might prefer to have an existing instance of a workflow be used to handle the request. For considerations, see Coordinating workflow-to-workflow actions.

Callable workflows

In z/OSMF, a workflow can invoke another workflow for processing. A workflow that invokes another workflow is the calling workflow. A workflow that is invoked by another workflow is the called workflow.

To indicate whether a workflow is eligible to be called by another workflow, specify the optional attribute isCallable on the workflow metadata element (<workflowInfo>). On the isCallable attribute, also indicate the callable range for the workflow, that is, whether the workflow can be called only within the same system, or whether it can be called from any system in the same sysplex. Specify the isCallable attribute with one of the following values:

system: This workflow can be called only by another workflow that is running on the same system.
sysplex: This workflow can be called by any workflow that is running in the same sysplex.

If you omit the isCallable attribute, the workflow cannot be called by another workflow.

More information about callable workflows is provided in Calling steps.

Workflow category

In z/OSMF, a workflow category is a classification of the activities that are to be performed in a particular workflow. Workflows that are used to configure system software such as a product or component are Configuration workflows. Workflows that are used to provision system software, such as DB2 or IMS, are Provisioning workflows. All other workflows are General workflows.

The category is specified by the workflow author in the workflow definition file. The workflow category is optional. If no category is specified for the workflow, the workflow belongs to the General category. Figure 1 shows an example of how the workflow category is specified: <General/>.

For a Configuration workflow or a Provisioning workflow, the workflow metadata specifies product-specific details, such as the product name, product version, and product ID. The metadata for a Provisioning workflow also specifies the type of software to be provisioned (software type). The Workflows task presents this information to users in the Category Specific tab on the Properties for workflow page.

The following example shows the metadata for a Configuration workflow:

<workflowInfo>
        <workflowID>Productx-01</workflowID>
        <workflowDefaultName>WORKFLOW#001</workflowDefaultName>
        <workflowDescription>Initial configuration of Product X</workflowDescription>
        <workflowVersion>1.0</workflowVersion>
        <vendor>IBM</vendor>
        <Configuration>
                <productID>abc123</productID>
                <productName>Product X</productName>
                <productVersion>V1R99</productVersion>
        </Configuration>
</workflowInfo>

In this example, the metadata provides product-specific fields in the <workflowInfo> element, as follows:

productID: Identifier of the product or component that is being configured through the workflow, such as the product identifier (PID) or function modification identifier (FMID).
productName: Name of the product or component that is being configured through the workflow.
productVersion: Version and release of the product or component that is configured through the workflow.