IBM Support

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

Technical Blog Post


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


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



<?xml version="1.0" encoding="UTF-8"?>
    xsi:schemaLocation=" ibm-portal-transformation.xsd ibm-portal-base.xsd ">
                <base:string>Transformation for NodeClickedOn event to launch a browser window</base:string>    
                <base:string>Sample Launch URL Transformation</base:string>    



* 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");
    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];     
            //Just using first object property, change accordingly
            //Standard JavaScript object iteration, google for more info

            for (var prop in sourceResObj) {
                //logging first property and its value
                console.debug("o." + prop + " = " + sourceResObj[prop]);
                //JavaScript API to open a new browser window
                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


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




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:


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



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.


1.6 Select the new transform we created earlier


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



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.



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":"BU004","label":"Hybrid Cloud"},"Product":{"code":"","label":""},"Component":"","Platform":[{"code":"","label":""}],"Version":"","Edition":""}]