Multisystem routing services

Although your enterprise can have multiple active z/OSMF instances, it is recommended that you make one instance the primary. The primary z/OSMF instance is the instance that:

• Is the base for configuring the other z/OSMF instances in your enterprise.
• Generates the Lightweight Third Party Authentication (LTPA) key that is used for single sign-on (if single sign-on is enabled).
• Is used to perform all z/OS system management tasks in your enterprise, which ensures that the data for each z/OSMF task is centrally managed.
• Acts as the client for all hypertext transfer protocol (HTTP) requests and drives the transfer of files between z/OSMF instances.

To obtain information from System 6 in Sysplex B, the following actions are performed:

1. A client application sends an HTTPS request to the primary z/OSMF instance.
2. The primary z/OSMF instance routes the HTTPS request to the secondary z/OSMF instance in Sysplex B.
3. The secondary z/OSMF instance processes the request and sends an HTTPS response to the primary z/OSMF instance.
4. The primary z/OSMF instance returns the HTTPS response to the browser.
5. The client application parses the response and extracts the appropriate information.

The JSON content type ("Content-Type: application/json") is used for HTTP response data. The following JSON object is used by all multisystem routing services for returning data and status about the requested operations. The attributes provided in the JSON object depend on the requested operation.

{
 "primaryAPIVersion":"primary-API-version",
 "systemsOutput":
   {
     "systemOutput":"system-output",
     "rc":"return-code",
     "error":{"msgid":"message-ID","msgtxt":"message-text"},
     "secondaryApiVersion":"secondary-API-version",
     "systemVersion":"
       {
         "zosNode":"zos-node",
         "zosVrm":"zos-level",
         "zosSysplex:"sysplex-name"
       }",
     "systemName":"system-name"
   },
 "numOfSystems":"total-systems"
}

where:

primary-API-version

Version of the multisystem routing services interface for the primary z/OSMF instance.

systemsOutput

Contains a separate response for each system to which the HTTPS request was sent. If the request was sent to multiple systems, the systemsOutput attribute contains an array of system responses.

system-output

Contains the response returned for a single system. A separate systemOutput attribute is included for each system to which the HTTPS request was sent.

return-code

Code returned by the system. The return code can be one of the following values:

OK

Success.

HttpConnectionFailed

The HTTPS connection failed. Typically, this error occurs when the system hosting the secondary z/OSMF instance is unavailable, the z/OSMF instance is not running, or a network error has occurred.

HttpConnectionTimedOut

The HTTPS request did not complete in the time allotted.

CertificateError

The certificate for the secondary z/OSMF instance is not trusted.

LoginRequired

The Lightweight Third Party Authentication (LTPA) token is not valid or has expired. You must submit a separate HTTPS request to authenticate with the z/OSMF instance.

InvalidLogin

The login credentials for the z/OSMF instance are not valid.

ProxyLoginRequired

Authentication is required by the proxy server.

InvalidProxyLogin

The login credentials for the proxy server are not valid.

FailedWithMessage

The request was successful; however, an internal error occurred with the secondary z/OSMF instance.

UnexpectedFailure

An unexpected error occurred.

error

If an error occurred with the request, the error attribute contains the message ID (msgid) and message text (msgtxt) for the message that was issued. Otherwise, this attribute is null.

secondary-API-version

Version of the multisystem routing services interface for the secondary z/OSMF instance.

systemVersion

Provides additional information about the system, as follows:

zosNode

JES2 multi-access spool (MAS) member name or JES3 complex member name that is assigned to the primary job entry subsystem (JES) that is running on the system.

zosVrm

Version, release, and modification level of the z/OS image installed on the system. The level has the format vv.rr.mm, where vv is the version, rr is the release, and mm is the modification level. You can correlate the returned value as follows:

• 04.24.00 indicates z/OS V2R1

zosSysplex

Name of the sysplex where the z/OS® system is a member. The name is the value specified for the SYSPLEX parameter of the cross-system coupling facility (XCF) couple data set format utility.

system-name

Unique name assigned to the system definition.

total-systems

Number of systems to which an HTTPS request was sent.

The following HTTP status codes are valid:

HTTP 200 OK

Success.

HTTP 400 Bad request

Request contained incorrect parameters.

HTTP 401 Unauthorized

Submitter of the request did not authenticate with the primary or secondary z/OSMF instance, or is not authorized to use the z/OSMF REST service.

If the user ID required to authenticate with the primary and secondary z/OSMF instances are not the same, submit a separate HTTPS request to authenticate with the secondary z/OSMF instances.

HTTP 404 Bad URL

Target of the request (a URL) was not found.

HTTP 500 Internal server error

Programming error.