Deploy a software instance

You can use the POST method to perform a deployment operation which will create a new software instance.

Currently this method has the following restrictions and limitations:

You can deploy a software instance only, not a portable software instance.
Target software instance data set names will exactly match the source software instance data set names. You cannot change data set names.
A new master catalog for the target software instance data sets will be created unconditionally.

HTTP method and URI path

POST /zosmf/swmgmt/dep

where:

zosmf/swmgmt: Identifies the software management services.
dep: Informs the service that the request is for a deployment.

Standard headers

Use the following standard HTTP header with this request:

Content-Type

Identifies the type of input content that is provided by the caller. The following value is acceptable:

Content-Type: application/json (JSON)

The JSON content type is used for the JSON document that is included as input with this request.

Accept-Language

Identifies the preferred language for any messages that are returned to the caller. The following values are acceptable:

Accept-Language: en (English)
Accept-Language: ja (Japanese)

If any other language value is specified or if the header is omitted, then English is used.

Custom headers

None.

Request content

{ 

"name":"deployment-name", 

"description":"deployment-description", 

"source":{ 

  "type":"swi", 

  "name":"name", 

  "system":"system-nickname" 

  }, 

"targetvolumes":[{ 

  "volume":"volume-serial", 

  "indirectcatalogsymbol":"volume-symbol" 

  }], 

"mastercatalog":{ 

  "name":"catalog-name", 

  "volume":"volume-serial", 

  "tempcatalias":"temporary-catalog-alias" 

  }, 

"jobstatement":["jcl-record"], 

"jcldataset":"data-set-name", 

"zosmfuid":"user-id",  

"zosmfpw":"password", 

"proxyuid":"user-id", 

"proxypw":"password" 

}

where:

name

The name for the Deployment object to be created in the SM db.

description

The description for the Deployment object. This value is optional.

source

Identifies the source software for the deployment operation. A copy of the specified software instance is the result of the deployment operation.

type: The type of source object for the deployment: software instance ("swi").

name: The name for the source software instance.

system: Nickname of the z/OSMF host system that has access to the volumes and data sets where the source software instance is. The z/OSMF host system is where the target software instance data sets are created. Use the nickname for the system definition in the z/OSMF Systems task.

targetvolumes

A list of target volumes. The target software instance data sets are created on these volumes. The number of input target volumes must be equal to or greater than the number of volumes on which the source software instance data sets reside.

name: The volume serial for a target volume.

indirectcatalogsymbol: If specified, this value indicates that target data sets are indirectly cataloged and is the symbol for the volume serial in the data set catalog entries. For example, "&SYSR1" or "******". This value is optional. The default behavior is to directly catalog all target data sets.

mastercatalog

Identifies the new master catalog to be created. All target software instance data sets are cataloged in this new catalog. The new catalog is an optional property. If not specified, the target software instance data sets are cataloged in the existing driving system catalog.

name: Name for the new master catalog.

volume: Volume serial where the new master catalog is created.

tempcatalias: The temporary catalog alias used to uniquely identify the data sets in the subject catalog from the z/OS driving system catalog. 1 - 8 characters and must follow data set name syntax.

jobstatement

List of JCL cards for the JOB statement to be used in the generated JCL for the deployment operation. The jobstatement is an optional property. If specified, it must be a list of JCL cards, each up to 72 characters long. Columns 1 and 2 of each record must be "//" or "/*" and the job name must be 1 - 8 characters. If no JOB statement is provided, the default is exactly "//IZUDnntt JOB (ACCOUNT),'NAME'" where "nntt" uniquely identifies the job sequence and type.

jcldataset

Partitioned data set to contain the generated deployment JCL. The data set name must comply with z/OS data set naming conventions.

zosmfuid

User ID for authenticating with a remote z/OSMF instance. This is an optional property.

zosmfpw

Password for authenticating with a remote z/OSMF instance. This is an optional property.

proxyuid

User ID for authenticating with an HTTP proxy. This is an optional property.

proxypw

Password for authenticating with an HTTP proxy. This is an optional property.

The request content is required, but some properties are optional. For example, if the software instance is not in the same sysplex as the primary z/OSMF instance, you might be required to authenticate with the secondary z/OSMF instance. This secondary z/OSMF instance is running in the sysplex where the software instance is. If the primary z/OSMF instance must use an HTTP proxy server to connect with the secondary z/OSMF instance, you might need to authenticate with that HTTP proxy server. Therefore, you may need to specify the remote z/OSMF user ID, password, and proxy user ID and password.

Required authorizations

Certain authorizations are required to submit a request through the software management services to deploy a software instance. The user ID that initiates the request requires the same authorizations as the user IDs that are needed to perform a deployment operation with the z/OSMF Software Management task.

The user ID needs the following:

READ access to the Software Management task.
READ access to the SAF resources that correspond to the source software instance.
CONTROL access to the SAF resources that correspond to the deployment object to be created.
CONTROL access to the SAF resources that correspond to the target software instance to be created.

For more information about access controls for the Software Management task, see Creating access controls for the Software Management task in IBM z/OS Management Facility Configuration Guide

