IBM Support

How to launch a URL externally in context, from a DASH widget?

Technical Blog Post


Abstract

How to launch a URL externally in context, from a DASH widget?

Body

Quite often we get asked from the field on different ways to easily launch external URLs from DASH. In this blog we will discuss about some of the options and look at one particular implementation in detail.

 

In this particular scenario, a dashboard administrator/page designer wants to launch an external URL (outside DASH, pointing to another IBM or non-IBM product) in response to the user clicking on a row in the list, table or a gauge widget. We will get the context from the widget and pass on to the external URL as query parameters.

 

Currently there is no easy way to do this in DASH. So let us achieve the same via some of the other existing features like Wires and Transforms. If you are unsure what that is, please watch these quick DashOGram video tutorials before we start:

Dashogram: How to Create a Wire

Dashogram: How to Create a Transformation

 

Now that you are a bit of an expert in Wires and Transformations, let us create a new wire and transform :-)

 

a) Creating a simple URL Launch Transform:

1. Go to the DASH Transformations directory and create a new folder - samples.urlLaunchTransformation

eg: <C:\IBM\JazzSM\profile>\installedApps\<JazzSMNode01Cell>\isc.ear\ISCWire.war\Transformations\samples.urlLaunchTransformation

Note: correct the JazzSM Profile and Cell names according to your environment

 

2. Create the following 2 files in the samples.urlLaunchTransformation folder created above

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&#34;
    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&#34;
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance&#34;
    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="samples.urlLaunchTransformation">
        <transformation:description
                uniqueName="samples.urlLaunchTransformation.description">
                <base:string>Transformation for NodeClickedOn event to launch a browser window</base:string>    
        </transformation:description>
        <transformation:title
                uniqueName="samples.urlLaunchTransformation.title">
                <base:string>Sample Launch URL Transformation</base:string>    
        </transformation:title>
        <transformation:function-name>LaunchURLTransform</transformation:function-name>
    </transformation:transformation>
</transformation:ibm-portal-transformation

 

transformation.js

/*
* This function retrieves the payload of a DASH event and launches an external URL
* in a new browser window with the event payload as context.
*
* srcEvent  - source event as JSON object
*/

LaunchURLTransform = function (srcEvent) {
    if (srcEvent === null) {
        return null;
    }
   
    var sourcePayload = srcEvent['payload'];
    console.debug("LaunchURLTransform: received event with following payload");
    console.dir(sourcePayload);
    
    if ((sourcePayload !== undefined) && (sourcePayload['resources'] !== undefined)) {
        var sourceResArray = sourcePayload['resources'];
        //Take the first resource in the array, we expect only 1 resource/context
        var sourceResObj = sourceResArray[0];     
        if(sourceResObj){        
            //Just using first object property, change accordingly
            //Standard JavaScript object iteration, google for more info

            for (var prop in sourceResObj) {
              if(sourceResObj.hasOwnProperty(prop)){
                //logging first property and its value
                console.debug("o." + prop + " = " + sourceResObj[prop]);
                //JavaScript API to open a new browser window
                window.open("http://google.com/search?q="+prop+"%20"+sourceResObj[prop]);
                break; //quit iteration as we are interested in first property only
              }
            }
        }            
    }
    
    return null; //ignore the event
}

 

Feel free to tweak the transformation.js as you need. For eg: you can check the context and may open a different URL according to a certain value or even use the URL coming in from the context.

 

b) Create a wire and use the above URL Launch Transform:

1. Now go to DASH UI and create a new wire and point it to the same page itself.

1.1 We will use an existing sample in DASH which is shipped by default, Samples -> OS Dashboard Sample. Edit it by selecting 'Edit Page' as shown below

image

1.2 Let us pick the 'Event List' table in bottom left corner for this example. Make sure it supports sending a 'NodeClickedOn' event by going to the Event details dialog via the 'Events' option

image

 

image

For this to work the source widget should support publishing NodeClickedOn event as shown above.

 

1.3 Go back to edit mode and click on 'Show Wires' button and let's create a wire:

image

1.4 Use Event List -> NodeClickedOn as the source for the wire

image

 

1.5 Let us use the same page as the target for the wire. In the transformation.js we return null, so event is not passed on further. Since you are launching out it doesn't make much sense to interact with other widgets on the same page simultaneously, if you want that, instead or return null you can return the srcEvent.

image

1.6 Select the new transform we created earlier

image

You should see the following wire if you did all the steps so far correctly.

image

 

2. Save the page and now when you click on a row in the Event List table, it opens a new browser window with a Google search for the first property name and value.

image

 

Limitations of this approach:

  • The source widget should support 'NodeClickedOn' event. You can check this via the Event details of the widget
  • Clicking anywhere on a row of a Table produces the same result since the whole row is the context

 

Other alternatives for launching a URL

  1. You can achieve same result by creating a custom widget thru the ContentBox feature in DASH. Your widget would then receive the NodeClickedOn event and launch a URL with the context from the event payload. Same limitations apply.
  2. Overlay with the HotSpot widget and configure a URL to it with 'Open Web Page' action. Not as dynamic as our approach, but could work well for certain scenarios.
  3. If you want to launch an external URL inside DASH (as part of same page or as another page) instead of opening a new browser window, you can use the Web Widget. You can follow this example to see how you can create a transform to convert the NodeClickedOn event to DisplayURL event accepted by the Web Widget. It also supports parameter substitution so that you can change the context passed to the URL dynamically.
  4. If you have control over the dataset (eg: TDI/Impact), you can add a task/action in the dataset, which will be exposed via a right click context menu in most widgets like Table, List etc
  5. Some products which integrate into DASH has similar mechanisms - eg: Omnibus Tool which shows up as context menu action in Event Viewer or Active Event List (AEL)

 

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"","label":""},"Component":"","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"","label":""}}]

UID

ibm11080165