Custom Process Dashboard Reporting
The Process Dashboard displays a large number of powerful charts and reports. But every organization has their own special needs, and your team may find yourself needing a particular report that is not already a part of the Process Dashboard.
Fortunately, the Dashboard provides a powerful solution to this problem. The dashboard contains an embedded web server for the display of process scripts, reports, charts, and other materials. Beginning in version 2.1, this server is based on the Jetty JSP engine. This makes it possible to develop custom reports using standard Java technologies, and run them against the project data in the Team Dashboard.
In this way, the Team Dashboard is much more than a data collection and analysis tool; it is ultimately a process- and project-driven application server. Your custom logic can run within this environment, enjoying effortless access to precomputed team project data, to generate the custom reports and analyses that you need.
Trying out the Demonstration Reports
This github repository provides a demonstration of several simple reports. To try them out, take these steps:
- Download the code for this demonstration project, or check out the code using git.
- Use maven to compile the code and build a WAR file:
- Open a Team Dashboard and choose "Help > About Process Dashboard > Configuration."
- The Configuration tab will include a paragraph stating that "Dashboard add-ons will also be read from the following directory..." Find that directory on your hard drive, creating it if it does not exist.
- Copy the WAR file (created in step 2) into that directory.
- Close and restart the Team Dashboard.
Each Team and Master Project will now include an item in the list of reports called "Reporting Demonstrations." Click this option to open the example and explore the various reports.
How the Demo Reports Work
Next, take a look at the source code for the demo to see how the reports work. Here are some notes:
- This WAR behaves just like any standard Java web application, and uses the same packaging.
- Reports can be written as JSPs or servlets.
- Inside the WAR, an extra
WEB-INF/processdash.xmlfile can be used to register items that should appear on the script list for team and master projects.
- When a JSP or servlet runs in the dashboard, a special object called
pdashwill be available in the servlet request. This is a
PDashContextobject. You can read API documentation on the PDashContext functionality here: http://www.processdash.com/static/pdash-servlet-api/index.html
- The PDashContext object provides access to the dashboard's calculation engine and also to a service which can perform intelligent object-oriented HQL queries against the dashboard's database. The various demos show how these objects can be used.
- When writing object-oriented HQL queries against the database, it is helpful to understand the object data model:
- Detailed information about the database is given here: http://www.processdash.com/tpdw
- Javadoc API documentation for the database object model is provided here: http://www.processdash.com/static/tpdw-data-api/index.html
Publishing Custom Reports Within Your Organization
If you develop reports that you would like to share with others in your organization, this is easy to accomplish; just make use of the template search path feature provided by the Team Dashboard.
When you take this approach, it is wise to add new attributes (beginning with
Dash-Pkg-) to the
META-INF/MANIFEST.MF file in your WAR file; see the
pom.xml file in this project for an example. These attributes allow you to tag the WAR as a Team Dashboard add-on with a given name, ID, and version number.
If two WAR files with the same ID appear in the template search path, the dashboard will use the one with the highest version number. This versioning strategy can be helpful in several ways:
- If WAR files get copied around to many different places, you can use this to help ensure that people in your organization receive the most recent version of your WAR.
- When you are developing enhancements to your WAR, you can assign a higher version number to the development snapshot that you deploy on your local computer. This will allow your local development snapshot to be preferred over the WAR that has been published to the rest of the organization via the template search path.
When you use the
Dash-Pkg- attributes, your WAR's name and version will be displayed on the "Help > About > Configuration" tab. Clicking the "More Details..." link at the bottom of that tab will also tell you the filesystem path of the WAR that was selected by the template search path mechanism. This information can be helpful for troubleshooting purposes if an individual is not seeing your custom reports, or if they are seeing an older version of your WAR.
Sharing Custom Reports
If you build a custom report that your organization finds useful, it is very likely that other organizations might find the report useful too. Since the Process Dashboard is an open source application, we welcome everyone to share their reports with the rest of the Process Dashboard community.