Application server routing services

As depicted in Figure 1, the process of routing requests and responses for plug-ins where the client and server-side code are on different application servers is as follows:

1. Use the z/OSMF Import Manager task to import your plug-in into z/OSMF, and to associate each task in the plug-in with an application server. For instructions, see Adding your applications to z/OSMF.
2. During the import process, z/OSMF core creates symbolic links to the client-side code for your application and stores those links in the z/OSMF file system on the z/OSMF server.
3. When the import process completes, z/OSMF core adds the tasks included in your plug-in to the z/OSMF navigation area.
4. When a user selects your task in the z/OSMF navigation area, z/OSMF core submits an HTTPS request to the file retrieval service to retrieve the client-side files and the browser downloads those files.
5. When the user performs an action that requires the task to interact with the server-side code, the client-side code for the task submits an HTTPS request to the application server routing interface, and that interface routes the request to the application server that is associated with the task.
6. The server-side code for your task processes the request and submits an HTTPS response to the application server routing interface, and that interface routes the response to the client.

The JSON content type ("Content-Type: application/json") is used for HTTP response data. If the client requests for the application server routing service to add additional information to the response from the target application server, the service wraps the response in the following JSON object. Otherwise, the service returns only the response from the target application server.

{
 "primaryAPIVersion":"primary-API-version",
 "systemsOutput":
   {
     "systemOutput":"system-output",
     "rc":"return-code",
     "error":{"msgid":"message-ID","msgtxt":"message-text"},
     "systemName":"system-name"
   },
 "numOfSystems":"total-systems"
}

where

primary-API-version

Version of the application server routing services interface on the z/OSMF server.

systemsOutput

Contains a set of attributes that provide different information about the response from the target application server.

system-output

Contains the response from the target application server.

return-code

Contains the return code provided by the target application server. The return code can be one of the following values:

OK

Success.

HttpConnectionFailed

The HTTPS connection failed. Typically, this error occurs when the target application server is unavailable or a network error has occurred.

HttpConnectionTimedOut

The HTTPS request did not complete in the time allotted.

CertificateError

The certificate for the target application server is not trusted.

InvalidLogin

The login credentials for the target application server are not valid.

FailedWithMessage

The request was successful; however, an internal error occurred on the target application server.

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.

system-name

Nickname assigned to the system entry in the z/OSMF Systems task that describes the settings required to access the target application server.

total-systems

Value is set to 1 because the HTTPS request can be sent to only one application server at a time.

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 is not authorized to use the service or did not authenticate with z/OSMF, or single sign-on is not enabled between the z/OSMF server and the target application server.

HTTP 404 Bad URL

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

HTTP 500 Internal server error

Programming error.