Defining legacy process templates for use in the Process Dashboard

Important Note

The instructions below describe how to build customized XML process templates. But these templates are now considered legacy functionality, because they have a number of serious limitations. For example, they cannot be modified without invalidating historical data, and they can only be used for personal work, not by teams.

Fortunately, custom workflows in team/personal projects do not have those limitations. Accordingly, users are strongly encouraged to create a team or personal project, then use workflows in their WBS to define custom processes.

The instructions below are provided for long-time users who need to maintain their legacy XML process templates.

The dashboard has been designed from the ground up to support custom processes. The PSP scripts and forms that you see are not hard-coded into the tool. Instead, they are dynamically loaded from simple HTML and text files. Thus, it is possible to create your own custom process scripts, forms, and data that will be dynamically integrated into the dashboard.

The dashboard process definition framework provides a great deal of power for process automation. To create a custom personal process definition, just follow these steps:

  1. Identify your process structure
  2. Create an XML definition for your process
  3. Save your XML process descriptor
  4. Restart the dashboard

Step 1: Identify your process structure

What steps do you want to include in your process? The standard PSP0 process, of course, includes the phases Planning, Design, Code, Compile, Test, and Postmortem. Think through your process and decide upon the list of phases that your process will include.

Think this through carefully. Remember how you had to restart your "To Date" data when you graduated from PSP1.1 to PSP2? The same truth applies here. Once you have defined a custom process and used it in the dashboard, even slight changes to the process definition will invalidate all your historical data. In fact, once you create a process definition and use it to perform a project, you can no longer even change the names of the phases without losing historical data.

If your process definition is still immature and evolving, it is probably better to use the Generic process for a while. As you begin creating your own custom process definitions, the flexibility of the generic process will allow you to radically change your process from one task to the next in response to process improvement proposals. Once you decide upon and finalize the list of phases in your process, you are ready to begin using a custom process.

Some guidelines to consider as you identify your process phases:

Don't subdivide things too far. Take a look at the PSP processes, for example. They will define a single phase like Planning, even though it contains several different steps (obtain requirements, make size estimate, make resource estimate, create schedule, etc.). The PSP process definition does not break each of these steps into its own phase! Herein lies the difference between a phase and an activity. By carefully defining the high level phases in the process, Watts Humphrey was free to incorporate process improvements simply by altering the set of activities in each phase. Remember also that when you enact your process, you will have to collect time and defect data with phase-level granularity. If you break your process up into a zillion tasks that each take only a minute, you will go crazy just trying to log time accurately. Therefore, if your custom process contains more than a dozen phases, it's most likely subdivided too far.

Here's another way to think about this: the dashboard is a useful tool because it seamlessly integrates your process script and your metrics collection framework. By tying the two things together, you have all the tools you need at your fingertips to enact the process. But as a result, this means that when you create a custom dashboard process, you must understand and think about your custom process from both perspectives. Many people are able to easily think up a script for their process, but you must also take time to think about your metrics collection framework. The phases you choose in your custom process define the "buckets" in your metrics collection framework. If you choose these phases thoughtfully, it will allow room for your process to grow and improve. On the other hand, if you choose phases that correspond one-to-one with activities in your process, you may find that your custom process quickly becomes obsolete.

Choose abbreviations for long phase names. When you write your process script, you may have phases with verbose names like "High Level Design Review". Realize that if you use this long phase name, the main dashboard window is going to stretch halfway across your screen whenever you navigate to that phase. An abbreviation like "HLD Review" may be more appropriate. You can still refer to the phase by its unabbreviated name when you create your HTML process scripts and forms.

Include Planning and Postmortem phases. In his book, Watts Humphrey encourages you to always include these phases in any process you define. The planning phase serves an obvious purpose of estimating size, cost, schedule, risk, etc. The postmortem phase allows you to ensure accurate collection of data and capture process improvement proposals.

Step 2: Create an XML definition for your process

The dashboard understands a process structure that is described in XML format. The discussion below assumes that you are familiar with XML. If this is not the case, please go read a nice tutorial on XML before proceeding!!

Here is an example of an XML description file for a PSP0 process:

<?xml version='1.0'?>

<dashboard-process-template>
   <template name="PSP0" defectLog="true">
      <phase name="Planning"   type="plan"/>
      <phase name="Design"     type="dld"/>
      <phase name="Code"       type="code"/>
      <phase name="Compile"    type="comp"/>
      <phase name="Test"       type="ut"/>
      <phase name="Postmortem" type="pm"/>
   </template>
</dashboard-process-template>

The file begins and ends with the header and footer (which appear in blue above). Between the header and footer, any number of process templates can be defined. (The file above only defines one process template.)