Expected response

Deploying a software instance is an asynchronous operation. Therefore, on completion of the initial POST request, the z/OSMF Software Management REST interface returns an HTTP response code of 202 Accepted. It also returns a JSON document that contains a URL for the status monitor for the request. The client performs GET requests to the supplied URL to monitor the status of the operation and to obtain the result set.

{ 

  "statusurl":"url" 

}

where:

statusurl: Indicates the URL that provides status for the deployment request.

On subsequent GET requests to the status monitor URL:

If the operation is not yet complete, an HTTP response code of 200 OK is returned, along with a JSON document that contains status information for the operation.
If the operation is complete, then an HTTP response code of 200 OK is returned, along with a JSON document that contains status information and the desired result set.
If the request expires, then an HTTP response code of 404 Not found is returned. That is, when the operation is complete, the z/OSMF server holds the result set for a finite length of time. After that time passes, the result set is said to expire and is no longer available for the client to obtain.

The response to GET requests on the status monitor URL includes the following JSON document:

{ 

 "status":"status", 

 "percentcomplete":"percent", 

 "tgtswiname":"name", 

 "tgtswiurl":"swi-URL", 

 "jcl":["data-set-name(member-name)"], 

 "jobs":[{ 

   "jobname":"job-name", 

   "jobid":"job-id", 

   "retcode":"completion-code" 

   }], 

 "tgtswidatasets":[{ 

   "aliases":["alias"], 

   "catalog":"catalog-name", 

   "blksize":"block-size", 

   "dddefs":[{ 

     "dddef":"dddef-name", 

     "zone":"zone-name", 

     "path":"unix-directory" 

     }], 

   "dscategory":["data-set-category"], 

   "dsname":"data-set-name",   

   "dstype":"data-set-type", 

   "extents":"allocated-extents", 

   "extendedformat":true | false, 

   "lrecl":"logical-record-length", 

   "mountpoint":"unix-path", 

   "unixdirs":["unix-directory"], 

   "recfm":"record-format", 

   "storclas":"storage-class", 

   "tempcatalias":"temporary-catalog-alias", 

   "tracks":"allocated-tracks", 

   "used":"used-tracks-percent", 

   "volumes":["volume-serial"] 

   }] 

}

where:

status

The status of the deployment request. The status can be either "running" or "complete".

percentcomplete

The percentage of the processing that is complete for this deployment request, expressed as a whole number 0 - 100.

tgtswiname

Name for the target software instance created by the deployment operation. z/OSMF generates a name for the target software instance from the name of the source software instance, by appending a sequence number, like this: source-name_n where "n" is an integer. For example, if the source software instance name is zOS25, then the generated target software instance name is zOSV25_1. If a software instance with the generated name exists, then the sequence number is incremented until a unique name is generated. For example, zOSV25_2, zOSV25_3.

tgtswiurl

URL that allows you to access the target software instance. For example, a client application can use the URL to read a software instance or list the data sets in the target software instance.

jcl

Ordered list of generated JCL (jobs) for the deployment operation. Each job is a unique member in the JCL data set. The values are fully qualified data set and member names of the form "data-set-name(member-name)".

jobs

Ordered list of batch jobs submitted for the deployment operation.

jobname: Job name.
jobid: Job ID.
retcode: Job completion code.

tgtswidatasets

The list of data sets in the target software instance created by the deployment operation.

aliases

A list of alias names for the data set.

catalog

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

blksize

The data set block size.

dddefs

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

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

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.

dsname

The data set name.

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.

extents

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

extendedformat

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

lrecl

Data set logical record length.

mountpoint

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

unixdirs

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

recfm

Data set record format.

storclas

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

tempcatalias

When you create an alternative master catalog, tempcatalias is the temporary catalog alias that is 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: tempcatalias.dsname.

The tempcatalias is null if a data set is cataloged in the new alternate master catalog indirectly, which means it uses a volume symbol instead of a specific volume serial. The tempcatalias is also null if it is not cataloged at all. Such data sets cannot be referenced by name from the driving system catalog. They must be referenced by using the volume instead.

If you are not creating an alternate master catalog, then temptations is null.

tracks

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

used

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.

volumes

The list of volume serials where the data set resides.

Example

In the following example, the POST method is used to create a new software instance by deploying software instance zos24 on system SYS123.

Figure 1. Sample request to retrieve a list of portable software instances

POST /zosmf/swmgmt/dep HTTP/1.1 

Host: sys123.yourco.com 

Content-Type: application/json 

Accept-Language: en 

{ 

"name":"zos24Deploy", 

"source":{"type":"swi","name":"zos24"}, 

"system":"SYS123", 

"targetvolumes":[{"volume":"LT1234"},{"volume":"LT5678"}], 

"mastercatalog":{"name":"CATALOG.ZOS24.MCAT","volume":"LT12345", 

"tempcatalias":"ZOS24"}, 

"jobstatement":["//JOBNAME   JOB (123456),'USER',NOTIFY=&SYSUID,REGION=0M,", 

"// MSGCLAS=H","//*"] 

}

