Workflow Guide
|
|
Workflow Guide |
This chapter provides an interactive demo of a sample workflow application (Issue Tracking) and a look at the application sources. It has these sections:
You have an existing Director EAR project in Workbench or know how to create and deploy one. If you need help, see the Quick Start section of Getting Started.
For a general introduction to workflow terminology and building a workflow application in Director, see
Basic Workflow Development.
Issue Tracking is a sample workflow application that simulates a bug tracking system for a software development project. It consists of an issue creation and resolution process associated with three authorized users called support, dev, and qa. The issue life cycle is defined in a workflow process that specifies an activity for each user. Each activity is associated with a specific workitem (in this case a property sheet) that the user completes.
How the application works The support user starts a new process and completes the first workitem. This workitem consists of a form where the user describes the issue, indicates whether the issue is a bug, and forwards it to the next activity. The status of the bug property determines the next workitem. If it's a bug, it goes to the dev user's workitem queue; if it's not a bug, it goes back to the support queue. If the dev user marks the bug as fixed and forwards the work, a new workitem is added to the qa user's queue. When the qa user verifies the fix, the issue is considered resolved and the process instance is complete.
Each user has a single workitem for each issue, but multiple issues can be running at the same time. The Workflow engine manages the routing of activities for each process instance. In the case of multiple instances, the user can select which workitem to access from the workitem queue.
Issue Tracking is packaged as a Web archive (WAR). You can use Workbench to add it as a subproject to an existing Director EAR project.
If you need help creating a Director EAR project, see the Quick Start section of Getting Started. Use the Typical setup option.
To add Issue Tracking to your EAR project:
From the main menu in Workbench, select Project>Director EAR>Setup.
On the next panel navigate to the Issue Tracking template directory in your Director install:
Director_install_dir/Samples
Click Next. Click Yes on the popup that asks if you want to use the Samples template.
On the next panel, select Issue Tracking.
A message informs you that the install will configure your project to use the Issue Tracking resource set for the Security and Workflow subsystems. When you are finished with he application you can change the setting back to the original configuration by editing the config.xml descriptors for the Workflow and Security services and redeploying the EAR.
For more information, see the section on binding subsystems to a resource set in the Core Development Guide.
Workbench adds the Issue Tracking WAR to your EAR project and executes a build. This will take a couple of minutes, after which you should see the IssueTrackingSample at the bottom of the Navigation Pane:
The Issue Tracking application is configured for the engine to start automatically with your application server. Now take a look at the configuration setting.
To configure the workflow engine to start automatically:
In the Service Entries list, click Engine.
In the Startup dropdown, automatic should be selected by default. If it is not selected, select it now.
In Workbench, open the project that contains the application WAR.
Select Deploy Archive from the Project menu.
Workbench deploys the WAR to your server. This process takes a couple of minutes. When the deployment is completed you're ready to run the application.
To run Issue Tracking you need to add the support, dev, and qa users to your server's directory realm. The application provides a servlet for doing this.
NOTE If you prefer, you can use your server administration tools to add the three users described in the next procedure.
To add users to your server realm using DirectoryInitServlet:
Open a browser and open this URL in your EAR project:
http://server name/DirectorDB/project name/IssueTracking/DirectoryInitServlet
This executes the servlet that adds the users and returns a confirmation message in the browser. The following users are added:
|
User |
Password |
|---|---|
|
support |
support |
|
dev |
dev |
|
qa |
qa |
This section provides an interactive demo of the Issue Tracking application. You will create a couple of workflow processes and complete the workitems in each one. This requires you to open three separate browsers and log in as each of the authorized workflow users as described in About the Issue Tracking application.
Open a browser and navigate to Issue Tracking in your project:
http://server name/DirectorDB/project name/IssueTracking/main
This displays the process start component and workitem queue for the support user:
The browser displays two components; the start process component on the left and a workitem queue (which is empty) on the right. Before starting a process, you need to log in as the other two users.
Open two more browser instances and log in as:
The dev and qa user pages display the workflow queue component, but not the start process component—which in this application can only be accessed by the support user. Component access is determined by a security role descriptor, described in the table in How the application was built.
Resize or minimize the browsers so you can easily access each one.
In the support workitem Start Process box, select Issue Tracking from the dropdown list.
Note that this is the only option available. If other workflow process definitions had been defined in the WAR, they would display in this list.
A new workitem appears in the support user's workitem queue:
Here is how each button works:
To complete a support user workitem:
Select the workitem and click View Item.
This displays a form for the support user to enter information about the new issue. Here is how each button works:
Click Save and Forward to Development.
Note that this item is removed from the support queue.
To start another process and complete the workitem:
To complete a dev user workitem:
The two items forwarded by the support user appear in the dev queue:
Select the first issue and click View Item.
This opens the workitem window. It includes the data entered by the support user. Notice the button at lower left labeled Forward to QA.
Note that the button label changes to Forward to Support.
Change the bug status back to Yes and click Forward to QA.
Note that this item is removed from the dev queue.
To complete the other dev item:
Select the remaining item in the dev queue and click View Item.
Click No for the bug status and enter the following in the Comments box:
It's a feature!
Go back to the support browser and click Refresh.
The forwarded item appears in the support queue.
To complete a qa user workitem:
The first item forwarded by the dev user appears in the qa queue.
Select the item and click View Item.
This opens the workitem window. It includes data entered by previous users. Notice the button at lower left labeled Save and Forward to Development. This is the process path when the fix approved status is No.
Change the status to Yes and click Save and Forward as Completed.
This closes the issue and removes the item from the qa queue.
(Optional) Create other items and experiment with the application. You can close the browsers when you're finished.
The basic components of the application are:
Workflow process: a visual map of the workflow process that consists of activities and links defined in the Workflow Editor. The workflow process is stored as an XML file.
Workflow client: custom Java code that uses the workflow APIs to interact with the process and the Workflow engine. To build the client the Issue Tracking application uses a combination of Director components and JSP pages.
Most of the application sources are in JAR files at this disk location:
project_name/IssueTrackingSample.war/WEB-INF/lib.
|
Application source/ |
Description |
|---|---|
|
Issue Tracking Process.xml |
Process definition created using the Workflow Designer. |
|
IssueTrackSupportUsers.xml |
Security role descriptor. This defines user access to the IssueTrackStartProcess component.
|
|
activitypolicy.xml |
Specifies the client type and source for each workitem. |
|
IssueTrackTechSupport.jsp |
JSP page that defines the workitem for the support user. Uses a JavaBean called techSupportIssue.java. |
|
IssueTrackDevelopment. |
Portal component that defines the workitem for the dev user. |
|
IssueTrackQA.jsp |
JSP page that defines the workitem for the qa user. This page uses the Workflow JSP tag library.
|
|
WorkflowStartProcess |
Workflow subsystem core component that starts a process selected by the user. Uses WorkflowStartProcessDefault.xsl. |
|
WorkflowQueue |
Workflow subsystem core component that lists the available workitems for a user. Uses WorkflowQueueDefault.xsl. |
|
LoginComponent |
Portal subsystem core component used to authenticate users. |
|
ITCheckLogin |
Component that verifies that the user has logged in to the application. |
|
UserDisplay |
Component used to display the current user for demo purposes. |
The process definition for this application was defined using the Workflow Designer, a graphical tool that allows you to lay out a workflow process. This section shows how the process is defined.
To open the process xml in the Workflow Designer:
In Workbench, open Issue Tracking Process.xml in your EAR project:
IssueTrackingSample/IssueTracking.spf/resource.spf/data/workflow-process/Issue Tracking Process.xml
IssueTracking.war/WEB-INF/lib/resource.jar/workflow-process/Issue Tracking Process.xml
The process opens in the Workflow Designer.
If necessary, use the scroll keys at the top and side of the window to center the graphic, as shown here:
A workflow process begins and ends with a Start activity and a Finish activity, represented by the green and checkered flag icons respectively. You place activities on the Designer palette and draw links between them. There are different types of activities and links you can use. The Issue Tracking process defines three User Activities that are linked with XOR link types.
For information about using the tool, see
Workflow Designer.
To look at the process properties:
With the cursor anywhere on the Designer palette, right-click and select Properties.
The Name property is a unique reference to this process. The Role property lists security roles authorized to create workitems with this process.
To look at an activity's properties:
Select the tech support activity.
A colored border means the item is selected.
Right-click and select Properties, then select the Activity tab.
The Name property specifies a unique reference for this activity.
Select the link labeled issue assigned (not the label itself).
The color of the arrow changes to show it is selected.
Right-click and select Properties, then select the Destination tab.
Note the addressee and expression boxes.
Click on the data in the Expression box.
This displays the expression editor. Here the editor says send work to the dev user if the isbug property is true.
The Workflow Designer does not create properties; this is done in the workitem code. However, the workitem can access a property value that is specified in the Designer. You will see how this works with the isbug property later in the chapter.
Click Cancel to close the editor, but leave the properties window open.
Select the link labeled cannot reproduce/need more info.
Note that the default box is checked in the property editor. This means that this path will be followed if no other path evaluates to true.
Click on the data in the Expression box.
The expression editor says send work back to support if the isbug property is false.
(Optional) Click other items in the editor and examine the property sheets.
TIP When finished, leave the process open in Workbench; you may want to look at it again in the course of the discussion that follows.
The Issue Tracking workflow client was built with a combination of Workflow subsystem core components and workitem code specific to this application. The core components are:
Each workitem uses the workflow API to interact with the workflow process. A workitem can be written as a portal component or JSP page: the IssueTracking application illustrates the use of both implementations.
The Issue Tracking client implements classes in the com.ssssw.wf.client package. Click the class name below to access API documentation:
|
Class name |
Used to |
|---|---|
|
Instantiate a workflow engine delegate and a workflow context |
|
|
Start an Issue Tracking process |
|
|
Define workitem properties |
|
|
Get workitems and forward work to the next activity |
WorkflowStartProcess is a Director core component that can be used in any workflow application. It uses methods on EbiWorkflowEngineDelegate to get a list of process definitions in the project resource set and allows the user to start a process instance.
To access the source for WorkflowStartProcess:
In Workbench openWorkflowStartProcess.java from the following location:
Take a few moments to scan the code, then navigate to this segment (50):
NOTE The number in parentheses is the approximate line number in the file. To turn on line numbering click View > Line Numbers on the main menu.
// Get a list of processes
getRequestParameters( context );
wf_context = asWFContext( context );
EbiWorkflowEngineDelegate m_engineDelegate = com.sssw.wf.client.EboFactory.getWorkflowEngineDelegate();
m_doc = m_engineDelegate.getProcessDefinitions( wf_context );
The component instantiates an engine delegate using EboFactory.getWorkflowEngineDelegate.
Next the code calls getProcessDefinitions() on the engine delegate, passing the workflow context object. The workflow context is derived from the portal context using a local method, asWFContext().
The getProcessDefinitions() method returns a Document defined by org.w3c.dom./document. The Document contains the XML definition of the workflow process. The DTD is located in your project at library/WorkflowService/DTD/workflow-process.dtd.
Scroll down to this code (72):
if( !isProcessListEmpty( m_doc ) ) {
context.setContentType( EbiComponentConstants.MIME_TYPE_XMLDOM );
context.setComponentContent( m_doc );
This code sets the content type and returns the DOM as the content.
Scroll back up to this code (56):
if( m_start ) {
m_start = false;
// The user has asked to start a process
m_engineDelegate.startProcess( m_processID, wf_context );
}
WorkflowQueue is a core component that displays a list of available workitems for a user. It queries the workflow engine and gets a list of available workitems in a running process. It displays the items in a dropdown list and gets the workitem selected by the user.
This component uses code logic that is similar to that of WorkflowStartProcess component.
To access the source for WorkflowQueue:
In Workbench, openWorkflowQueue.java from the following location:
Take a few moments to scan the code, then navigate to this segment (50):
EbiQueueDelegate m_queueDelegate = com.sssw.wf.client.EboFactory.getQueueDelegate();
Scroll down a couple of lines to this line:
m_doc = m_queueDelegate.getWorklist( wf_context );
Scroll down to this code (75):
context.setContentType( EbiComponentConstants.MIME_TYPE_XMLDOM ); context.setComponentContent( m_doc );
private void unlock( EbiContext context ) {
try{
EbiQueueDelegate queue = com.sssw.wf.client.EboFactory.getQueueDelegate();
EbiWorkitemDelegate delegate = queue.getWorkitem( getWID( m_workitemID ), context );
delegate.unlock( context );
}
catch( Exception e ) {
// An exception means this user cannot unlock this item
m_wrongUser = true;
}
}
This code calls getWorkitem(), passing in the workitem ID. This value is returned by a local method that parses the workitem selected by the user.
The workitem class associated with getWorkItem() is specified by user in the activitypolicy.xml. For example, if you are logged in as the dev user, getWorkList() calls the IssueTrackDevelopment component.
For more information, see
Binding an activity to a client.
Finally, the code calls unlock() on the queue delegate. This allows the user to access the workitem. When accessed a workitem is automatically locked for that user until the user closes the file or forwards work to the next activity.
The Issue Tracking application defines workitem properties for each workflow user. In the case of the support user, the application implements a JSP page and a supporting bean class.
To access the bean source for the support JSP page:
You might also want to access the JSP page source to follow the code discussion.
(Optional) To access the source for the JSP page:
In Workbench, open techSupportIssue.java from the following location:
In the bean source navigate to this code segment (70):
public void setWfid( String newWfid , HttpServletRequest request, HttpServletResponse response)
{
try {
m_wfid = newWfid;
EbiQueueDelegate queue = com.sssw.wf.client.EboFactory.getQueueDelegate();
com.sssw.wf.api.EbiContext WFcontext = com.sssw.wf.client.EboFactory.createEbiContext(request, response);
m_delegate = queue.getWorkitem( m_wfid , WFcontext);
}
catch( Exception e ) {
e.printStackTrace();
}
}
This code shows how to instantiate the basic objects you need to define workitem properties.
First the code stores the workitem ID passed in from the JSP page. This value is derived from the WorkflowQueue component.
The code uses a factory method to instantiate a queue delegate.
The code calls another factory method to get a workflow context object, passing in the servlet request and response.
Using the queue delegate, the code gets the workitem, passing in the workitem ID and the context. It stores the delegate as a global variable so it can be accessed from other class methods.
try {
EbiProperty isbugProp = null;
EbiProperty issueidProp = null;
EbiProperty issuenameProp = null;
EbiProperty companynameProp = null;
EbiProperty issuedescProp = null;
EbiProperty commentsProp = null;
m_workitemID = request.getParameter( "wfid" ).trim();
m_issueid = request.getParameter("issueid").trim();
m_issuename = request.getParameter("issuename").trim();
m_companyname = request.getParameter("companyname").trim();
m_issuedescription = request.getParameter("issuedescription").trim();
m_isbug = request.getParameter("isbug").trim();
m_comments = request.getParameter("issuecomments").trim();
//EbiWorkitemDelegate delegate = queue.getWorkitem( m_wfid, context );
if( m_delegate.hasProperty("isbug")) {
isbugProp = m_delegate.getProperty("isbug");
isbugProp.setPropertyValue(m_isbug);
}
else {
isbugProp = (EbiProperty) new EboProperty("isbug", m_isbug, EbiProperty.TYPE_BOOLEAN, false);
}
...
The code instantiates an com.sssw.wf.ap.EbiProperty for each workitem property.
Next the code uses the workitem delegate to store the property values. First it tests to ensure the value exists, and creates it if it doesn't. Existing values are derived from the JSP page and stored locally. This code shows the value being set for the isbug property.
m_delegate.setProperty(isbugProp, context); m_delegate.setProperty(issueidProp, context); m_delegate.setProperty(issuenameProp, context); m_delegate.setProperty(companynameProp, context); m_delegate.setProperty(issuedescProp, context); m_delegate.setProperty(commentsProp, context);
The code sets each property. Properties defined as EbiProperties are stored in XML as defined in the workflow-workitem.DTD.
Locking a workitem The lock() method locks a workitem for the current user. This prevents conflicts between multiple users authorized to access a workitem. This method must be called before the user can update the workitem.
public void lockWorkitem(HttpServletRequest request, HttpServletResponse response)
{
try {
EbiQueueDelegate queue = com.sssw.wf.client.EboFactory.getQueueDelegate();
com.sssw.wf.api.EbiContext WFcontext = com.sssw.wf.client.EboFactory.createEbiContext(request, response);
getStrings(m_delegate);
m_delegate.lock( WFcontext );
}
catch( Exception e ) {
e.printStackTrace();
}
}
The code again uses createEbiContext() as described earlier to get the workflow context, and passes it to the lock() method. Before locking the workitem, it calls a local method getStrings() to set the current workitem properties.
Forwarding a workitem Each workitem calls the forward() method to forward work to the next activity in the process.
private void forwardWorkitem( EbiQueueDelegate queue ) {
try {
queue.forward( m_delegate );
}
catch( Exception e ) {
e.printStackTrace();
}
}
The forward() method is called on the queue delegate. The forward destination is determined by the property value specified in the process definition. In this case, if the isbug property is true, the work goes to the dev user. Otherwise, it stays in the support worklist. The forward() method automatically unlocks the workitem for the next user.
The Workflow subsystem allows you to define a client type and class association for each workitem. The client is specified as an URL in a descriptor called activitypolicy.xml.
NOTE This file name is hard-coded and should not be changed.
To access the activity policy descriptor for Issue Tracking:
In Workbench open activitypolicy.xml from the following location:
IssueTrackingSample/IssueTracking.spf/resource.spf/data/workfllow-activity-policy/activitypolicy.xml
IssueTracking.war/WEB-INF/lib/resource.jar/workfllow-activity-policy/activitypolicy.xml
<?xml version="1.0"?>
<activitypolicy>
<activity name="TechSupport">
<client type="portal" uri="/jsp/issueTrackTechSupport.jsp">Portal</client>
</activity>
<activity name="Development">
<client type="portal" uri="/main/comp/IssueTrackDevelopment">Portal</client>
</activity>
<activity name="QA">
<client type="portal" uri="/jsp/issueTrackQA.jsp">Portal</client>
</activity>
</activitypolicy>
The activity name element value must match the name defined in the workflow process. The client type URL is specified as portal for each of the activities. This means that each workitem uses Director portal presentation services for the client UI. Currently this is the only client type supported.
The client type attribute specifies the client type and the location of the workitem class file.
The activity policy feature allows you to define other client types (such as a Java client) and specify its URL in this descriptor.
For more information, see
Binding activities to client types.
The Workflow subsystem includes core portal components for Workflow administration.
To access WorkflowAdminClient:
In your browser go to the URL for WorkflowClientAdmin:
server name/DirectorDB/project name/web application name/main/component/WorkflowAdminClient
The Client Administration Panel displays, where you can change the status of a process and get information about process activities:
Select the Issue Tracking process from the Process Pane.
Information about the process activities in the Activities Pane displays. An activity status can be:
With the process selected, click Terminate Process.
This terminates this process instance.
To access WorkflowEngineAdmin:
In your browser go to the URL for WorkflowClientAdmin:
server name/DirectorDB/project name/web application name/main/component/WorkflowEngineAdmin
The Engine Administration Panel displays where you can start, suspend, or shut down the engine and queue:
This shuts down the engine and queue.
For more information about the administration components, see
Workflow Administration.
|
|
Workflow Guide |
Copyright © 2002, SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.