A process definition begins with the <template> tag and ends with </template>. The template tag must have a "name" attribute, and all of the processes you define must have unique names. Also, template names cannot contain the "/" character. If you will be collecting defects with your process, you should include the "defectLog" attribute as shown above (and remember that XML is case-sensitive, so "defectlog" will not work).

Between the <template> tags, list the phases in order. Each phase is described with a <phase> tag. The phase tag must have a "name" attribute, and all of the phase names must be unique. As was true of template names, phase names cannot contain the "/" character. The phase type can optionally be specified with the "type" attribute. The following is a list of valid types that can be specified:

Phase types are not required. Even if you specify the phase type for one phase, you can omit it for others. If you do specify phase types, the dashboard will be able to intelligently calculate metrics like Yield, A/FR, and Defect removal efficiency.

Step 3: Save your XML process descriptor

Once your XML process descriptor is complete, it is time to save it somewhere where the dashboard can find it. Follow these steps:

  1. Choose " → Help → About," and click the "Configuration" tab. Just above the list of add-ons, a paragraph will tell you where the Process Dashboard is installed. Find that directory on your computer. It should contain a small number of files, including one called "pspdash.jar".
  2. Underneath this directory, create a subdirectory called "Templates".
  3. Save your XML process descriptor in that Templates directory. Important: you must give your XML process descriptor a filename ending with "-template.xml" to signal to the dashboard that this is an XML process template descriptor. If you do not choose a filename ending with "-template.xml", your process descriptor will be ignored.

This is the simplest place to put your XML process descriptor. Of course, if you want to share your process with team members, you may want to put it somewhere else. See the section on how the dashboard finds process files for more information. Keep in mind that the dashboard will search for "-template.xml" files in the "Templates" directories only - subdirectories will not be searched.

Step 4: Restart the dashboard

Once your XML process descriptor is in place, it is necessary to shut down the dashboard and restart it for the new process to be found. Once found, you will automatically have:

Advanced/Optional: Defining HTML scripts

Defining HTML scripts for your process and its phases is easy to do. Here is an example of an XML description file for a PSP0 process, with HTML script definitions added. The text in blue is identical to the example shown in step 2 above; the black text illustrates the additions:

<?xml version='1.0'?>

<dashboard-process-template>
   <template name="PSP0" defectLog="true"
             htmlID="top">
   
      <html ID="sum"
            title="Project Plan Summary"
	    href="dash/summary.shtm"/>
      <html ID="top"
            title="PSP0 Process Script"
	    href="psp0/script.html"/>
      <html ID="plan"
            title="PSP0 Planning Script"
	    href="psp0/planning.html"/>
      <html ID="dev"
            title="PSP0 Development Script"
	    href="psp0/develop.html"/>
      <html ID="pm"
            title="PSP0 Postmortem Script"
	    href="psp0/postmort.html"/>

      <phase name="Planning"   type="plan"
             htmlID="plan"/>
      <phase name="Design"     type="dld"
             htmlID="dev"/>
      <phase name="Code"       type="code"
             htmlID="dev"/>
      <phase name="Compile"    type="comp"
             htmlID="dev"/>
      <phase name="Test"       type="ut"
             htmlID="dev"/>
      <phase name="Postmortem" type="pm"
             htmlID="pm"/>
   </template>
</dashboard-process-template>

So right after your <template> tag, you list all the HTML pages that you want to appear on the script button's drop down menu, in order. (Note that you don't have to list every HTML page used by your process - just the ones that you want to appear on the script button menu.) For each HTML page, you state:

Then you (optionally) associate these HTML pages with the phases by adding an htmlID attribute which names the ID of the HTML page associated with that phase. You can have HTML pages that aren't associated with any phase, and vice versa. You can even associate an HTML page with the <template> tag, as shown above; then any phases which don't specify an htmlID of their own will inherit that htmlID.

Of course, before the dashboard will be able to open any of these HTML pages, you must actually create them and place them appropriately underneath the "Templates" directory. You can use your favorite HTML editor to create these pages; if you have a program like Microsoft Word, it is capable of saving files in HTML format. Since the hrefs are interpreted relative to the "Templates" directory, for this example we would need to create a directory called "psp0" underneath the "Templates" directory, and put files in that directory called "script.html", "planning.html", "develop.html", and "postmort.html".

The file "dash/summary.shtm" is special. It names an HTML file that is shipped with the dashboard. When you don't name any HTML files for your process, the dashboard assigns it "dash/summary.shtm" by default. (This is why you could create an XML template file, specify no HTML files, and still get a project plan summary form automatically.) However, as soon as you include <html> tags in your template definition, the dashboard will no longer automatically assign it "dash/summary.shtm", so you must manually include this entry to ensure that you can view a plan summary form for your process.

Additional Advanced Topics

That should be enough to get you started! For more advanced questions, send email to the development team at processdash-devel@lists.sourceforge.net.