Software Management workflow variables

You can use workflows in Software Management to perform setup and configuration tasks for a software instance. When a software instance is deployed, you can use workflows that are defined for the software instance to perform those setup and configuration tasks.

Software Management provides detailed properties about a software instance as well as the data sets and products that compose software instances. These properties are exposed to workflows as workflow variables.

Note: The support for the workflow variables is added with the PTFs for APAR PH09032.

The workflow variables that are created by Software Management for a software instance are shown as follows:

izud-varsversion = version
izud-created = yyyy-mm-ddThh:mm:ssZ
izud-createdby = user-id
izud-system = system-nickname
izud-fmids= ["fmid-name"]
izud-globalzone= csi-data-set-name
izud-zones= [{
  "izud-name":"zone-name",
  "izud-type":"zone-type",
  "izud-related":"related-zone-name",
  "izud-csi":"csi-data-set-name"
  }]
izud-datasets = [{
  "izud-aliases":["alias"],
  "izud-cataloged":true | false,
  "izud-catalog":"catalog.data.set.name",
  "izud-blksize":"block-size",
  "izud-dddefs":[{
    "izud-dddef":"dddef-name", 
    "izud-zone":"zone-name", 
    "izud-path":"unix-directory"
    }],
  "izud-dscategories":["data-set-category"],
  "izud-dsname":"dataSetName",
  "izud-dstype":"dataSetType",
  "izud-extents":"allocated-extents",
  "izud-extendedformat":true | false,
  "izud-lrecl":"logical-record-length",
  "izud-mountpoint":"UNIX-path",
  "izud-recfm":"record-format",
  "izud-storclas":"storage-class",
  "izud-tempcatalias":"temporary-catalog-alias",
  "izud-tracks":"allocated-tracks"
  "izud-unixdirs":["unix-directory"],
  "izud-used":"used-tracks-percent",
  "izud-volumes":["volser"],
  "provider-dataset-property-key":"provider-dataset-property-value"
  }]
 izud-catalogs = [{ 
  "izud-catname":"catalog-name",  
  "izud-cattype":"MASTER | USER",  
  "izud-catdsnprefixes":["data-set-name-prefix"], 
  "izud-tempcatalias":"temporary-catalog-alias",   
  "izud-tgtsyscattype":"MASTER | USER" 
  }] 
izud-products= [{
  "izud-eosdate":"yyyy-mm-ddThh:mm:ssZ" | "NotAnnounced"| "Unknown",
  "izud-features":[{
    "izud-featname":"feature-name",
    "izud-featid":"feature-id",
    "izud-fmids":["fmid-name"]
    }],
  "izud-gadate":"yyyy-mm-ddThh:mm:ssZ",
  "izud-prodname":"product-name",
  "izud-prodid":"product-id",
  "izud-prodinfoversion":"yyyy-mm-ddThh:mm:ssZ",
  "izud-prodsups":[{
    "izud-prodid":"product-id",
    "izud-release":"vv.rr.mm"
    }],
  "izud-release":"product-level",
  "izud-srels":["srel"],
  "izud-url":"product-url",
  "izud-vendor":"vendor-name",
  "provider-product-property-key":"provider-product-property-value"
}]

Where:

izud-varsversion

Indicates the version of the workflow variables that are defined by z/OSMF Software Management. izud-varsversion is an integer type variable. The version value can be:

The initial version of the variable set.

izud-created

Indicates the date and time when the workflow instance was created. izud-created is a string type variable.

izud-createdby

The user ID for the user that created the workflow instance. izud-createdby is a string type variable.

izud-system

The nickname of the z/OSMF host system where the software instance data sets reside. For Deployment Perform workflows, this is the target system of the deployment operation. izud-system is a string type variable.

izud-fmids

The list of FMIDs in the software instance. This includes all FMIDs associated with one or more products and features, as well as all FMIDs associated with no products or features. izud-fmids is an array type variable.

izud-globalzone

Indicates the name of the CSI data set that contains the global zone for the software instance. izud-globalzone is a string type variable.

izud-zones

Indicates the list of SMP/E zones for the software instance. izud-zones is an array type variable.

izud-name: Indicates the zone name.
izud-type: Indicates the type for the zone, global, target, or dlib.
izud-related: If the zone has a related zone, then this indicates the name of the zone's related zone.
izud-csi: Indicates the CSI data set name that contains the zone.

izud-datasets

The list of data sets in the software instance. izud-datasets is an array type variable.

izud-aliases

A list of alias names for the data set.

izud-cataloged

Indicates, true or false, whether the data set is cataloged. End of change

