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.

This github repository provides a demonstration of several simple reports. To try them out, take these steps:

1. Download the code for this demonstration project, or check out the code using git.
2. Create a keypair for code signing by running the generate-signing-key.bat batch file in the project directory. (You can also use the keytool program in your Java SDK directly if you prefer, or if you are not building on Windows.) You will be prompted to enter your name, organization, and other details to write into the code signing key.
3. Use maven to compile the code and build a WAR file: mvn package
4. Open a Team Dashboard and choose "Help > About Process Dashboard > Configuration."
5. 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.
6. Copy the WAR file (created in step 3) into that directory.
7. Close and restart the Team Dashboard.
8. If you are running version 2.7 or higher of the Team Dashboard, visit http://localhost:3000/control/showPackage?pkgId=reportDemo and click the "Approve Add-ons from this Signer" button. Then close and restart the Team Dashboard one last time.

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.

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.xml file 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 pdash will be available in the servlet request. This is a PDashContext object. 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

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.

Before you begin sharing an add-on, it is wise to edit the Dash-Pkg-* attributes in the pom.xml file. These attributes allow you to tag the WAR as a Team Dashboard add-on with a given name, ID, and version number that are specific to your custom report development efforts.

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 if an individual is not seeing your custom reports, or if they are seeing an older version of your WAR.

Add-ons can contain custom executable code. To prevent their use as a vector for malware, Process Dashboard 2.7 and higher will reject add-ons unless they are signed by a recognized certificate. (Earlier versions of the dashboard used a different security mechanism to block dangerous code without requiring signatures. But that mechanism is incompatible with recent versions of Java, so signatures have been adopted going forward.)

The instructions above helped you to generate a personal code signing certificate, and arrange for it to be trusted by the Process Dashboard on your computer.

Other people in your organization will need to trust your certificate as well before they can use your add-on with Process Dashboard 2.7 and up. They can do this by following these steps:

1. Opening the Team Dashboard, choosing "Help > About > Configuration," and scrolling to the bottom of the tab.
2. If they are using Process Dashboard 2.7, they may see a section in red text advising them that your plugin has been rejected.
3. If so, they should click the name of your add-on, press the "Approve Add-ons from this Signer" button, and restart the Team Dashboard.

These steps will approve the add-on for use on their computer, along with any other add-ons you sign in the future with the same certificate. So if you use a consistent certificate for your add-on development work, people in your organization will only need to take these steps once.

If you've written a custom reporting add-on in the past, you'll need to take these steps to make it compatible with the new trust mechanism in Process Dashboard 2.7:

1. Retrieve the latest files from this git repository, to include pom.xml and generate-signing-key.bat. Merge these changes into your customized pom.xml file if necessary.
2. Create a keypair for code signing by running the generate-signing-key.bat batch file in the project directory. (You can also use the keytool program in your Java SDK directly if you prefer, or if you are not building on Windows.) You will be prompted to enter your name, organization, and other details to write into the code signing key.
3. Increment the <version> number at the top of your pom.xml file. (This will cause your newly signed add-on to receive a higher Dash-Pkg-Version and be preferred over the older, unsigned file.)
4. Rebuild your add-on by typing mvn clean package
5. Copy the new WAR file into your local Templates directory.
6. Close and restart the Team Dashboard. Choose "Help > About > Configuration" and scroll to the bottom of the tab.
7. Look for a table of red text advising that your plugin has been rejected. Click the name of your add-on, press the "Approve Add-ons from this Signer" button, and restart the Team Dashboard.
8. After validating the functionality of your add-on, share the updated file with others in your organization as appropriate. They will also need to approve your add-on for use by Process Dashboard 2.7.

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.

Please feel free to contribute other reports via pull requests or by contacting the Process Dashboard development team directly.