Introduction

This article describes how to configure a Web GUI map to launch another Web GUI map in a portlet page.

In Web GUI 7.4.0/8.1, a map can be configured to launch (or change the context) of an Event Viewer or AEL portlet with the "Update Event List (using wires)" launch action. This action can also be used to configure custom wires between maps such that clicking an element in one map may launch a portlet page containing another map. This article describes how to do this.

(Note: This article was updated on 23 September 2015 to include deployment details for transformation files on DASH in Web GUI 8.1)

Step 1: Configure the map click-action

This step configures a map element so that when it is clicked it fires a NodeClickedOn event that is picked up by any wires on the portlet page

1. Navigate to the Administration->Event Management Tools->Map Creation task and edit the map from which the launch will be performed
2. Select the map element whose click-action should launch a map and edit its properties.
3. Select the Associations tab and choose the option: Update Event List (using wires)
4. Repeat steps 1 to 3 for each map element that should launch a map portlet
5. Apply the changes and save the map
6. Repeat steps 1 to 5 for each map that should launch other maps

Step 2: Deploy Transformation

This step deploys a transformation to intercept the NodeClickedOn event from the map and route it to the correct destination. Transformations manipulate the event generated by a source target before it is delivered to the target portlet . This is required because a Map is not capable of receiving a NodeClickedOn event directly, so a "framework" event must be used to launch the portlet containing target map.

1. Create the transformation descriptor in a file named ibm-portal-transformation.xml
    

   <?xml version="1.0" encoding="UTF-8"?> <transformation:ibm-portal-transformation     xmlns:p="http://www.ibm.com/tivoli/tip/schemas/2.1/ibm-portal-base.xsd"     xmlns:transformation="http://www.ibm.com/tivoli/tip/schemas/2.1/ibm-portal-transformation.xsd"     xmlns:base="http://www.ibm.com/tivoli/tip/schemas/2.1/ibm-portal-base.xsd"     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:schemaLocation="http://www.ibm.com/tivoli/tip/schemas/2.1/ibm-portal-transformation.xsd ibm-portal-transformation.xsd http://www.ibm.com/tivoli/tip/schemas/2.1/ibm-portal-base.xsd ibm-portal-base.xsd ">     <transformation:transformation         uniqueName="com.ibm.tivoli.ncw.transforms.map">         <transformation:description                 uniqueName="com.ibm.tivoli.ncw.map.MapTransform.description">                 <base:nls-ref                              key="MapTransform.description"                         locationName="classes/com/ibm/tivoli/ncw/map/nl/MapTransform" />         </transformation:description>         <transformation:title                 uniqueName="com.ibm.tivoli.ncw.map.MapTransform.title">                 <base:nls-ref                         key="MapTransform.title"                         locationName="classes/com/ibm/tivoli/ncw/map/nl/MapTransform" />         </transformation:title>         <!-- This is the name of the function in the transformation.js that will be called when the event is occurred. -->         <transformation:function-name>launchMap</transformation:function-name>     </transformation:transformation> </transformation:ibm-portal-transformation>

   
    