The response indicates that the deployment request is accepted and provides the URL to use for monitoring the status.

HTTP/1.1 202 Accepted 

Date: Tues, 21 April 2021 18:53:04 +00005GMT 

Content-Type: application/json 

Content-Language: en 

Connection: close 

{"statusurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/statusmonitor\/deployment\/4837290198343"}

To check the status of the list deployment request, submit the following request:

GET /zosmf/swmgmt/statusmonitor/deployment/4837290198343 HTTP/1.1 

Host: sys123.yourco.com

A sample response:

HTTP/1.1 200 OK 

Date: Tues, 21 April 2021 18:53:19 +00005GMT 

Content-Type: application/json 

Content-Language: en 

Connection: close 

{"status":"running", "percentcomplete":"65"}

The response indicates the operation to deploy the software instance is still running and 65% complete. A final request to the status monitor URL is as follows:

GET /zosmf/swmgmt/statusmonitor/deployment/4837290198343 HTTP/1.1 

Host: sys123.yourco.com

A sample response is as follows:

HTTP/1.1 200 OK 

Date: Tues, 21 April 2021 18:53:27 +00005GMT 

Content-Type: application/json 

Content-Language: en 

Connection: close 

{"status":"complete", "percentcomplete":"100", 

"swiname":"zos24_1", 

"swiurl":"https:\/\/zosmf1.yourco.com\/zosmf\/swmgt\/swi\/SYS123\/zos24_1", 

"jcl":["IBMUSR.SMJCL.CNTL(IZUD01CP)", 

"IBMUSR.SMJCL.CNTL(IZUD02RN)", 

"IBMUSR.SMJCL.CNTL(IZUD03UC)"], 

"jobs":[{"jobname":"IZUD01CP","jobid":"JOB12345","retcode":"CC 0"}, 

{"jobname":"IZUD02RN","jobid":"JOB12347","retcode":"CC 0"}, 

{"jobname":"IZUD03UC","jobid":"JOB12349","retcode":"CC 0"}], 

"tgtswidatasets": [
        {
            "aliases": [
                "ZOS24.IBMUSR.SWI.AMACLIB"
            ],
            "catalog": "CATALOG.ZOS24.MCAT",
            "blksize": "32720",
            "dddefs": [
                {
                    "dddef": "AMACLIB",
                    "zone": "DLIB"
                },
                {
                    "dddef": "AMACLIB",
                    "zone": "TGT"
                }
            ],
            "dscategory": [
                "DLIB"
            ],
            "dsname": "IBMUSR.SWI.AMACLIB",
            "dstype": "PDSE",
            "extents": "1",
            "extendedformat": false,
            "lrecl": "80",
            "mountpoint": null,
            "unixdirs": null,
            "recfm": "FB",
            "storclas": null,
            "tempcatalias": "ZOS24",
            "tracks": "1",
            "used": "50",
            "volumes": [
                "LT1234"
            ]
        },
        {
            "aliases": [
                "ZOS24.IBMUSR.SWI.CSI"
            ],
            "catalog": "CATALOG.ZOS24.MCAT",
            "blksize": null,
            "dddefs": null,
            "dscategory": [
                "DLIB",
                "GLOBAL",
                "SMP"
            ],
            "dsname": "IBMUSR.SWI.CSI",
            "dstype": "VSAM",
            "extents": null,
            "extendedformat": false,
            "lrecl": null,
            "mountpoint": null,
            "unixdirs": null,
            "recfm": null,
            "storclas": null,
            "tempcatalias": "ZOS24",
            "tracks": "76",
            "used": null,
            "volumes": [
                "LT1234"
            ]
        },
       { ... list of remaining data sets ...}
    ]
}

Processing

The Software Management Deployment REST API does the following:

Validate the request content is of proper form and syntax.
Verify that the source software instance exists.
Create a new deployment using the name provided in the input. No categories are assigned to the deployment.
Analyze the source software instance to get the list of data sets and determine the number of volumes on which the source data sets reside.
Ensure that the number of input target volumes is equal to or greater than the number of source volumes.
Create the deployment configuration:
1. The zone names in the target software instance will match the zone names in the source software instance.
2. The target data set names will match the source data set names.
3. Target volumes are selected from the list of input target volumes. Each source volume corresponds to one target volume.
4. The new master catalog name, volume, and temporary catalog alias are provided in the input. All target data sets will be cataloged in this new master catalog.
Verify the target software instance described by the configuration can be created; make sure there are no unintended data set collisions on target volumes, and ensure the temporary catalog alias is not already defined in the driving system catalog.
Generate the deployment JCL.
Submit the deployment JCL, in sequence, one job at a time, ensuring an acceptable condition code before the next job is submitted. Exception: The RACF job is NOT submitted. It is overridden complete.
After all jobs have run successfully, the target software instance is created using a name generated from the source software instance name with an appended sequence number to ensure uniqueness. Categories from the source software instance, if any, are also added to the target software instance definition.
Get the list of target software instance data sets and prepare the response content.