The PDL file sample1.pdl is located in /usr/Tracker/samples and is listed in Figure 4-2.

Like all PDL files, sample1 has sections for field declarations, transition declarations, and view declarations. sample1 is a simple application, so there are no auxiliary views.

Figure 4-2. sample1 PDL File

Let's analyze the sample1 PDL file, piece by piece. For details on the meaning of each term and its use, refer to Chapter 2, “Using the Process Description Language (PDL).”

The field declaration follows:

fields {
   submitter: short-text;
   submit_date: date;
   owner: short-text
   priority: one-of LOW, MEDIUM, HIGH;
   project: one-of PROJECT_1, PROJECT_2, PROJECT_3...;
   description: long-text;
   close_date: date;
}

The sample1 PDL file has seven field declarations:

The transition declarations follow the field declarations in PDL files. Each transition declaration requires a state change declaration, which can be simply the transition operator in a declaration (=>), indicating no state change with any current state valid. Rules and actions are optional.

The transition declarations for sample1 follow:

transitions {
   SUBMIT(=>AWAITING_RESPONSE) {
      rules {
         description.isSet;
      }
      actions {
         submit_date.setValue('now');
         submitter.setValue($USER.value);
      }
   }
   RESOLVE(AWAITING_RESPONSE=>CLOSED) {
      rules {
         description.changed;
      }
   }
   REJECT(AWAITING_RESPONSE=>CLOSED) {
      rules {
         description.changed;
      }
   }
   EDIT(=>) {
   }
}

sample1 has four transitions: SUBMIT, RESOLVE, REJECT, and EDIT.

SUBMIT takes a request from a nonexistent state to AWAITING_RESPONSE. Its only rule is that there must be an entry in the description field. This is accomplished through the isSet method:

description.isSet;

SUBMIT has two actions:

The declaration

submit_date.setValue('now');

has the effect of setting the submit_date field to the value of `now', which is replaced by the current date and time.

The action declaration

submitter.setValue($USER.value);

forces the submitter field to the current user.

RESOLVE and REJECT have similar declarations. They both take a request from AWAITING_RESPONSE to CLOSED. Both incorporate one rule; the description must change. Its purpose is to cause the user to provide an explanation when resolving or rejecting the request.

The EDIT transition is open-ended in nature. The state does not change and EDIT can be applied to requests in any state. It has no rules or actions. You can declare no rules or actions with empty braces with or without the key words. In the example we simply use empty braces after the state declaration.

The view declaration for sample1 is as follows:

views {
   Sample1(){
      control-bar() {
         transitions;
      };
      qresults() {
         index $ENTITY_ID ' ', $STATE ' ', owner,
         ` submitted by `, submitter;
      };
      display() {
          row{'Report #:' $ENTITY_ID, 'Status:' $STATE,
           'Owner:' owner, 'Submitter:' submitter};
          row{'Date:' submit_date,'Project:' project,
           'Priority:' priority, 'Closed:' close_date};
          row{'Description:' ' '};
          row{description};
      }
   }
}

The example has one view called Sample1 that has declarations for a standard control bar, query results area, and request form area.

The control bar is specified to use all four transitions, since the transitions key word is used with no transition names specified.

The query results area sets up an index of the request number (equal to the $ENTITY_ID variable), the state ($STATE), owner, and submitter. In the GUI, the area is divided into four columns, each with a title indicating the type of data it displays. The data in text columns is left-justified and vertically aligned. Data in numeric columns is right-justified.

The first two rows have four fields, plus a label for each one. The first two fields, Report # and Status, are predefined. The next six fields use field declarations from the beginning of the PDL file. The string 'Description:' is used as a label, padded with trailing white space (` `), as described in the section on tuples (see “Defining a Request Form Area” in Chapter 2).

To add a field declaration, you:

A complete list of field types is provided in Table 2-1 in Chapter 2. In this example, we add a field named approver of type short-text, (see Figure 4-3).

Figure 4-3. Adding a Field Declaration

Once you have defined a field, you need to add it to the user interface, by editing the view declarations portion of the PDL file.

In this example, we add a tuple that comprises the approver field and the “Approver” label. There are currently eight short fields in two groups of four, plus the larger description field.

To keep things symmetrical, change the view to three rows of three fields each, adding the approver field last (see Figure 4-4).

Figure 4-4. Changing a View Declaration

Adding a new state is tricky because it actually changes the process. All transitions that enter or leave that state have to be changed accordingly. NEED MORE EXPLANATION

Figure 4-5 shows the state transitions of a request as sample1 was originally designed.

Figure 4-5. Original State Transitions of a Request in sample1

To implement the notion of an approval authority, you need to add an intermediate state called AWAITING_APPROVAL after the owner is through with the request, and prior to its being closed. This is shown in Figure 4-6.

Figure 4-6. State Transitions after Adding State

As a result, you need to change the RESOLVE and REJECT transitions so that instead of going from AWAITING_RESPONSE to CLOSED, they go to AWAITING_APPROVAL. The transition declarations are shown in Figure 4-7.

Figure 4-7. Transition Declarations after New State

You now need to create a new transition called APPROVE that takes a request from the AWAITING_APPROVAL state to CLOSED. To set a condition requiring the approver to add an explanation to the description for closing the request, add the rule:

description.changed;

You can also add an action:

close_date.setValue('now');

This sets the closed date to the date on which the APPROVE transition is performed. Figure 4-8 shows the transitions section after you have added the new rule and action.

Figure 4-8. Transition Declarations after New Transition