Application Linking Manager interface services

To perform traditional system management tasks in z/OS, you might interact with several different interfaces, such as the TSO command line, graphical user interfaces, and web-style interfaces. With the z/OSMF Application Linking Manager, it is possible to link or connect some of these tasks and external applications together for a smoother user experience.

The key components in the Application Linking Manager process include the:

Event requestor. z/OSMF task or external application that requests the launch of a specific function within another task or external application
Event. Action requested by the event requestor. It includes the type of event and the event parameters.
Event type. Object that connects an event requestor to an event handler. It identifies the handlers that can process an event and the possible parameters that can be supplied with an event.
Event handler. z/OSMF task or external application that can process the event parameters and display the requested information.

Figure 1 depicts the relationship of these components in the application linking process. For more information about these components and to obtain a list of the predefined event types, requestors, and handlers, see Event types, requestors, and handlers shipped with z/OSMF.

Figure 1. Key components in the application linking process

This graphic shows the relationship between the event requestor and the event handler in the application linking process.

z/OSMF provides the following resources for working with the Application Linking Manager:

Application Linking Manager task, which provides a graphical user interface that you can use to add, query, or remove event type and event handler definitions.
Application Linking Manager REST APIs, which are a set of REST services that allows a client application to add, query, or remove event type and event handler definitions.
AppLinker JavaScript API, which is a set of JavaScript services that allows a client application to send events to the Application Linking Manager or to define the context to be displayed. The JavaScript services are applicable only if you are creating your own z/OSMF plug-in.

The remainder of this section describes the Application Linking Manager REST APIs. For information about the Application Linking Manager task, see the z/OSMF online help. For details about the AppLinker JavaScript API, see Using the Application Linking Manager JavaScript APIs.

Operations provided through the Application Linking Manager interface services

Table 1 lists the operations that the Application Linking Manager interface services provide.

Table 1. Operations provided through the Application Linking Manager interface services
Operation	HTTP method and URI path
Register an event type	POST /zosmf/izual/rest/eventtype
Register an event handler	POST /zosmf/izual/rest/handler?eventTypeId=<eventTypeId>
Obtain a list of all tasks that are eligible to be handlers	GET /zosmf/izual/rest/adm/getHandlerEligibleTasks?eventTypeId=<eventTypeId>
Obtain a list of handlers for an event type	GET /zosmf/izual/rest/handler?eventTypeId=<eventTypeId>
Unregister an event handler	DELETE /zosmf/izual/rest/handler/<handlerId>?eventTypeId=<eventTypeId>
Unregister an event type	DELETE /zosmf/izual/rest/eventtype/<eventTypeId>

Required authorizations

To submit requests through the Application Linking Manager interface services, your user ID requires authorization to the Application Linking Manager task. Ensure that your user ID has READ access to the following resource profile in the ZMFAPLA class: <SAF-prefix>.ZOSMF.ADMINTASKS.APPLINKING. By default, any user ID with z/OSMF administrator authority can access the Application Linking Manager interface services.

Further, if you plan to use the Application Linking Manager interface services to list the registered event handlers for an event type, your user ID requires authorization to the z/OSMF SAF profile prefix on the target z/OS® system, as follows:

READ access to <SAF_PREFIX> in the APPL class.
READ access to the <SAF_PREFIX.izuUsers profile in the EJBROLE class.

By default, the z/OSMF SAF profile prefix is IZUDFLT.

For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

Content type used for HTTP request and response data

The JSON content type ("Content-Type: application/json") is used for sent data and returned data; for the detailed format of each returned object, see the JSON object description for each operation.

Error handling

For errors that occur during the processing of a request, the Application Linking Manager interface returns an appropriate HTTP status code to the calling client. An error is indicated by a 4nn code or a 5nn code. For example, HTTP/1.1 400 Bad Request or HTTP/1.1 500 Internal Server Error

In addition, some errors might also include a returned JSON object that contains a message that describes the error. You can use this information to diagnose the problem or provide it to IBM® Support, if required.

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 to z/OSMF or is not authorized to the Application Linking Manager task.
HTTP 404 Bad URL: Target of the request (a URL) was not found.
HTTP 500 Internal server error: Programming error.

Error logging

Errors from the Application Linking Manager interface services are logged in the z/OSMF runtime log files or the z/OSMF server logs directory. You can use this information to diagnose the problem or provide it to IBM Support, if required. For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.

Invoking a z/OSMF application link externally

It is possible for an external application (a web application, for example, or a desktop application), to launch a z/OSMF event on a z/OS system. Here, the application issues a command comprised of the URL for the local instance of z/OSMF, combined with the appropriate event information.

The following is an example of such a request. In the example, eventType-1 identifies the event type and value-1 specifies the parameter input for the event handler.

https://...:9443/zosmf/?izual.eventType={eventType-1}&parm1={value-1}

This command launches z/OSMF in a new browser window on the issuer's system, and sends the event to z/OSMF after session startup. If the user is authenticated to z/OSMF, the handler is launched in the user's session. Otherwise, the user is prompted to authenticate before the handler can be launched.