2. Create the JavaScript function in a file named transformation.js. The function must be named as specified in the <transformation:function-name> element of the transformation descriptor
    

   launchMap=function(srcEvent,srcElement,targetEventName){         if(srcEvent == null) {         return null;     };          //Send original event if anything goes wrong..     var eventObject  = srcEvent;          try {                  /*         * Construct the event object for launching the map tab - the source event payload can be         * examined here and the navigation element customized based on the clicked map element         */         var filterName = srcEvent.payload.product.OMNIbusWebGUI.displaycontext.filterName;         var filterType = srcEvent.payload.product.OMNIbusWebGUI.displaycontext.filterType;         console.log("Transforming NodeClickedOn event. The clicked filter was: " + filterType + ":" + filterName);                  var navigationNode = "item.desktop.navigationElement.ExampleMapGeographic";         //Additional navigation nodes may be added to the conditional statement below         if ("AllEvents" == filterName)             navigationNode = "item.desktop.navigationElement.ExampleMapECommerce";         else if ("Default" == filterName)             navigationNode = "item.desktop.navigationElement.ExampleMapGeographic";         else if ("Unacknowledged" == filterName)             navigationNode = "com.ibm.isclite.admin.PortletPicker.navigationElement.pagelayoutA.modified.QSl5VsLGRUH-0H1MCgYAlIW1377872548266";                 console.log("Transforming NodeClickedOn event. The target Navigation Node is: " + navigationNode);                  eventObject = {            name: "http://ibm.com/isclite#launchPage",            NavigationNode: navigationNode,            pageInstanceRef: null,            switchPage: true         };             console.log("Transformed NodeClickedOn event. New event is: " + eventObject);     }     catch(error) {         console.log("Failed to transform event: " + srcEvent);     }          //Send a framework event to launch the target node     EventBroker.sendFrameworkEvent( eventObject, IscPages.currentPageId )          return eventObject; }

   
   Note that in the example method above, the target map is specified by checking the filterName value of the NodeClickedOn event from the source map. the navigationNode variable is set to the Page unique name. To determine the Page unique name for a map portlet, use the TIP Navigation Task Settings -> Pages
3. Create resource bundles. (Optional, but allows the transformation to be easily identified when configuring custom wires between portlets)
    

   # NLS_MESSAGEFORMAT_VAR # NLS_ENCODING=UNICODE # The file is the default "MapTransform" resource bundle. If no other locale # files are created, this will be used as the default for "MapTransform" bundle requests. MapTransform.description=This transform may be applied to Netcool/OMNIbus Web GUI Maps. Launches a map portlet. MapTransform.title=Show Map

   
    
4. Deploy the transformation files eg in Web GUI 7.4:
   1. Save the transformation descriptor to
      $TIPHOME/tipv2/profiles/TIPProfile/installedApps/TIPCell/isc.ear/ISCWire.war/Transformations/com.ibm.tivoli.ncw.transforms.map/ibm-portal-transformation.xml
   2. Save the transformation JavaScript code to
      $TIPHOME/tipv2/profiles/TIPProfile/installedApps/TIPCell/isc.ear/ISCWire.war/Transformations/com.ibm.tivoli.ncw.transforms.map/transformation.js
   3. Save the resource bundles to
      $TIPHOME/tipv2/profiles/TIPProfile/installedApps/TIPCell/isc.ear/ISCWire.war/WEB-INF/classes/com/ibm/tivoli/ncw/map/nl/MapTransform.properties

Note: In Web GUI 8.1, the deployment is as described below:

1. Save the transformation descriptor to
   $DASH_HOME/profile/installedApps/JazzSMNode01Cell/isc.ear/ISCWire.war/Transformations/com.ibm.tivoli.ncw.transforms.map/ibm-portal-transformation.xml
2. Save the transformation JavaScript code to
   $DASH_HOME/profile/installedApps/JazzSMNode01Cell/isc.ear/ISCWire.war/Transformations/com.ibm.tivoli.ncw.transforms.map/transformation.js
3. Save the resource bundles to
   $DASH_HOME/profile/installedApps/JazzSMNode01Cell/isc.ear/ISCWire.war/WEB-INF/classes/com/ibm/tivoli/ncw/map/nl/MapTransform.properties

See Deploying transformations for more information.
 

Step 3: Create Custom Wires

This step creates the wire which will be used to send a NodeClickedOn event from the map. The trick here is to select the source and target as the same map page. This is because the transformation above will fire a new TIP framework event that will handle the appropriate target page launch.

1. Navigate to the Map portlet which is the source of the click-action. eg) Availability->Events->E-Commerce
2. Modify the page wires, Select-Action -> Show Wires
3. Click the New Wire button. The wire configuration dialog is launched.
4. Select Source Event for New Wire. Choose
   Map
     -> NodeClickedOn
5. Click OK
6. Select Target for New Wire. Choose the same map as for step 4. (This means that the map will be firing the NodeClickedOn event to itself).
   Availability
      -> Events
        -> This page (E-Commerce)
7. Check the "Load the selected target page" and "Switch to the selected target page" options and click OK
8. The Transformations window is displayed. Choose "Show Map" and click OK
9. Save the page
10. There should now be a new custom wire
11. Click the map element configured in step 1
12. The target map portlet should be launched
13. Repeat steps 1-12 for each map that is to be used to launch other map pages

The screen capture below shows how the custom wire should be configured for each map portlet page.

More Information

• Configuring communications between portlets using wires