Retrieve data from one or more systems

You can use this operation to request that the primary z/OSMF instance submit an HTTPS request to retrieve data from one system, from a list of systems, or from all the systems in a group, sysplex, or central processor complex (CPC).

HTTP method and URI path

GET /zosmf/gateway/system?content=<http-content>
GET /zosmf/gateway/systems?content=<http-content>
GET /zosmf/gateway/group?content=<http-content>
GET /zosmf/gateway/sysplex?content=<http-content>
GET /zosmf/gateway/cpc?content=<http-content>
where:
  • zosmf/gateway identifies the multisystem routing services.
  • system informs the service that the request will be routed to only one system.
  • systems informs the service that the request will be routed to a list of systems.
  • group informs the service that the request will be routed to all of the systems in a group.
  • sysplex informs the service that the request will be routed to all of the systems in a sysplex.
  • cpc informs the service that the request will be routed to all of the systems in a CPC.
  • content=<http-content> represents the parameters used to qualify the request. Table 1 lists the parameters that are supported for this request.
    Important: If the value for a parameter contains a number sign (#), encode the number sign as %23. Otherwise, everything following the number sign will be omitted from the request. For example, if the target is System#1, specify System%231.
    Table 1. Supported input parameters for the multisystem routing services
    Parameter Required Description
    target Yes If the request is being sent to a system or a list of systems, the target is the nickname of the system. If the request is being sent to all the systems in a group, sysplex, or CPC, the target is the name of the group, sysplex, or CPC. The specified target must be defined in the Systems task. Otherwise, the request will fail.
    resourcePath Yes Path to the z/OSMF REST service that will process the request. The resource path must be within the z/OSMF context. For example, to ping a TSO/E address space on the target system, you would use the TSO/E address space services to process the request. Therefore, you would specify the following resourcePath: /tsoApp/ping/<servletKey>, where <servletKey> identifies the TSO/E address space for the service to ping.

    When sending an HTTPS request to a list of systems, you can specify a different resource path and different parameters for each system included in the list. When sending an HTTPS request to all the systems in a group, sysplex, or CPC, you can specify only one resource path and one set of parameters, which will be used for all the systems in the specified group, sysplex, or CPC.
    requestProperties No HTTP headers to be included in the HTTP request. Specify the HTTP headers as name and value pairs. If HTTP headers are omitted or are null, default values will be used, which are valid for most installations.
    timeout No Amount of time in milliseconds allowed to process a request. The value can range from 1 to 5601000 milliseconds. If omitted, the default value of 20000 milliseconds is used.
    content Yes if the HTTP method is POST or PUT. Parameters or JSON object to include in the body of the HTTPS request that will be sent to the z/OSMF REST interface that will process the request.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Custom headers

None.

Request content

None.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

See Required authorizations.

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.

The response also includes a JSON object that contains the requested information. For more details, see Content type used for HTTP response data.

Examples

To obtain sample HTTPS requests and responses for retrieving data from one system, from a list of systems, or from all the systems in a group, sysplex, or CPC, see the following sections:

Example 1: Retrieve data from one system

To retrieve the handlers that are registered for event type IBM.ZOSMF.IMPORT_EXTERNAL_APP from system sys057, submit the following request:
Figure 1. Sample request to retrieve data from one system
GET /zosmf/gateway/system?content={"target":"sys057",
"resourcePath":"/izual/rest/handler?eventTypeId=IBM.ZOSMF.IMPORT_EXTERNAL_APP",
{"contentType":"application/json","charset":"UTF8"}} HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 2.
Figure 2. Sample response from a request to retrieve data from one system
HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 05:39:28 +0000GMT
Connection: close

{
  "primaryAPIVersion":1.0,
  "systemsOutput":
    {
      "systemOutput":
        {
          "error":null,
          "result":[
            {
              "id":"IBM.ZOSMF.IZU_IMPORT_HANDLER",
              "taskId":"IZUG_TASK_zOSMFImportManager",
              "enabled":true,
              "defaultHandler":false,
              "applId":"IzuImportManager",
              "type":"INTERNAL",
              "displayName":"Import Manager",
              "url":"/zosmf/IzuImportUtility/index.jsp",
              "eventTypeId":"IBM.ZOSMF.IMPORT_EXTERNAL_APP",
              "options":{"CONTEXT_SUPPORT":"OPT_CONTEXT_SUPPORT_LAUNCH_AND_SWITCH"}
            }
          ],
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
	    "systemName":"sys057"
    },
  "numOfSystems":1
}

Example 2: Retrieve data from a list of systems

To retrieve the handlers that are registered for event type IBM.ZOSMF.IMPORT_EXTERNAL_APP from system sys057 and for event type IBM.ZOSMF.VIEW_DATASET from system sys060, submit the following request:
Figure 3. Sample request to retrieve data from a list of systems
GET /zosmf/gateway/systems?content=[{"target":"sys057",
"resourcePath":"/izual/rest/handler?eventTypeId=IBM.ZOSMF.IMPORT_EXTERNAL_APP",
{"contentType":"application/json","charset":"UTF8"}},{"target":"sys060",
"resourcePath":"/izual/rest/handler?eventTypeId=IBM.ZOSMF.VIEW_DATASET"}] HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 4.
Figure 4. Sample response from a request to retrieve data from a list of systems
HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 05:39:28 +0000GMT
Connection: close

{
  "primaryAPIVersion":1.0,
  "systemsOutput":[
    {
      "systemOutput":
        {
          "error":null,
          "result":[
            {
              "id":"IBM.ZOSMF.IZU_IMPORT_HANDLER",
              "taskId":"IZUG_TASK_zOSMFImportManager",
              "enabled":true,
              "defaultHandler":false,
              "applId":"IzuImportManager",
              "type":"INTERNAL",
              "displayName":"Import Manager",
              "url":"/zosmf/IzuImportUtility/index.jsp",
              "eventTypeId":"IBM.ZOSMF.IMPORT_EXTERNAL_APP",
              "options":{"CONTEXT_SUPPORT":"OPT_CONTEXT_SUPPORT_LAUNCH_AND_SWITCH"}
            }
          ],
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
	    "systemName":"sys057"
    },
    {
      "systemOutput":
        {
          "error":null,
          "result":[
            {
              "id":"IBM.ISPF.ISR.EPDF.B",
              "enabled":true,
              "defaultHandler":false,
              "type":"EXTERNAL",
              "displayName":"ISR Browse Data Set",
              "url":
               "/zosmf/webispf/index.jsp?cmd=ISPSTART%20CMD(%25ISREPDF%20'%24dataSetName'%20B)%20NEWAPPL(ISR)",
              "eventTypeId":"IBM.ZOSMF.VIEW_DATASET",
              "options":{"CONTEXT_SUPPORT":"OPT_CONTEXT_SUPPORT_LAUNCH"}
            }
          ],
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY4","zosVrm":"04.24.00","zosSysplex":"PLEX4"}",
	    "systemName":"sys060"
    }],
  "numOfSystems":2
}

Example 3: Retrieve data from all the systems in a group

To retrieve the handlers that are registered for event type IBM.ZOSMF.IMPORT_EXTERNAL_APP from all the systems in group mygroup, submit the following request:
Figure 5. Sample request to retrieve data from all the systems in a group
GET /zosmf/gateway/group?content={"target":"mygroup",
"resourcePath":"/izual/rest/handler?eventTypeId=IBM.ZOSMF.IMPORT_EXTERNAL_APP"} HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 6.
Figure 6. Sample response from a request to retrieve data from all the systems in a group
HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 05:39:28 +0000GMT
Connection: close

{
  "primaryAPIVersion":1.0,
  "systemsOutput":[
    {
      "systemOutput":
        {
          "error":null,
          "result":[
            {
              "id":"IBM.ZOSMF.IZU_IMPORT_HANDLER",
              "taskId":"IZUG_TASK_zOSMFImportManager",
              "enabled":true,
              "defaultHandler":false,
              "applId":"IzuImportManager",
              "type":"INTERNAL",
              "displayName":"Import Manager",
              "url":"/zosmf/IzuImportUtility/index.jsp",
              "eventTypeId":"IBM.ZOSMF.IMPORT_EXTERNAL_APP",
              "options":{"CONTEXT_SUPPORT":"OPT_CONTEXT_SUPPORT_LAUNCH_AND_SWITCH"}
            }
          ],
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
	    "systemName":"sys057"
    },
    {
      "systemOutput":
        {
          "error":
          {
            "msgid":"IZUG0000E",
            "msgtxt":"The HTTPS request to server "sys058" failed with return code 
                     "LoginRequired" and HTTP response code "401"."
          },
          "result":null
        },
      "rc":"LoginRequired",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY2","zosVrm":"04.24.00","zosSysplex":"PLEX2"}",
      "systemName":"sys058"
    },
    {
      "systemOutput":
        {
          "error":
          {
            "msgid":"IZUG0000E",
            "msgtxt":"The HTTPS request to server "sys059" failed with return code 
                     "HttpConnectionTimedOut" and HTTP response code "0"."
          },
          "result":null
        },
      "rc":"HttpConnectionTimedOut",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY3","zosVrm":"04.24.00","zosSysplex":"PLEX3"}",
      "systemName":"sys059"
    }],
  "numOfSystems":3
}

Example 4: Retrieve data from all the systems in a sysplex

To retrieve the handlers that are registered for event type IBM.ZOSMF.IMPORT_EXTERNAL_APP from all the systems in sysplex PLEX1, submit the following request:
Figure 7. Sample request to retrieve data from all the systems in a sysplex
GET /zosmf/gateway/sysplex?content={"target":"PLEX1",
"resourcePath":"/izual/rest/handler?eventTypeId=IBM.ZOSMF.IMPORT_EXTERNAL_APP"} HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 8.
Figure 8. Sample response from a request to retrieve data from all the systems in a sysplex
HTTP/1.1 200 OK
Date: Thu, 15 Feb 2015 05:39:28 +0000GMT
Connection: close

{
  "primaryAPIVersion":1.0,
  "systemsOutput":[
    {
      "systemOutput":
        {
          "error":null,
          "result":[
            {
              "id":"IBM.ZOSMF.IZU_IMPORT_HANDLER",
              "taskId":"IZUG_TASK_zOSMFImportManager",
              "enabled":true,
              "defaultHandler":false,
              "applId":"IzuImportManager",
              "type":"INTERNAL",
              "displayName":"Import Manager",
              "url":"/zosmf/IzuImportUtility/index.jsp",
              "eventTypeId":"IBM.ZOSMF.IMPORT_EXTERNAL_APP",
              "options":{"CONTEXT_SUPPORT":"OPT_CONTEXT_SUPPORT_LAUNCH_AND_SWITCH"}
            }
          ],
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
	    "systemName":"sys057"
    },
    {
      "systemOutput":
        {
          "error":
          {
            "msgid":"IZUG0000E",
            "msgtxt":"The HTTPS request to server "sys077" failed with return code 
                     "LoginRequired" and HTTP response code "401"."
          },
          "result":null
        },
      "rc":"LoginRequired",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
      "systemName":"sys077"
    },
    {
      "systemOutput":
        {
          "error":
          {
            "msgid":"IZUG0000E",
            "msgtxt":"The HTTPS request to server "sys195" failed with return code 
                     "HttpConnectionTimedOut" and HTTP response code "0"."
          },
          "result":null
        },
      "rc":"HttpConnectionTimedOut",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
      "systemName":"sys195"
    }],
  "numOfSystems":3
}

Example 5: Retrieve data from all the systems in a CPC

To retrieve the handlers that are registered for event type IBM.ZOSMF.IMPORT_EXTERNAL_APP from all the systems in CPC CPC1, submit the following request:
Figure 9. Sample request to retrieve data from all the systems in a CPC
GET /zosmf/gateway/cpc?content={"target":"CPC1",
"resourcePath":"/izual/rest/handler?eventTypeId=IBM.ZOSMF.IMPORT_EXTERNAL_APP"} HTTP/1.1

Host: zosmf1.yourco.com
A sample response is shown in Figure 10.
Figure 10. Sample response from a request to retrieve data from all the systems in a CPC
HTTP/1.1 200 OK
Date: Thu, 15 Feb 2015 05:39:28 +0000GMT
Connection: close

{
  "primaryAPIVersion":1.0,
  "systemsOutput":[
    {
      "systemOutput":
        {
          "error":null,
          "result":[
            {
              "id":"IBM.ZOSMF.IZU_IMPORT_HANDLER",
              "taskId":"IZUG_TASK_zOSMFImportManager",
              "enabled":true,
              "defaultHandler":false,
              "applId":"IzuImportManager",
              "type":"INTERNAL",
              "displayName":"Import Manager",
              "url":"/zosmf/IzuImportUtility/index.jsp",
              "eventTypeId":"IBM.ZOSMF.IMPORT_EXTERNAL_APP",
              "options":{"CONTEXT_SUPPORT":"OPT_CONTEXT_SUPPORT_LAUNCH_AND_SWITCH"}
            }
          ],
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY1","zosVrm":"04.24.00","zosSysplex":"PLEX1"}",
	    "systemName":"sys057"
    },
    {
      "systemOutput":
        {
          "error":null,
          "result":null
        },
      "rc":"Ok",
      "secondaryApiVersion":1.0,
      "systemVersion":"{"zosNode":"SY5","zosVrm":"04.24.00","zosSysplex":"PLEX5"}",
      "systemName":"sys289"
    }],
  "numOfSystems":2
}
Parent topic: Multisystem routing services