Add a new portable software instance

HTTP method and URI path

POST /zosmf/swmgmt/pswi

zosmf/swmgmt

Identifies the software management services.

pswi

Informs the service that the request is for a portable software instance object.

Standard headers

Custom headers

None.

Request content

{
"name":"pswi-name",
"system":"system-nickname",
"description":"pswi-description",
"directory":"UNIX-directory",
"categories":["pswi-category"],
"signaturekeyring":"keyring-name",
"zosmfuid":"zosmf-user-ID",
"zosmfpw":"zosmf-password",
"proxyuid":"proxy-user-ID",
"proxypw":"proxy-password"
}

pswi-name

Name of the portable software instance. The name is required and must be unique on the system. The name can contain up to 30 non-blank characters, including the following alphanumeric characters, mathematical symbols, punctuation marks, and special characters: 0-9 A-Z a-z ! " # $ ' - / : < = > ? | @ \ ^ _

system-nickname

Nickname of the system that has access to the volumes and data sets where the portable software instance is located. Use the nickname that is specified for the system definition in the z/OSMF Systems task. The nickname is required.

To manage the systems that are defined to z/OSMF, you can use the z/OSMF topology services. For more information, see Topology services.

pswi-description

Description of the portable software instance. The description can contain a maximum of 256 characters.

UNIX-directory

UNIX directory to contain the files for the portable software instance. Ensure that the directory name is valid according to the following UNIX directory name syntax:

• Must be an absolute path name.
• Must start and end with a forward slash.
• Can contain up to 1023 characters.

pswi-category

Comma-separated list of the categories to which the portable software instance is assigned. Each category name can contain up to 30 non-blank characters, including the following alphanumeric characters, mathematical symbols, punctuation marks, and special characters: 0-9 A-Z a-z ! " # $ ' - / : < = > ? | @ \ ^ _

signaturekeyring

Identifies the location of the Certificate Authority (CA) certificate that is required to validate the digital signature of the portable software instance. The name for a security manager keyring or the keyword javatruststore may be specified.

keyring-name

Identifies the name for a security manager keyring. The specified name may be for a real or virtual keyring. Keyring names are from 1 to 237 characters in length and may include only characters X'40' through X'FE' excluding the forward slash (/), and the reserved XML characters, less than (<), greater than (>), double quotation mark ("), and ampersand (&).

If the keyring is associated with a userid other than the one that is used to perform the action, then the keyring name must be prefixed with the associated userid. Userids are from 1 to 8 alphanumeric characters in length, and can consist entirely of numerics and need not begin with any particular character. The userid is separated from the keyring value by a forward slash (userid/keyring).

To indicate that all of the Certificate Authority (CA) certificates that are defined in the security manager may be used to validate the digital signature, use the CERTAUTH virtual keyring by specifying the userid/keyring value “*AUTH*/*”.

Note:

The userid that performs the action must be properly authorized to the FACILITY class resource IRR.DIGTCERT.LISTRING or to the RDATALIB class resource keyring-owner.keyring-name.LST for z/OSMF to use the specified keyring. READ access is required for a userid to use its own keyring or the CERTAUTH virtual keyring. UPDATE access is required to use a keyring from another user. If the RDATALIB class is used, for any real keyring, READ access to keyring-owner.keyring-name.LST is required. For the CERTAUTH virtual keyring, READ access to CERTIFAUTH.IRR_VIRTUAL_KEYRING.LST is required.

javatruststore

Indicates that all of the certificates in the default Java truststore may be used to validate the digital signature. A Java truststore is a Java keystore file that contains the collection of the trusted Certificate Authority (CA) certificates. The default Java truststore is located relative to the Java home directory.

zosmf-user-ID

User ID for authenticating with a remote z/OSMF instance.

zosmf-password

Password for authenticating with a remote z/OSMF instance.

proxy-user-ID

User ID for authenticating with an HTTP proxy.

proxy-password

Password for authenticating with an HTTP proxy.

The request content is required, but some properties are optional. For example, consider whether the UNIX directory is not in the same sysplex as the primary z/OSMF instance. You might need to authenticate with the secondary z/OSMF instance that is running in the sysplex where the source software instance is located. In addition, consider whether the primary z/OSMF instance must access an HTTP proxy server to connect with the secondary z/OSMF instance. You might also need to authenticate with that HTTP proxy server. Therefore, you might need to specify the remote z/OSMF user ID and password and the proxy user ID and password.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

Certain authorizations are required to submit a request through the software management services to add a portable software instance. The user ID that initiates the request requires the same authorizations as the ones needed to perform an add operation with the z/OSMF Software Management task. The user ID needs READ access to the Software Management task and CONTROL access to the SAF resources that correspond to the portable software instance to add. If the specified categories are implicitly added during this portable software instance add operation, the user ID must also have CONTROL access to the SAF resources that correspond to the specified categories. 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

{
 "statusurl":"url"
}

{
 "status":"status"
"packagesignercertdetails":{
    "subjectname":"subject-name",
    "serialnumber":"serial-number",
    "fingerprint":"finger-print",
    "issuer":"issuer-subject-name"
         }
}

Example

POST /zosmf/swmgmt/pswi HTTP/1.1
Host: pev174.yourco.com
Content-Type: application/json
{
"name":"Hooli",
"system":"PEV174",
"description":"Fictitious software product from Hooli",
"directory":"/u/ibmusr/hoolipswi/"
}

HTTP/1.1 202 Accepted
Date: Fri, 5 June 2020 18:53:04 +00004GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"statusurl":"https:\/\/pev174.yourco.com\/zosmf\/swmgt\/statusmonitor\/addpswi\/4837290198343"}

GET /zosmf/swmgmt/statusmonitor/addpswi/4837290198343 HTTP/1.1
Host: pev174.yourco.com

HTTP/1.1 200 OK
Date: Fri, 5 June 2020 18:54:04 +00004GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"status":"running"}

GET /zosmf/swmgmt/statusmonitor/addpswi/4837290198343 HTTP/1.1
Host: pev174.yourco.com

HTTP/1.1 200 OK
Date: Fri, 5 June 2020 18:55:04 +00004GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"status":"complete"}