Enabling a workflow definition file for future upgrades
Over the course of time, you might want to provide users with a revised version of your workflow, presumably with enhanced functions. This topic describes the tags that you can use to make your workflow definition upgradeable.
In z/OSMF, to upgrade a workflow means to create a new instance of an existing workflow, based on a new definition file. As the workflow author, you can design your workflow definition to be upgradeable to future versions of the definition.
During an upgrade operation, the Workflows task user upgrades an existing workflow to a new level of the workflow by using the action Create New Based on Existing, which is provided in the Workflows table. By upgrading the workflow, the user creates a new instance of the workflow, while retaining data from the existing workflow.
Creating an upgradeable workflow definition
Using a set of tags in the Workflows schema, you can add an upgrade capability to your workflow definition. The tags specify which previous versions of the workflow are supported for upgrades. Also, the rules for data mapping, which variables, steps and attributes can be copied forward, and so.
To provide upgrade option in a workflow definition, you must provide a workflow definition with same workflowID as the current (old) version of the workflow definition.
To add an upgrade capability to your workflow definition, you define an upgrade element (<preserveOptions>) with the attributes described in this topic.
- Version. This element specifies information about the workflow
to be upgraded. It contains the following attributes:
- Value. Version of the workflow definition that is supported for upgrading. You must specify at least one prior version of the workflow definition.
- Type. Specify either patch or release, as follows:
- Patch indicates that the upgrade to is intended to fix a defect in the prior version of the workflow. Based on this idea, the new workflow replaces, rather than coexists, with the prior version. Thus, the prior version is canceled when the upgrade is performed.
- Release indicates that the upgrade creates a new release of the workflow. The prior version is retained, based on the assumption that some installations with multiple releases might choose to use more than one version of the workflow.
- Variable set (<variableSet>). This element specifies which variable values are to be copied from the existing workflow. On this element, you can optionally specify the attribute (<defaultChecked>). Setting it to true (the default) causes the option Copy attribute values based on upgrade definition in the Workflows task wizard Create New Based on Existing to be selected by default. If so, all of the variable values are copied to the upgraded workflow.
- Step set (<stepSet>). This element specifies the step values to be copied from the existing workflow. On this element, you can optionally specify the attribute (<defaultChecked>). Setting it to true (the default) causes the option Copy step attributes based on upgrade definition in the Workflows task wizard Create New Based on Existing to be selected by default. If so, all of the current workflow step attributes are copied to the upgraded workflow. The attributes include the step assignees, step owners, step states, notes, submitted job status, and the record of how variable conflicts, if any, were resolved.
- Workflow history (<workflowHistory>). This element specifies whether the workflow history is copied from the existing workflow to the new instance. On this element, you can optionally specify the attribute (<defaultChecked>). Setting it to true (the default), causes the option Copy workflow history in the Workflows task wizard Create New Based on Existing to be selected by default. Otherwise, the option is not selected.
- Workflow notes (<workflowNotes>). This element specifies whether workflow notes are copied from the existing workflow to the new instance. On this element, you can optionally specify the attribute (<defaultChecked>). Setting it to true (the default), causes the option Copy workflow notes in the Workflows task wizard Create New Based on Existing to be selected by default. Otherwise, the option is not selected.
- Include (<include>). Use this element to specify which steps or variables in the prior workflow definition file are copied to the new workflow. You can specify this element multiple times. Specify either a regular expression or a variable name.
- Exclude (<exclude>). Use this element to specify which steps or variables are excluded from the set that is generated by the <include> element.
- Upgrade notes (<upgradeNotes>). Use this element to provide the user with information about the upgraded workflow definition. For example, you might use this element to provide the user with details about using the workflow.
For descriptions and data types of these elements and attributes, see Workflow upgrade elements summary.
<include regExp="\w*"><include name="setting3"/><include name="setting1" mapTo="setting2"/>If you specify the <include> element multiple times in a sequence, and a variable is included for multiple times after calculation by name and regular expression, the last <include> specification is the one that is used for the copy operation.