Add a new software instance

You can use this operation to add a software instance to z/OSMF.

HTTP method and URI path

POST /zosmf/swmgmt/swi

where:

zosmf/swmgmt identifies the software management services.
swi informs the service that the request is for the software instance object.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: Identifies the type of input content provided by the caller. The JSON content type ("Content-Type: application/json") is used for the JSON document included as input with this request.
Accept-Language: Identifies the preferred language for messages that may be returned to the caller. Acceptable values are "Accept-Language: en" (English) and "Accept-Language: ja" (Japanese). Any other language value is ignored and English is used instead. In addition, if the header is not specified, English is used.

Custom headers

None.

Request content

Your request must include a JSON object that describes the software instance to be added, for example:

Figure 1. Adding a software instance: request content

{
  "name":"swi-name",
  "system":"system-nickname", 
  "description":"swi-description",
  "globalzone":"global-zone", 
  "targetzones":["target-zones"], 
  "categories":"["categories"],
  "datasets":[
  {
    "dsname":"data-set-name",
    "volume":"volume-serial"
  }]
  
}

where:

swi-name: Name of the software instance. The name can contain up to 30 non-blank characters, including alphanumeric characters (A-Z, a-z, and 0-9), mathematical symbols (< > - = | \), punctuation marks (? ! : ' " /), and special characters ($ _ # @ ^). The name is required and must be unique on the system.
system-nickname: Nickname of the system that has access to the volumes and data sets where the software instance resides. Use the nickname that is specified for the system definition in the z/OSMF Systems task. The nickname is required.
To manage the systems defined to z/OSMF, you can use the z/OSMF topology services. For more details, see Topology services.
swi-description: Description of the software instance. The description is optional and can contain a maximum of 256 characters.
global-zone: CSI data set that contains the global zone used to manage the software. If specified, must comply with z/OS data set naming conventions, and must end with .CSI.
target-zones: Comma-separated list of the target zones to be included in the software instance. A list of 0 or more zone names, each target zone name must be 1-7 characters long; the valid characters are uppercase alphabetic characters (A-Z), numeric characters (0-9), and special characters (@ # $). The first character must be an alphabetic character.
categories: Comma-separated list of the categories to which the software instance is assigned. Each category name can contain up to 30 non-blank characters, including alphanumeric characters (A-Z, a-z, and 0-9), mathematical symbols (< > - = | \), punctuation marks (? ! : ' " /), and special characters ($ _ # @ ^). Assigning the software instance to a category is optional.
datasets: Array that contains each non-SMP/E managed data set to be added to the software instance. Adding non-SMP/E managed data sets to the software instance is optional.
data-set-name: Name of the non-SMP/E managed data set. You cannot specify data set members or a subset of a data set. A data set name is required if you are adding non-SMP/E managed data sets to the software instance. The data set name must comply with z/OS data set naming conventions
volume-serial: Volume on which the non-SMP/E managed data set resides. The volume serial is required if the data set is not cataloged, and the volume must be accessible by the system where the software instance resides. The volume serial must be 6 characters long; the valid characters are uppercase alphabetic characters (A-Z) and numeric characters (0-9).

When adding a software instance, the software management REST interface validates the information that is supplied in the JSON object before completing the request. All input values must be valid and syntactically correct. If any errors are discovered, the add request fails and appropriate messages are returned.

Start of change The name and system, properties are required for every software instance. If either of these are not specified or are specified as null, then the request finishes with HTTP response code 400 (Badrequest) and reason code 4 (The required property {name|system} is missing. Add the missing property and retry the request.). End of change

Start of change If the globalzone property is specified, then the targetzones property is required. Therefore, if globalzone is specified and targetzones is not, then the request finishes with HTTP response code400 (Bad request) and reason code 4 (The required property {targetzones} is missing. Add the missing property and retry the request.). End of change

Start of change If the globalzone property is not specified, then the datasets property is required. That is, the software instance must contain either SMP/E managed software, or at least one non-SMP/Emanaged data set. Therefore, if both globalzone and datasets are not specified or are specified as null, then the request finishes with HTTP response code 400 (Bad request) and reason code 42 (Both of the properties {globalzone} and {datasets} are missing, but one is required. Add one or both of the missing properties and retry the request.). End of change

Start of change The targetzone property can only be specified if the globalzone property is also specified. Therefore, if targetzone is specified but globalzone is not, then the request finishes with HTTP response code 400 (Bad request) and reason code 43 (The {targetzone} property requires the{globalzone} property, but the {globalzone} property is missing. Either add the {globalzone}property or remove the {targetzone} property and retry the request.) End of change

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

To submit requests through the software management services, the user ID initiating the request requires the same authorizations as when performing an analogous operation using the z/OSMF Software Management task. That is, the user ID must have READ access to the Software Management task, and CONTROL access to the SAF resources corresponding to the software instance to be added. If the specified categories are implicitly added during this software instance add operation, the user ID must also have CONTROL access to the SAF resources corresponding to the specified categories. For information about access controls for the Software Management task, see IBM z/OS Management Facility Configuration Guide.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

Example

In the following example, the POST method is used to add a software instance to the z/OSMF instance that has a host name of pev174.yourco.com.

Figure 2. Sample request to add a software instance

POST /zosmf/swmgmt/swi HTTP/1.1
Host: pev174.yourco.com

Content-Type: application/json
Accept-Language: en
{
  "name":"DB2V9", 
  "system":"PEV174", 
  "description":"DB2",
  "globalzone":"DB2.GLOBAL.CSI", 
  "targetzones":["DB2TGT"], 
  "datasets":[
  {"dsname":"USER.DB2V9.PROCLIB","volume": "LV1234"},
  {"dsname":"USER.DB2V9.SAMPLES","volume":"LV1234"}]
}