Project Open Advanced Workflow Part 3: Arcs and Guards
Revised March 31, 2011
Terrance A. Crow
Project Open ships with a powerful workflow editor that lets you control how a ticket is processed. The workflow editor operates in one of two modes: Simple Process and Advanced Process. This tutorial will cover the Advanced Process.
I’ll break down the Advanced Process tutorial into these parts:
- Tasks and Places
- Roles and Responsibilities
- Arcs and Guards
- Automatic Processes
- Adding to Helpdesk Ticket Types
- Adjusting Dynfields
This section will cover Arcs and Guards.
To successfully run this tutorial, you’ll need:
- A working installation of Project Open 126.96.36.199.1; 188.8.131.52.0c should work as well.
- A Project Open administrator ID
My Project Open installation runs on CentOS 5.5 Linux. The examples should run on any installation of Project Open, though. I used Apple’s Safari (under OS X 10.6.7) to capture the screen shots.
Arcs and Guards
If you remember all the way back to Part 1, you’ll recall that we used Arcs to connect Places to Tasks and Tasks to Places. That means you have a head start on this part of the tutorial — you already know how to create Arcs!
Now, I’m going to show you how add Guards to Arcs. Guards let you ask questions — usually true/false questions — within a workflow, then branch the workflow according to the answer.
Our example workflow, called Sample 001, has these Tasks and Places:
- Start (Place)
- Open Ticket (Task)
- Ready to Assign Ticket (Place)
- Assign Ticket (Task)
- Ready to Work Ticket (Place)
- Work Ticket (Task)
- Ready to Close (Place)
- Close Ticket (Task)
- End (Place)
You can display these Places and Tasks in the graphical workflow editor by following these steps:
- Log into Project Open as a PO Admin
- Click on the Admin tab
- Click on Workflow URL
- Find and click on the name of your workflow (ours is Sample 001)
- Click on the URL called graphic process editor
You should see something like the screen in Figure 1.
Figure 1: This is the Simple 001 workflow as shown in the graphical workflow editor.
As it stands, the workflow starts at S and goes from Task to Place to Task to Place until it hits E. There’s no deviation; every workflow is the same.
Let’s say that we want to add a conditional branch after Work Ticket. Let’s give the folks who work the ticket the ability to say that they didn’t finish and that ticket needs to be reassigned to someone else.
In the context of Sample 001, that’s the same as saying we need to add an Arc between the Task named Work Ticket and the Place called Ready to Assign Ticket. Then, we’ll add two Guards to handle the decision of which Arc to follow.
First, click on the Task that’s going to prompt for a decision. In our case, that’s the Task called Work Ticket.
In the HTML table near the top, you should see a URL to “add arc.” If you click on it, all of the Tasks should go gray. Click on the Ready to Assign Ticket Place to complete the Arc. Your screen should look like the one in Figure 2.
Figure 2: We’ve added a decision point at the Work Ticket Task.
If we tried to use this workflow now, it wouldn’t work. Project Open wouldn’t know how to process the decision point; it wouldn’t know to which Arc to send the workflow. We can fix that by adding two Guards: one that will be executed if the guard’s answer is yes and one to execute if it’s no.
If you notice, the Work Ticket Task is still highlighted (it’s blue). Take a look at the HTML table cell called “Output Places.” You can see it in Figure 3.
Figure 3: Under Output Places, you can see the option to add Guards.
Output Places lists two destinations, both of which are Places: Ready to Close Ticket and Ready to Assign Ticket. We’ll execute these steps to define the Guards that’ll control the work’s flow to either of those Places:
- Define a Guard for the Ready to Close Place that’ll prompt the person working the ticket if they’re ready to close the ticket; if they answer yes, the Guard will push the workflow through the Arc leading to the Ready to Close Place.
- Define another Guard to handle any case that the other Guard doesn’t handle; which is to say, if the person working the ticket says no.
Adding a Guard is itself a three step process:
- Create the Guard; if the Guard includes a question/prompt, give it a description and name
- Create an Attribute to define both the question that’ll be displayed to the person working the ticket and the default answer to that question
- Associate the Attribute with the Task in question (in our example, the Task called Work Ticket)
Start by clicking on the URL add guard under the Ready to Close Ticket Place “Output Location” as seen in Figure 3. You should see a screen like the one in Figure 4.
Figure 4: This screen lets you define a Guard.
I’ll fill out the fields like this:
- Plaintext description: This defines the text that will display on the graphical editor and in the graphical representation of the workflow that shows in the ticket. I’ll enter “Ready to close ticket?”
- Guard condition: This tells the Guard how to respond to the yes or no question. There are two options: wf_callback__guard_attribute_true (yes, there are two underlines after callback) or “No other guards were satisfied.” Since this Guard will handle an affirmative answer, I’ll set it to wf_callback__guard_attribute_true.
- Optional argument: This should really be called “Optional argument if this is the ‘No other guards were satisfied’ Guard Condition.” This becomes the key to the Attribute name we’ll use later. I’ll enter ready_to_close_yes.
Clicking Update should display a screen like the one in Figure 5.
Figure 5: We’ve successfully created the first Guard — the one to handle a “yes” answer.
Now that we’ve defined how the workflow should respond to a yes, let’s define how the workflow will respond to a no response. Under the “Output Place” Ready to Assign Ticket, click on the URL for add guard. The screen should look much like the screen from Figure 4. This time, we only need to set one field: Guard condition. Set it to “No other guards were satisfied.” Since there’ll be no question to display to the person working the ticket, we don’t need to setup the Attribute.
Click Update to see a screen like the one in Figure 6.
Figure 6: Both Guards are now defined.
Notice that the “text” for the second Guard is just “[#]”. This is the workflow editor’s way of showing that a Guard exists, but there’s no prompt or Attribute with it.
Now we come to an interesting set of behaviors in the workflow editor: we need to switch to the text-based editor to add the Attribute’s definition. At least, that’s the only way I’ve found to do it.
Follow these steps:
- Since we’re in a browser, there’s no need to disrupt our existing screen. Right-click on Project Open’s Admin tab and select your browser’s option to open the selection in a new browser tab.
- Switch to that new browser tab.
- Click on the Workflow URL.
- Find and click on your workflow’s name (our is Sample 001).
- You should see a screen like the one in Figure 7.
Figure 7: This is the text-based editor’s start page.
From here, click on the “tab” called Attributes. The screen should now look like the one in Figure 8.
Figure 8: We’re ready to define an Attribute now.
You can probably guess that the next step is to click on the URL add attribute. When you do, you’ll see a screen like the one in Figure 9.
Figure 9: This screen lets you define an Attribute.
Remember that we entered ready_to_close_yes as the “optional” argument when we defined the first Guard earlier? That’s what we need to enter as the “Name” here.
For “Pretty Question”, enter the question just as you want it to appear to the person going through the workflow. I’ll enter “Is the work done and are you ready to close the ticket?”
Without the quotes, of course.
I’ll leave Datatype set to its default of boolean.
Finally, for the Default Value, I’ll enter true and click on the button Add. The screen should now look like the one in Figure 10.
Figure 10: The Attribute for ready_to_close_yes is almost ready to use!
There’s one step left before this has a chance of working. If you switch back to the browser tab that holds the graphical editor, you should see three options in the upper left: assignment, attributes, and actions.
Click on the URL for attributes to see a screen like the one in Figure 11.
Figure 11: This screen lets you associate the question with the Task.
Since we only have the one Attribute defined, it’s pre-selected for you in the combo-box. If we were building a more complex workflow, you might have to open the combo-box to find the Attribute you’re looking for. Notice that the combo-box displays the value from the field “Pretty name (question).”
Click on the Add button. The screen should now look like the one in Figure 12.
Figure 12: The Attribute is now ready to use!
The Attribute should now be ready to use! Click on Done to return to the graphical workflow editor.
Notice that we only have to define the question and default answer for the affirmative Guard. It’s the one that’ll execute the stored procedure wf_callback__guard_attribute_true. The other Guard will fire if the answer to the question is not true; in other words, if the answer is false.
Honesty, understanding Guards took me more time than I care to admit. For whatever reason, it just didn’t make sense to me. It was only after I had dug around the PostgreSQL tables that I could see where the design was coming from, and it started to make sense. The power’s there — it just takes a little extra effort to get to it!
So, as of the end of part 3, our workflow has Tasks and Places, it has Roles and Responsibilities, and it has Arcs and Guards. In Part 4, I’ll look at how to automate processes like closing the ticket.