Making a change to a script

Perhaps a pre-existing process suits you well, but you'd like to make some small tweak to one of the HTML scripts. For example, you might like to add company specific instructions to some of the steps (to run a code analyzer perhaps).

When you're viewing the page in question, you notice it has a URL like:

http://localhost:2468/Project+Path//procID/script.htm

In this example, "procID" is the ID of the process containing the script, and "script.htm" is the name of an HTML script within that process.

Take the following steps:

1. Choose " → Help → About," and click the "Configuration" tab. One of the paragraphs will state that "add-ons will also be read from the following directory." Find that directory on your computer; it will end with "Templates".
2. Create a subdirectory within "Templates" with the name that appears in the "procID" space in the example above.
3. Save the current version of the HTML file to the subdirectory you just created. This can be done by choosing "File Save As..." from within your web browser.
   • Give the file the same name that appears in the URL - in this instance, we would save the file as "script.htm". (Note: if the URL contains a "?" or "#", just use the filename that appears before the "?" or "#".)
   • If your web browser has a feature to save "html only", use it.
4. Edit it to your heart's content using the HTML editor of your choice.

Now, every time you visit that page, for any project in your hierarchy that uses this process, the dashboard will show you the page containing your custom changes.

How the Dashboard finds process files

When it starts, the dashboard searches for process files and add-ins and dynamically loads them. Also, every time you request a web page from http://localhost:2468/, the dashboard is using this same search mechanism.

The dashboard searches for files in the following locations, in the following order:

1. Look first in the directories specified by the add-on search path.
2. Next, look in any WAR/JAR/ZIP files contained in that directory.
3. Next, look in any WAR/JAR/ZIP files contained in the parent of that directory.
4. Next, look in the user-specific application templates directory. (To locate this directory, choose "Help → About Process Dashboard → Configuration." Look for the heading that reads, "Dashboard add-ons will also be read from the following directory.")
5. Next, look in any WAR/JAR/ZIP files contained in the application templates directory.
6. If there is a Templates directory underneath the directory where the Process Dashboard is installed, look there: first for the file, then for WAR/JAR/ZIPs containing the file.
7. Next, look within the WAR, JAR and ZIP files that are present in the Process Dashboard installation directory.
8. Finally, look inside the Process Dashboard application file. (This file is called "pspdash.jar", and it appears in the Process Dashboard installation directory.)

When looking for a particular file, the dashboard will search in the above locations and stop as soon as it finds a matching file. This means that if you want to customize anything that appears in a process templates directory, you can. Just create your custom version and put it in a location earlier on the search list.

Note: although dashboard add-ons are distributed as ZIP or JAR files, you should refrain from unzipping them. For example, if you were to unzip an add-on in place, it would create a new Templates directory underneath the Process Dashboard installation directory. When you upgrade the dashboard in the future and a new version of the add-on is installed, your unzipped files will be overriding the newly released materials! This will almost certainly cause serious problems, as new and old versions of files will be interacting with each other. It is fine to extract single HTML files from an add-on if you intend to customize that one file. But do not extract files that you don't intend to change, or whose purpose you don't understand.

Sharing changes with team members

If you're working with a team, and everyone on your team would like access to changes you have made to a process script, you can do the following:

1. Create a directory somewhere out on a shared network drive, called "Templates" (for example: "T:\Common\Our Team Folder\Templates" on a Windows network, or "/usr/shared/OurTeam/Templates" on a Unix network)
2. Have each person on your team add this directory to their add-on search path.
3. Put custom versions of files underneath this team templates directory. For example, you could put:
   • WAR files containing custom reports
   • HTML files overriding files that are built into the dashboard
   • LanguageFilters defining custom LOC counters
   • template.xml files defining team processes
   • Data files and HTML scripts/forms supporting those team processes
   and when you make changes to these items, everyone on the team will see them automatically (except as noted below).

Some files are only read at start up

When you change HTML files, everyone will see your changes immediately. The very next time they view the HTML page in question, they will see your changes. Other files, however, the dashboard will only read once. For example, template.xml files, datafiles, and LOC counters will only be read once, when the dashboard starts up. If you make changes to these files, people will have to shut down and restart their dashboard to see your changes.