List the software instances defined to z/OSMF

You can use this operation to obtain a list of the software instances that are defined to a z/OSMF instance.

HTTP method and URI path

GET /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:

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, then English is used.

Custom headers

None.

Request content

None.

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, to obtain a list of the software instances that are defined to a z/OSMF instance, the user ID initiating the request must have READ access to the z/OSMF Software Management task. 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.

If the request is successful, the response also includes the following JSON object: 
{
  "swilist":[
  {
    "name":"swi-name",
    "system":"system-nickname", 
    "description":"swi-description",
    "globalzone":"global-zone", 
    "targetzones":["target-zones"], 
    "categories":"["categories"],
    "productinforetrieved":"last-retrieved", 
    "lastmodified":"last-modified", 
    "modifiedby":"modified-user-ID", 
    "created":"date-created",
    "createdby":"created-user-ID", 
    "locked":"date-locked", 
    "lockedby":"locked-user-ID",
    "swiurl":"swi-URL"
  }
]}
where:
swilist
Array that contains each software instance that is defined to z/OSMF.
swi-name
Name of the software instance.
system-nickname
Nickname of the z/OSMF host system that has access to the volumes and data sets where the software instance resides. To obtain information about the specified system, you can use the z/OSMF topology services. For more details, see Topology services.
swi-description
Description of the software instance.
global-zone
CSI data set that contains the global zone used to manage the software.Start of change If the software instance has no global zone, then this property will be null.End of change
target-zones
Comma-separated list of the target zones included in the software instance.Start of change If the software instance has no global zone, then this property will be null.End of change
categories
Comma-separated list of the categories to which the software instance is assigned.
last-retrieved
Date and time the product, feature, and FMID information was last retrieved for the software instance. This attribute is blank if this information has not been retrieved.
last-modified
Date and time in ISO 8601 format that the software instance was last modified.
modified-user-ID
User ID of the user who last modified the software instance.
date-created
Date and time in ISO 8601 format that the software instance was created.
created-user-ID
User ID of the user who created the software instance.
date-locked
Date and time in ISO 8601 format that the software instance was locked. This attribute is null if the software instance is not currently locked.
locked-user-ID
User ID of the user who locked the software instance. This attribute is null if the software instance is not currently locked.
swi-URL
URL that allows you to access the software instance. For example, a client application can use the URL to read a software instance. For more details, see Retrieve the properties of a software instance.

Example

In the following example, the GET method is used to retrieve a list of the software instances that are defined to the z/OSMF instance that has a host name of zosmf1.yourco.com.
Figure 1. Sample request to retrieve a list of software instances
GET /zosmf/swmgmt/swi HTTP/1.1
Host: zosmf1.yourco.com
A sample response is shown in Figure 2.
Figure 2. Sample response from a request to retrieve a list of software instances
HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 05:39:28 +0000GMT
Content-Type: application/json
Content-Language: en
Connection: close

{"swilist":[
{"name":"DB2V9", "system":"PEV174", "description":null,
"globalzone":"DB2.GLOBAL.CSI", "targetzones":["DB2TGT"], "categories":null,
"productinforetrieved":"2014-08-20T19:23:25+00:00", "lastmodified":"2014-08-
20T19:23:25+00:00", "modifiedby":"FRED", "created":"2014-08-20T19:23:25+00:00",
"createdby":"BARNEY", "locked":null, "lockedby":null,
"swiurl":"https:\/\/zosmf1.yourco.com\/zosmf\/swmgt\/swi\/PEV174\/DB2V9"}
{"name":"zOSV2R1", "system":"PEV174", "description":null,
"globalzone":"ZOS.GLOBAL.CSI", "targetzones":["MVST100","MVST110"],
"categories":null, "productinforetrieved":"2014-08-20T19:23:25+00:00",
"lastmodified":"2014-08-20T19:23:25+00:00", "modifiedby":"WILMA",
"created":"2014-08-20T19:23:25+00:00", "createdby":"BETTY", "locked":null,
"lockedby":null,
"swiurl":"https:\/\/zosmf1.yourco.com\/zosmf\/swmgt\/swi\/PEV174\/zOSV2R1"}
]}
Parent topic: Software management services