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"
  }]
  Start of change"products":[{
    "prodname":"product-name",
    "prodid":"product-id", 
    "release":"product-level",
    "vendor":"vendor-name",
    "url":"product-url",
    "features":["feature-name"],    
    "generalavailability":"general-availability-date",
    "endofservice":"end-of-service-date"
    }],End of change
}
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).
Start of changeproductsEnd of change
Start of changeList of products for the software instance that are not managed by SMP/E. This list is optional.End of change
Start of changeproduct-nameEnd of change
Start of changeName of the product, but can be up to 64 characters.End of change
Start of changeproduct-IDEnd of change
Start of changeIdentifier for the product, but can be up to 64 characters.End of change
Start of changeproduct-levelEnd of change
Start of changeRelease level for the product, but can be up to 64 characters.End of change
Start of changevendor-nameEnd of change
Start of changeName of the vendor that provides the product, but can be up to 64 characters.End of change
Start of changeproduct-URLEnd of change
Start of changeA URL that links to additional information about the product, but can be up to 256 characters.End of change
Start of changefeature-nameEnd of change
Start of changeList of names of features for the product, but can be up to 64 characters.End of change
Start of changegeneral-availability-dateEnd of change
Start of changeDate this level of the product is available to all users. May be null,or a date value, in ISO 8601 format, yyyy-mm-ddThh:mm:ssZ.End of change
Start of changeend-of-service-dateEnd of change
Start of changeLast date on which the vendor will deliver standard support services for this level of the product. This date is the general end of service date. It does not account for lifecycle extensions. Can be any of the following:
null
The end of service date is unknown for the product.
yyyy-mm-ddThh:mm:ssZ
The known end of service date, in ISO 8601 format.
NotAnnounced
The end of service date is not yet announced for the product.
End of change

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.

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.).

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.).

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.).

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.)

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"}]
}
Parent topic: Software management services