Using the Application Linking Manager JavaScript APIs

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

z/OSMF predefines several event types, requestors, and handlers. For a list, see Event types, requestors, and handlers shipped with z/OSMF.

Importing and instantiating the AppLinker API

To participate in the application linking process as an event requestor or an event handler, your task needs access to the functions provided in the AppLinker API, which is located at the following path: /zosmf/js/zosmf/izual.

To access the functions in the API, you must import and instantiate the AppLinker API in your task’s HTML file. Sample code is provided in Figure 1.

//Add a package for izual
packages: [{
   name: "izual",
   location: "/zosmf/js/zosmf/izual"
}]

//Import the AppLinker API.
require(["izual/api/PluginAppLinker17"],
         function(PluginAppLinker){
}
//Instantiate the global AppLinker variable.
win.global.applinker = new PluginAppLlinker();

//After instantiation, call the zOSMFTools getAppLinker function
win.global.zosmfTools=new Tools();
var localAppLinkerVariable = win.global.zosmfTools.getAppLinker();

Functions provided in the AppLinker API

Using the AppLinker functions in the application linking process

The application linking process consists of the following steps:

1. An event requestor defines a user interface control that invokes the sendEvent function when a user performs an action.
2. An event requestor calls the getHandlers function to determine if handlers are available to process the request. If handlers are not available, the event requestor might perform an action such as disabling or hiding the user interface control.
3. A user performs an action on the user interface control that triggers the call of the sendEvent function.
4. The Application Linking Manager searches the set of known event types for the type identified by the event.
5. If a match is found, the Application Linking Manager searches for event handlers that are registered for this event type. If only one handler is found, it is launched. Otherwise, the user is prompted to select the handler to launch.
6. After the handler is identified, z/OSMF core identifies the launch context the handler supports.
7. If the launch context is launch without context, z/OSMF core uses the URL provided in the handler definition to launch the handler. If the handler is already open, it receives focus.
8. If the launch context is launch with context, launch with context and reload, or launch with context and switch, z/OSMF core does the following:
   • Appends the event type and parameters to the URL provided in the handler definition.
   • Completes one of the following actions:
     • If the launch context is launch with context, z/OSMF core uses the modified URL to launch the handler. If the handler is already open, it receives focus.
     • If the launch context is launch with context and reload, z/OSMF core uses the modified URL to launch the handler. If the handler is already open, a message is displayed warning the user that the current context will be overwritten.
     • If the launch context is launch with context and switch, the following steps are completed:
       1. z/OSMF core uses the modified URL to launch the handler.
       2. If the handler is loading for the first time, the handler calls the subscribe function for each event type to which it wants to subscribe and provides the function that z/OSMF core will call to determine the context to display.
       3. After the handler subscribes to all the event types it can process, the handler calls the onLoadingComplete function to inform z/OSMF core that it is ready to accept events.
       4. When an event occurs, z/OSMF core verifies that the handler has called the onLoadingComplete function. If the function has been called, z/OSMF core searches the list of handlers that have subscribed for this event type, and identifies the callback function for the selected handler.
          Important: Register your task for each event type to which your task subscribes. Otherwise, z/OSMF core will not use the subscription because users will not have the option of selecting your task as the handler for the event.
       5. z/OSMF core calls the subscribe callback function.
       6. The function returns the context for z/OSMF core to display.
       7. z/OSMF core displays the context and finishes loading the handler.
9. To display the correct context for the launch with context and launch with context and reload launching options, the handler must do the following while it is being loaded:
   1. Call the hasLaunchContext function to determine if an event has occurred.
   2. Call the getEventFromUrl function to extract the event information from the URL that z/OSMF used to launch the handler.
   3. Use the event information to display the correct context. For example, the handler might call another JavaScript function, which you provide, that can process the event information and return the correct context.