Load the products, features, and FMIDs for a software instance

You can use this operation to analyze the SMP/E global zone and target zones for a software instance to identify the installed products, features, and FMIDs in the instance, and to load that information into the z/OSMF Software Management task database.

HTTP method and URI path

PUT /zosmf/swmgmt/swi/<system-nickname>/<swi-name>/products

where:

zosmf/swmgmt identifies the software management services.
swi informs the service that the request is for the software instance object.
<system-nickname>/<swi-name> further qualifies the request and indicates the specific software instance to be retrieved. A software instance is uniquely identified by its name (swi-name) and the nickname (system-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.
products indicates that the products, features, and FMIDs included in the software instance are to be obtained and loaded into the Software Management task database.

When you issue this request, z/OSMF searches the SMP/E global zone and target zones associated with the software instance and gathers information about the software instance and its products, features, and FMIDs. z/OSMF returns this information in a JSON object, and stores this information in the Software Management task database.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: Identifies the type of input content provided by the caller. Use the JSON content type ("Content-Type: application/json") if a JSON document is 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

If the software instance does not reside in the same sysplex as the primary z/OSMF instance, you might be required to authenticate with the secondary z/OSMF instance that is running in the sysplex where the software instance resides. In addition, if the primary z/OSMF instance must navigate an HTTP proxy server to connect with the secondary z/OSMF instance, you might also be required to authenticate with that HTTP proxy server. To do so, include the following JSON object in your request:

Figure 1. Request content to authenticate with a secondary z/OSMF instance and an HTTP proxy server

{
  "zosmfuid":"zosmf-user-ID",
  "zosmfpw":"zosmf-password",
  "proxyuid":"proxy-user-ID", 
  "proxypw":"proxy-password" 
}

where:

zosmf-user-ID: User ID for authenticating with the secondary z/OSMF instance.
zosmf-password: Password for authenticating with the secondary z/OSMF instance.
proxy-user-ID: User ID for authenticating with the HTTP proxy server.
proxy-password: Password for authenticating with the HTTP proxy server.

Include the JSON object in the request only if you are required to authenticate with a secondary z/OSMF instance or an HTTP proxy server. Otherwise, omit the JSON object.

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 retrieve the product, feature, and FMID information, the user ID must have READ access to the Software Management task and UPDATE access to the SAF resources for the software instance being updated. 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 was accepted. If the request was accepted, the service returns status code 202 Accepted and a JSON object that contains a URL ({"statusurl":"url"}). To monitor the status of the retrieve product, feature, and FMID information request and to obtain the results, perform GET requests to the supplied URL. Only the user ID that initiates the retrieve product, feature, and FMID information request is authorized to check the status and obtain the results. One of the following responses is returned from the get status request:

If the retrieve product, feature, and FMID information request is still in progress, an HTTP response code of 200 OK is returned, along with the following JSON object: {"status":"status"}.
If the retrieve product, feature, and FMID information request is complete, an HTTP response code of 200 OK is returned, along with the following JSON object:
```
{
  "status":"status",
  "swi":{
    "name":"swi-name",
    "system":"system-nickname",
    "description":"swi-description"
    "globalzone":"global-zone-name",
    "targetzones":["target-zone-name"],
    "categories":["category-name"],
    "productinforetrieved":"date-retrieved",
    "lastmodified":"date-modified",
    "modifiedby":"modified-user-ID",
    "created":"date-created",
    "createdby":"created-user-ID",
    "locked":"date-locked",
    "lockedby":"locked-user-ID",
    "datasets":[{
      "dsname":"data-set-name",
      "volume":"volume-serial"
    }],
    "products":[{
      "prodname":"product-name",
      "prodid":"product-ID",
      "release":"version-release-modification",
      "vendor":"vendor-name",
      "generalavailability":"general-availability-date",
      "endofservice":"end-of-service-date",
      "url":"product-URL",
      "productinfofileversion":"product-file-version",
      "features":[{
        "feature":"feature-name",
        "fmids":[{
          "fmid":"fmid-name",
          "description":"fmid-description",
          "targetzones":["fmid-target-zone-name"]
        }]
      }]
    }]    
  }
}
```
where:
status

Status of the retrieve product, feature, and FMID information request. The status is either running or complete.

swi

JSON object to describe a software instance.

swi-name

Name of the software instance.

system-nickname

Nickname of the z/OSMF host system that has access to the global zone CSI data set included in the software instance. 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-name

Name of the CSI data set that contains the global zone used to manage the software.

target-zone-name

Array of the target zones in the specified global zone that describe the software.

category-name

Array of the categories to which the software instance is assigned.

date-retrieved

Date and time in ISO 8601 format that the product, feature, and FMID information for the software instance was last retrieved from the CSI data set. For example, 2014-08-20T19:23:25+00:00Z.

date-modified

Date and time in ISO 8601 format that the software instance was last modified. For example, 2014-08-20T19:23:25+00:00Z.

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. For example, 2014-08-20T19:23:25+00:00Z.

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 for an impending update. For example, 2014-08-20T19:23:25+00:00Z. If null, the software instance is not locked.

locked-user-ID

User ID of the user who locked the software instance.

datasets

Array of the non-SMP/E managed data sets that are included in the software instance.

data-set-name

Name of the data set.

volume-serial

Volume serial for the volume where the data set resides.

products

Array of the products included in the software instance.

product-name

Name of the product.

product-ID

Identifier for the product.

version-release-modification

Version, release, and modification level of the product. The value has the format VV.RR.MM, where VV is the two-digit version, RR is the two-digit release, and MM is the two-digit modification level.

vendor-name

Name of the vendor that provides the product.

general-availability-date

Date and time in ISO 8601 format that a version or release of the product became available to all users. For example, 2014-08-20T19:23:25+00:00Z.

end-of-service-date

Date and time in ISO 8601 format that service support ends for the product. For example, 2014-08-20T19:23:25+00:00Z.

product-URL

URL that links to additional information about the product. This information can include, for example, product life cycle dates, product highlights, planning information, and technical descriptions.

product-file-version

Version of the most recent product information file that supplied information about the product. The version represents the date and time in ISO 8601 format that file was created or last updated. For example, 2014-08-20T19:23:25+00:00Z.

features

Array of the features contained in the software instance.

feature-name

Name of the feature.

fmids

Array of the FMIDs contained in the software instance.

fmid-name

Name of the FMID.

fmid-description

Description of the FMID.

fmid-target-zone-name

Array of the target zones where the FMID is installed.
If the retrieve product, feature, and FMID information request is complete but the results are no longer available, an HTTP response code of 404 Not found is returned. z/OSMF makes the results available for a client application for a finite period of time. When that time elapses, the results are no longer available; in which case, the client must reissue the request.
If the identified software instance has no global zone property, then products, features, and FMIDs cannot be loaded for this software instance. If such a software instance is the target of such a request, an HTTP response code 400 (Bad request) with reason code 41 will be returned (The request cannot be performed because the software instance does not have a global zone.).

If the retrieve product, feature, and FMID information request cannot be processed, a status code of 4nn or 5nn is returned, indicating that an error has occurred. For more details, see Error handling.

Example

In the following example, the PUT method is used to retrieve the product, feature, and FMID information for software instance DB2V9 on system SYS123.

Figure 2. Sample request to retrieve the product, feature, and FMID information for a software instance

PUT /zosmf/swmgmt/swi/SYS123/DB2V9/products HTTP/1.1
Host: sys123.yourco.com

Figure 3 provides a sample response, indicating that the retrieve product, feature, and FMID information request has been accepted and supplying the URL to use for monitoring the status of that request.

Figure 3. Sample response for a retrieve product, feature, and FMID information request

HTTP/1.1 202 Accepted
Date: Tues, 21 November 2014 18:53:04 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"statusurl":"https:\/\/sys123.yourco.com\/zosmf\/swmgt\/statusmonitor\/prodload
\/4837290198343"}

To check the status of the retrieve product, feature, and FMID information request, submit the following request:

Figure 4. Sample request to obtain the status of a retrieve product, feature, and FMID information request

GET /zosmf/swmgmt/statusmonitor/prodload/4837290198343 HTTP/1.1
Host: sys123.yourco.com

Figure 5 provides a sample get status response, indicating that the retrieve product, feature, and FMID information request is in progress.

Figure 5. Sample get status response when the retrieve product, feature, and FMID information request is in progress

HTTP/1.1 200 OK
Date: Tues, 21 November 2014 18:53:19 +00005GMT
Content-Type: application/json
Content-Language: en
Connection: close
{"status":"running"}

Figure 6 provides a sample get status response, indicating that the retrieve product, feature, and FMID information request is complete.

Figure 6. Sample get status response when the retrieve product, feature, and FMID information request is complete

HTTP/1.1 200 OK
Date: Tues, 21 November 2014 18:53:36 +00006GMT
Content-Type: application/json
Content-Language: en
Connection: close
{
"status":"complete", "swi":{
"name":"DB2V9", "system":"PEV174", "description":null,
"globalzone":"DB2.GLOBAL.CSI", "targetzones":["DB2TGT"], "categories":null,
"productinforetrieved":"2014-08-20T19:23:25Z", "lastmodified":"2014-08-
20T19:23:25Z", "modifiedby":"FRED", "created":"2014-08-20T19:23:25Z",
"createdby":"BARNEY", "locked":null, "lockedby":null, "datasets":
[{"dsname":"USER.DB2V9.PROCLIB", "volume": "LV1234"},
{"dsname":"USER.DB2V9.SAMPLES", "volume":"LV1234"}], "products":
[{"prodname":"DB2 for z/OS", "prodid":"5635-DB2", "release":"09.01.00",
"vendor":"IBM", "generalavailability":"20006-06-09T19:23:25Z",
"endofservice":"2014-06-27T19:23:25Z", "url":null,
"productinfofileversion":"2014-01-01", "features":[{"feature":"DB2 Base",
"fmids":[{"fmid":"HDB9910", "description":"DB2 BASE/TSO", "targetzones":
["DB2V9T"]}]}]}
}