getEventFromUrl function

If your task is an event handler and the hasLaunchContext function returns true, call the getEventFromUrl function to parse the URL that z/OSMF core used to launch your task. Doing so will provide your task with the event type ID and parameters it needs to display the correct context. Otherwise, your task will launch without context.

Invoking the function

To call the getEventFromUrl function, use the syntax shown in Figure 1.

Figure 1. Syntax to use to call the getEventFromUrl function

win.global.applinker.getEventFromUrl();

Return values

The getEventFromUrl function returns an event object that includes the following information:

type: The event type ID supplied with the event.
params: Array that contains the name and value of each parameter supplied with the event.

Tip: While your task is loading, it must use the event information to display the correct context. For example, your task might call another JavaScript function, which you provide, that can process the event information and return the correct context.

Expected results

The event information returned by the getEventFromUrl function depends on the launching option that is specified in the event handler definition for your task and whether your task is already open when an event is received.

Table 1 describes the expected result for each launching option and task state (open or closed) combination.

Table 1. Expected results by launching option and task state
Launching option and task state	Expected result
The launching option is launch without context and the task is closed.	The getEventFromUrl function will return null, and z/OSMF core will launch the task using the URL supplied in the handler definition. Tip: z/OSMF core does not collect event information for this launching option because there is no context to display; therefore, it is not necessary for your task to call the getEventFromUrl function.
The launching option is launch without context and the task is already open.	The getEventFromUrl function will return null, and z/OSMF core will bring the existing task tab into focus. Tip: z/OSMF core does not collect event information for this launching option because there is no context to display; therefore, it is not necessary for your task to call the getEventFromUrl function.
The launching option is launch with context and the task is closed.	The getEventFromUrl function will return the event type ID and parameters for the current event, and the task will display the current context.
The launching option is launch with context and the task is already open.	The getEventFromUrl function will return one of the following values: The event type ID and parameters for the event that z/OSMF core used to initially open the task. Null if the task was not initially opened as a result of an application linking event. z/OSMF core will bring the existing task tab into focus, and the task will display its last context.
The launching option is launch with context and reload and the task is closed.	The getEventFromUrl function will return the event type ID and parameters for the current event, and the task will display the current context.
The launching option is launch with context and reload and the task is already open.	z/OSMF core brings the existing tab into focus and displays a message, which warns the user that the current context will be overwritten and gives the user the option to proceed with displaying the new context or keeping the previous context. If the user clicks OK, the getEventFromUrl function will return the event type ID and parameters for the new event, and the task will display the new context. If the user clicks Cancel, the getEventFromUrl function will return one of the following values, and the task will display its last context: The event type ID and parameters for the previous event. Null if no event has occurred.
The launching option is launch with context and switch and the task either is closed or is already open.	The getEventFromUrl function will return the event information for the current event, and your task will determine the context to display based on the callback function you provided as a parameter for the subscribe function. Tip: z/OSMF core supplies your task with the event type ID and event parameters when it calls the subscribe callback function; therefore, it is not necessary for your task to call the getEventFromUrl function to retrieve the event information. For information about the subscribe function, see subscribe function.

Example

Figure 2. Sample code for the getEventFromUrl function

function init(){
{
  if(win.global.applinker.hasLaunchContext()){
  //The task was opened with application linking; therefore, update context.

  //Use the getEventFromURL function to obtain the context.
  var result = win.global.applinker.getEventFromURL();
  var eventType = result.type;
  var params = result.params;

  //Use the eventType and parameters to switch the context.

  }
  else{
  //The task was not opened with application linking; therefore, display 
  //the standard starting page.
  
  }
}