izud-catalog

For cataloged data sets, the name of the catalog that includes the data set. End of change

izud-blksize

The data set block size.

izud-dsname

The data set name.

izud-dstype

The type for the data set. Can be one of the following types:

HFS — Hierarchical file system.
PDS — Partitioned data set.
PDSE — Partitioned data set extended.
SEQ — Sequential data set.
VSAM — VSAM data set.
ZFS — zSeries file system.

izud-dscategory

List of categories for how the data set is used. Can be one or more of the following:

DLIB — SMP/E managed distribution library, or SMP/E control data set associated with a distribution zone.
GLOBAL — SMP/E control data set associated with the global zone.
SMP — SMP/E control data set.
SMPTLIB — SMPTLIB data sets associated with the global zone.
TARGET — SMP/E managed target library, or SMP/E control data set associated with a target zone.
WORKFLOW — Contains one or more workflow definition files for the workflows that are explicitly defined to the software instance.
OTHER — None of the above.

izud-volumes

The list of volume serials where the data set resides.

izud-storclas

The name of the storage class where the data set resides.

izud-tempcatalias

The name of the temporary catalog alias used to uniquely identify the data set from the z/OS driving system catalog. This value is the temporary catalog alias that is used for the alternate master catalog and is a data set name prefix to reference the data set from the driving system. To reference the data set from the driving system catalog, use a name that is constructed like this: izud-tempcatalias.izud-dsname.

If a data set is cataloged in the new alternate master catalog indirectly (using a volume symbol instead of a specific volume serial) or not cataloged at all, then the izud-tempcatalias value is null. Such data sets cannot be referenced by name from the driving system catalog. They must be referenced using the volume instead.

If not creating an alternate master catalog izud-tempcatalias is null.

izud-tracks

The number of 3390-device equivalent tracks (56664 bytes/track) allocated to the data set.

izud-dddefs

Indicates the list of SMP/E zones and DDDEF entries that reference the data set.

izud-dddef: Indicates the name of the DDDEF entry.
izud-zone: Indicates the name of an SMP/E zone that contains the DDDEF entry.
izud-path: Indicates the UNIX directory that is identified in the DDDEF entry.

izud-mountpoint

Indicates the mount point for the UNIX file system data set.

izud-unixdirs

A list of UNIX directories that reside in the subject data set and contain one or more workflow definition files for the software instance.

izud-extendedformat

Indicates, true or false, whether the data set is an extended format sequential data set.

izud-recfm

Data set record format.

izud-lrecl

Data set logical record length.

izud-used

Indicates the percentage of allocated tracks used, expressed in whole numbers, not rounded. If any track is used, the minimum percentage is 1. If the data set is a PDSE, the percentage refers to the percentage of allocated pages used.

izud-extents

The number of extents that are allocated to the data set.

provider-dataset-key and provider-dataset-property-value

A property key and its value that is defined by the provider of the software instance for the subject data set. Each property that is defined for the data set is represented as a unique key-value pair. See Add a new software instance for more information about the datasetproperties.

izud-catalogs

The list of catalogs where data sets in the software instance are cataloged. izud-catalogs is an array type variable.

izud-catname: Name of the catalog.
izud-cattype: Indicates the catalog type, MASTER or USER, from the z/OS driving system perspective. Note: When creating a new alternate master catalog, from the z/OS driving system the new alternate master catalog is a user catalog. It is a master catalog only to the z/OS target system after that system is IPLed.
izud-catdsnprefixes: A list of data set name prefixes for data sets cataloged in the subject catalog.
izud-tempcatalias: When creating an alternate master catalog, izud-tempcatalias indicates the temporary catalog alias that is used to uniquely identify the data sets in the subject catalog from the z/OS driving system catalog.; If not creating an alternate master catalog, or the saved configuration information does not match the actuals, then z/OSMF might not be able to determine the temporary catalog alias. Therefore, izud-tempcatalias will be null.
izud-tgtsyscattype: When creating an alternate master catalog, izud-tgtsyscattype indicates the intended catalog type for the subject catalog, MASTER or USER, from the z/OS target system perspective.; If not creating an alternate master catalog, or the saved configuration information does not match the actuals, then z/OSMF might not be able to determine the intended catalog type. Therefore, izud-tgtsyscattype will be null.

izud-products

The list of software products in the software instance. This list includes both SMP/E and non-SMP/E managed products. izud-products is an array type variable.

izud-prodname

The name for the product.

izud-prodid

The identifier for the product.

izud-release

The release level for the product.

izud-vendor

The name of the vendor that supplied the product.

izud-url

