The goal of this tutorial is to describe step by step on how to create dynamic real time HTML dashboards with a custom layout that can be viewed in both desktop as well as mobile and table browsers.
Christian Grimm (firstname.lastname@example.org)
Experimental - Not Supported
2013-01-21 Initial release
Real time web dashboards:
Mobile Phone (WP8)
About dynaTrace dashboards
Compuware dynaTrace offers a great way to design and view dashboards within the Java based rich client. These dashboards are fully interactive and display analytics data in real time.
Documentation about dynaTrace dashboards:
Great video about building fancy dashboards:
Sometimes it could be helpful to display dashboards as HTML for viewing analytics data in a regular web browser or on mobile devices.
To accomplish this goal, dynaTrace offers a built in dashboard export functionality which is described in the reporting section of the dynaTrace documentation: https://apmcommunity.compuware.com/community/display/DOCDT50/Reporting
The out of the box HTML report function exports all dashboard components in vertical sequence, without any chance to manually configure the individual components or layout. This means the original layout of the designed dashboard will not be exported to the HTML document.
If a custom HTML dashboard with individual layout and functionality is a fundamental requirement, this tutorial will help to accomplish this.
Goal of this tutorial
This tutorial describes step by step how to create dynamic real time HTML dashboards with a custom layout.
The resulting HTML dashboards are viewable in any regular web browser or mobile device.
For mastering this tutorial requires basic knowledge of the following technologies:
- HTML (Create HTML documents)
- XML (Read and understand XML documents)
Going one step further and extend or debug parts of this project, an engineer level for the following technologies is essential:
How it works
(1) Getting the data from dynaTrace
Every dynaTrace dashboard can be exported as XML. This means all the underlaying data, which is visualized by the dynaTrace Rich Client can be exported as XML from the dynaTrace server.
Example (REST Inteface Call): http://dynatraceserver:8020/rest/management/reports/create/easyTravel%20Operations%20Console?type=xml
This REST call exports the raw data for the dashboard "easyTravel Operations Console" as XML. The exported data can be real time data or static data, depending on the configuration of the dashboard.
(2) Creating the HTML document
After getting the data as XML, XSL can be used to transform the raw XML data into HTML. For this tutorial a custom Apache Tomcat Web App (Servlet) will be used to execute this transformation.
This means for every web request to the Apache Tomcat Web Server, an internal REST call to the dynaTrace Server will be made to grab the XML and convert it on the fly into HTML.
The only thing needed is a HTML document on the Apache Tomcat Web Server, which contains the page style and defines at which location the charts should be rendered. That’s basically it.
Note: The HTML layout is packed into an XSL file.
As the "how it works" graphic above is suggesting, this tutorial explains how to make a HTML version of the dashboard "easyTravel Operations Console". However, it’s about the same process for any other dashboard.
For this tutorial, a working dynaTrace installation configured with easyTravel is required. Please refer to the following guide how to set up easyTravel: https://apmcommunity.compuware.com/community/display/DL/Demo+Applications+-+easyTravel#DemoApplications-easyTravel-InstallingeasyTravel
(1) Installation and Configuration
This section explains how to install and configure the Apache Tomcat Web Server.
(1.1) Install JRE
If the system, which is intended to run the Apache Tomcat Web Server, does not yet have a Java Runtime installed the JRE should be downloaded and installed from http://www.java.com
Hint: After the installation it’s very important to make sure the "JRE_HOME" system variable is set correctly.
(1.2) Install Apache Tomcat
Download the latest version from http://tomcat.apache.org. It’s recommended to download the ZIP file version and extract it to installation location. At the time this article has been written, Apache Tomcat 7.0.35 was the current version. This is also the only tested version for this tutorial.
The following screenshot shows an example of the extracted Apache Tomcat Installation:
After the installation it should be verified if the Apache Tomcat is running fine with the default configuration. The startup script "startup.cmd" will start the Apache Tomcat:
If Apache Tomcat is running fine, the following output on the console should be visible and the URL http://localhost:8080 should display the Apache Tomcat welcome page.
(2) Configuring the Apache Tomcat Web Server:
As an optional step the file "server.xml" from Apache Tomcat can be modified to run on port "80" instead of "8080".
(3) Installation and configuration of the HTML dashboard generator Web App:
After successfully setting up Apache Tomcat, the Web App which is doing to do all the XML to HTML processing needs to be deployed. Please download the file dynaTraceWebDashboardsApp-Step3.zip and extract it into the "webapps" sub folder of the Apache Tomcat installation directory.
The next step is to configure the Web App. It is important for the Web App to know how to access the dynaTrace server. Please edit the file "configuration.properties" and specify the dynaTrace server hostname, port (for the REST service) and credentials.
At this point the Web App can be tested. Opening the URL http://localhost:8080/dynaTraceWebDashboards/generate with a web browser should look as following.
The message "no style parameter supplied" is okay for now:
(4) Creation of a prototype HTML Dashboard
Now, it is time to craft a HTML document and design the desired dashboard. A professional tool such as Adobe Dreamweaver (http://www.adobe.com/products/dreamweaver.html) is strongly recommended during this process.
The goal is to design a static web page and substitute the dynamic dashboard parts (like traffic lights, charts, etc.) with image place holders for now.
An example of the HTML prototype for the "Operations Console" dashboard can be downloaded from here (easyTravel Operations Console Dashboard HTML Prototype.zip) and looks like this:
The HTML file should be saved to the root folder of the dynaTraceWebDashboards app while additional resources are stored in the "img" or "lib" sub folder.
If everything is working, the static dashboard is available through the Apache Tomcat Web Server. The following URL assumes the example dashboard (easyTravel Operations Console - HTML Prototype.html) is used:
(5) Convert the HTML prototype into an XSL template
After getting the static version of the dashboard to work with Apache Tomcat, the dynamic version can be built. The first step of doing this is to embed the static HTML into an XSL file. Please download this template (template.xsl) and use it for creating the XSL file:
After pasting the HTML code into place, the XSL file should look like this:
The final XSL file must be stored into the dynaTrace Web App root directory. An example of the final static XSL is available here:
easyTravel Operations Console - Static.xsl (Please rename it properly after downloading)
It is imperative to save the XSL file with exactly the same name as the dashboard in dynaTrace. The dynaTraceWebDashboards app will call the dynaTrace Server via the REST service to get the XML data. This only works, if the XSL has exactly the same name as the dashboard in dynaTrace – otherwise the Web App has no chance to know which dynaTrace dashboard to use as XML data source.
If everything went well, the XSL should now be available through the Apache Web Server.
Example for http://localhost:8080/dynaTraceWebDashboards/easyTravel%20Operations%20Console.xsl:
(6) Adding dynamics Elements (Traffic lights, charts, etc.):
This last section will cover how to replace the static placeholder elements with dynamic traffic lights, charts etc.
(6.1) Example for a traffic light
For the easyTavel Operation Console example described so far, there are placeholder elements in the HTML document which defines where a dynamic component should be inserted. Example:
Simply replace the placeholder with the following code to get a full dynamic traffic light:
(6.2) Example for a chart
Also replace the placeholders for chart elements with the following code to get a full dynamic chart:
The traffic light as well as the chart needs to know which dashlet and measures from dynaTrace dashboard XML data should be used. To define this, the following argument has to be matched with the XML output from the dynaTrace server:
XML output from dynaTrace server (http://localhost:8020/rest/management/reports/create/easyTravel%20Operations%20Console?type=xml):
An example of the final dynamic XSL is available here:
easyTravel Operations Console - Dynamic.xsl (Please rename it properly after downloading)
If everything went well, the following result can be achieved:
(8) Optional: Extensions and debugging
This section covers how to develop custom extensions to this project or just debugging it in general.
(8.1) Debugging the Java Servlet
The Java Servlet "com.compuware.apmcommunity.TransformationServlet" is responsible for the XSL to HTML conversion. The servlet is called with a style parameter (http://localhost/dynaTraceWebDashboards/generate?style=easyTravel%20Operations%20Console.xsl for example).
Internally the Servlet connects to the dynaTrace server, downloads the XML and transforms it using XSL finally into HTML. For this purpose the Saxon Java library is used.
Setting up the IDE (Eclipse) for debugging:
Please refer to the following tutorial for setting up Eclipse to debug Apache Tomcat Applications:
Just as described in the section "Import and Test a Sample App" from the listed tutorial above, projects can be imported from a ZIP file into Eclipse. The file EclipseProject.zip includes everything which is necessary and can be imported and run in Eclipse just the same way as described.
(8.2) Debugging the XSL to HTML transformation
Step by step debugging of XSL can be very tricky as this cannot be done within Eclipse. The "Oxygen XML Editor" from http://www.oxygenxml.com/ is maybe one of the best tools out there to handle this task.
Please follow these steps if step by step debugging of the XSL to HTML transformation is required:
(8.2.1) Download the "Oxygen XML Editor" from http://www.oxygenxml.com.
Unfortunately it’s not an open source tool available for free. However, Oxygen offers a 30 day trial to prove it's worth the money.
(8.2.2) Download a reference XML from the dynaTrace server
As already mentioned the XSL transformation cannot be debugged together with the Apache Tomcat Servlet. However, this is not so much of a handicap. The only thing needed to debug with Oxygen is a reference dashboard exported as XML from the dynaTrace Server. For the "easyTravel Operations Console" dashboard this could be downloaded from the dynaTrace server with this URL:
Just save the resulting XML to the Eclipse project workspace folder
(8.2.3) Create a new Oxygen Project
After starting up Oxygen, an Oxygen project needs to be created. It’s recommended to save it in the "WebContent" of the Eclipse project.
Adding files and folders to the project ...
.. to make the Oxygen project look like this:
(8.2.4) Configure the Run/Debug Config
After this double click on the "easyTravel Operations Console.xsl" file from the Oxygen project and hit the "Appy" or "Debug" button from the toolbar.
Use the following settings
Afterwards the following error may appear:
This error occurs because "DateUtil.xsl" is calling a Java method which is only available when executed within the Apache Tomcat environment. To overcome this issue, just comment (disable) the following line:
Afterwards debugging within Oxygen should work like a charm.