Retrieve the z/OS system UUID

You can use this operation to retrieve the UUID for the software instance that represents the installed software for the specified z/OSMF host system.

A UUID (Universal Unique Identifier) is a 128-bit value that is used to uniquely identify an object. UUIDs are represented with 32 hexadecimal characters, 0 - 9 and A - F, with four hyphens, in this form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. For example, “bbc9e8d6-bd61-4f11-af48-ff500fffc178”. The UUID for the z/OS software instance is defined in module IZUSIUI in LPALIB. This module is created by z/OSMF during the installation or subsequent deployment of z/OS. The UUID can be discovered by this REST API, and then used by other z/OSMF Software Management REST APIs to perform actions on the software instance. The UUID can also be displayed by using the "D IPLINFO" MVS system command.

HTTP method and URI path

POST /zosmf/swmgmt/system/uuid/<system-nickname>
Where:
  • zosmf/swmgmt identifies the software management services.
  • system/uuid informs the service that the request is for obtaining a z/OS system’s software instance UUID.
  • <system-nickname> further qualifies the request and indicates the z/OSMF host system for which the software instance UUID is retrieved. This value is optional. If the system nickname is not specified, the UUID for the system that processes the REST API request is returned.

    To obtain information about the specified system, you can use the z/OSMF topology services. For more details, see Topology services.

When you issue this request, z/OSMF reads module IZUSIUI from LPA to obtain the UUID value recorded in the module. It then returns the UUID value to the caller.

Standard headers

Use the following standard HTTP header with this request:

Content-Type

Identifies the type of input content that is 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 can 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 identified z/OSMF host system is not the primary z/OSMF instance, you might be required to authenticate with the remote z/OSMF instance. In addition, if the primary z/OSMF instance must navigate an HTTP proxy server to connect with the remote 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: 
{ 

  "zosmfuid":"zosmf-user-ID", 

  "zosmfpw":"zosmf-password", 

  "proxyuid":"proxy-user-ID",  

  "proxypw":"proxy-password"  

}
Where:
zosmf-user-ID
User ID for authenticating with the remote z/OSMF instance.
zosmf-password

Password for authenticating with the remote 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 remote 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 retrieve the UUID for a z/OSMF host system, the user ID must have READ access to the Software Management task.

Expected response

On completion, the service returns an HTTP response, which includes a status code, which indicates 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: 
{ 

  “uuid”:”uuid-value” 

  “modid”:”modid-value”   

}
Where:
uuid-value

UUID for the software instance that corresponds with the installed software for the specified z/OSMF host system. The value can be null if no UUID is defined for the requested z/OSMF host system.

modid-value

Includes the UUID module name and assembly date. The value can be null if no UUID is defined for the requested z/OSMF host system.

Example

In the following example, the POST method is used to retrieve the UUID for system PEV174.
POST /zosmf/swmgmt/uuid/PEV174 HTTP/1.1 

Host: zosmf1.yourco.com
A sample response is shown in Figure 1.
Figure 1. Sample response from a request to retrieve the z/OS system UUID
HTTP/1.1 200 OK 

Date: Thu, 15 Jan 2023 05:39:28 +0000GMT 

Content-Type: application/json 

Content-Language: en 

Connection: close 

{ 

 “uuid”:”bbc9e8d6-bd61-4f11-af48-ff500fffc178” 

 “modid”:”IZUSIUI 2023.032 ”   

}