Specifying the workflow metadata

Use the workflow metadata element (<workflowInfo>) to specify information about the workflow, such as the workflow identifier, description, version, and vendor, and possibly other details. The Workflows task displays the metadata information 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.

At a minimum, you must specify the following metadata elements for a workflow:

workflowID: A short, arbitrary value that identifies the workflow.
This element can include the optional attributes scope and isCallable. For information, see Workflow scope and Callable workflows.
workflowDescription: A short description of the workflow.
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: The version of the workflow definition.
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: The name of the workflow provider.

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

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

Figure 1. General metadata for a workflow

<workflowInfo>
	<workflowID scope="system" isCallable="system">SampleWorkflow</workflowID>
	<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. In some cases, however, 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

Start of change 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. End of change

Start of change 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/>. End of change

Start of change 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. End of change

The following example shows the metadata for a Configuration workflow:

<workflowInfo>
        <workflowID>Productx-01</workflowID>
        <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.