The URL that links to additional information about the product.

izud-srels

The SMP/E system or subsystem releases on which the product can be installed.

izud-prodsups

The list of products that are superseded by the subject product.

izud-prod-id: The identifier for the superseded product.
izud-release: The release level for the superseded product.

izud-features

The list of features for the product.

izud-featname: The name of the feature.
izud-featid: The identifier for the feature.
izud-fmids: The list of FMIDs for the feature.

izud-gadate

The date when the product became generally available.

izud-eosdate

The last date on which the vendor delivers standard support services for the product.

izud-prodinfoversion

The version for the most recent product information file that provided information for the subject product.

provider-product-key and provider-product-property-value

A property key and its value defined by the provider of the software instance for the subject software product. Each property defined for the product is represented as a unique key-value pair. See Add a new software instance for more information about the productproperties.

Provider Defined Properties

As a software provider you can define properties that are associated with individual data sets and products within a software instance. These properties are available to a workflow created by Software Management as workflow variable properties. These properties are merged with those defined by Software Management to describe the data sets and products within a software instance to create the workflow variables previously described.

Provider defined properties can be specified when you use the Software Management REST services to add or modify a software instance. Refer to the Add a new software instance and Modify software instance REST services to learn how to specify provider properties. Provider defined properties are merged with the Software Management defined properties to create workflow variables. These variables are made available to a workflow when Software Management creates a new workflow instance for the software instance.

Note: The support for provider defined properties is added with the PTFs for APAR PH11650.

Example

If a data set in a software instance must be APF authorized for the software to run properly, as the provider of the software, you can create a workflow to help your users ensure that the data set is APF authorized when the software instance is deployed. Your workflow needs to know which data sets in the software instance must be APF authorized, therefore, you can define a property for the subject data sets and the workflow can reference this property in the workflow variables.

When you define the software instance by using the REST service to add a new software instance, as described in Add a new software instance, specify a data set property by using datasetproperties in the request content like this:

Figure 1. Using the Add software instance REST API to specify a data set property in the request content

POST /zosmf/swmgmt/swi HTTP/1.1
Host: pev084.yourco.com
Content-Type: application/json
Accept-Language: en

{"swiname":"mySWI",
 "system":"PEV084",
 "globalzone":"JOHNDOE.GLOBAL.CSI",
 "targetzones":["TGTZ"],
 "datasetproperties":[
   {"dddefname":"ABCMOD", 
    "properties":[{"abc-ApfLst":"yes"}]}
   ]
}

In this example the data set that must be APF authorized is managed by SMP/E and is identified by a DDDEF entry named ABCMOD. A property with a key "abc-ApfLst" and value "yes" are defined for the subject data set.

When Software Management creates a workflow instance for the software instance, workflow variables are generated, which provides the workflow programmatic access to the information about the data sets in the software instance. The workflow variable izud-datasets is a generated array variable containing one entry for each data set in the software instance. The entry in the izud-datasets array for the subject data set will contain properties like this:

Figure 2. Sample entry in the list for the subject data set

izud-datasets = [
  ...
  {"izud-dsname":"ABC.ABCMOD",
  "izud-volumes":["LV1234"],
  "izud-dstype":"PDS",
  ...
  "abc-ApfLst":"yes"
  },
  ...
]

The data set property that you specified when you defined the software instance, abc-ApfLst, is set for the subject data set in the izud-datasets array entry. A template step in your workflow can analyze the entries in the izud-datasets array variable to determine which data sets in the software instance have this property, like this:

Figure 3. Sample template step to determine the specified property

<template>                                                           
<inlineTemplate substitution="true">                               
APF FORMAT(DYNAMIC)                                                      
## For each data set in the software instance,                           
## find the data sets that must be APF authorized.                       
##                                                                       
#foreach($dataset in ${instance-izud-datasets})                          
#if(${dataset.abc-ApfLst} == "yes")                                  
APF ADD DSNAME(${dataset.izud-dsname}) VOLUME(${dataset.izud-volumes[0]})
#end                                                                     
#end                                                                     
</inlineTemplate>                                                  
<saveAsDataset substitution="true">                                
${instance-izud-createdby}.PARMLIB(PROGXX)</saveAsDataset>       
</template>

This example workflow template step creates a PROGxx parmlib member snippet for the data sets with the abc-ApfLst property set to yes. Workflow template steps such as this can be created for many other actions.

Sample workflow definition

A sample workflow definition file named IZUDWFVR is provided in the SYS1.SAMPLIB data set. It demonstrates how to create a workflow that references the workflow variables that are defined by Software Management.