WORKFLOW PORTLET - USER GUIDE

What is the Workflow Portlet?

The Workflow Portlet is a sample portlet that shows how to implement Workflow functionalities using SAW ( Simple API For Workflow ). 
SAW is a generic workflow api to perform human workflow interaction with various workflow engines. 
SAW provides an easy framework to plugin any business process specific implementation that implements the SAW interfaces.
The portlet demonstrates how to use the SAW APIs and SAW Taglibs.

Abbreviations Used

• SAW - Simple API for Workflow

• JCAPS - Sun Java Composite Application Platform Suite

• BP - Business Process

• API - Application Programming Interface

Basic Terminology

• Task - Unit of execution requiring human interaction

• CheckOut Task - To take ownership of the task for execution

• CheckIn Task - Relinquish ownership of the task

• Reassign Task - Assignment of a task assigned to an individual A to individual B by individual A

• Delete Task - delete the task from the task queue

• Save Task - Provide input to the task

• Complete task - Act on a task and mark status as completed

• Pending task- A task which requires attention and is incomplete

• Business Process - Sequence of processess in a business function

• User Activity - Acitivity in due course of a business function requiring human intervention

What's in this release

1. workflowPortlet.war - The workflow portlet WAR file.

Pre-requisites

1. Supported JDK versions are

   1. 5 and above

Deploying the Portlet

1. Extract the workflowPortlet.war into a local directory.

2. Modify the < jreHome > \lib\logging.properties like this.

   1. Update the following property - java.util.logging.FileHandler.formatter =java.util.logging.SimpleFormatter

3. The logging levels (like INFO,ERROR, etc) can be configured here.

4. Modify the WorkflowConfig^?.properties file in \workflowPortlet\WEB-INF\classes directory giving suitable values to the following properties.

   1. businessProcess = com.sun.saw.impls.jcaps.JCAPSWorkflow(This means that we are using JCAPS business process and the implementation class is JCAPSWorkflow.)

5. logFileLocation = E:\\work\\jaw\\logs\\log.txt(The location where the log file has to be created.)

6. Modify the JCAPSWorkflowConfig^?.properties file in \workflowPortlet\WEB-INF\classes directory giving suitable values to the following properties.

   1. appserverhost = <machine name / IP where JCAPS business process is running Eg. abc.india.sun.com >

7. appserverport = <port on the appserverhost where JCAPS business process is running Eg. 18002>

8. appserverusername = <Administrator user name. Eg. Administrator>

9. appserverpassword = <Administrator password. Eg. STC>

10. contextfactory = <The context factory. Eg. com.sun.jndi.cosnaming.CNCtxFactory>

11. serviceJndi = <The JNDI look up name. Eg. WorkflowService^?>

12. Modify the workflowportlet.properties file in \workflowPortlet\WEB-INF\classes directory giving suitable values to the following properties.

    1. authenticationRepository = <authenticationRepository possible values are accessManager / appServer>. If the deployment is on Open Portal, then the value should be accessManager. If the deployment is on Open Source Portlet Container (OSPC), then the value should be appServer.

13. pagination.numberofrecords = <number of tasks to be displayed in the workflow portlet page.>

14. Deploying the portlet.

    1. Deploying the portlet on Open Portal

       1. Create a user with userId "CPina" in Access Manager (AM) with "active" status. Assume this is the user to which the Business process assigns the newly created tasks to.

15. Deploy the portlet and create the JSR 168 workflow channels and containers.

16. Access the portlet like this. http://machine:port/portal/dt. Log in as CPina, and the tasks assigned to this user would be displayed on the workflow portlet.

    1. Deploying the portlet on Open Source Portlet Container

       1. Create a user under admin-realm of glassfish/AS9.1(on which the OSPC is running) :ex: CPina in the admin-realm of glassfish/AS9.1

17. Login to the glassfish admin -> under configuration -> security -> Realms -> click on admin-realm and click on Manager users button , add CPina, group list : asadmin and passowrd as CPina.

18. Access the portlet like this. http://machine:port/portletdriver/dt. Log in as CPina, and the tasks assigned to this user would be displayed on the workflow portlet.

19. The saw-api-0.2.jar should be available in container classpath if its a web-app.If not, then the saw-api-0.2.jar should be discoverable. The saw.tld, saw-impl-jcaps-0.2.jar and WorkflowServiceClient^?.jar should be bundled with the application.

Using the Portlet

1. As soon as the user logs in, all the tasks assigned to the user are displayed. The page has three sections.

   1. The first section is the Search Criteria section where the user can mention the criteria based on which the tasks have to be filtered and displayed.

2. The second section is the Task List section that displays all the tasks that match the user's search criteria.

3. The third section displays the buttons which are the operations that can performed on any task.

4. The search criteria section has the following - ie the user can filter the tasks based on the following:

   1. Start Date and End date - filter tasks based on some valid start date and end date.

5. TaskIds - if the user knows the taskids, he / she can enter them in the text area seperated by commas.

6. UserIds - filter the tasks based on the current owner of the task.

7. Task Status - filter tasks based on the status of the task like pending or completed.

8. GroupId - filter tasks on the group id. eg VP Marketing

9. Flex String Type - filter tasks based on some flex string type eg. flexString1, flexInt1, flexDouble1

10. Flex String Value - The value of the flex string type that was selected.

11. On click of Search button, tasks are filtered in based on the search criteria that the user has entered and displayed in the "Task List" section.

12. The "Clear" button clears any of the search criteria that the user has entered / selected.

13. Assume a new task is allocated to the user "CPina" . The user can do the following operations on the task that is assigned to him.

    1. EXECUTE - Select the task and click on the "Execute" button. It shows a new page for executing a task.
       That page shows the input for the task in a text box and flex string in another text box. The user can update both the text boxes and click Save button.These values get updated for the task.
       On executing, the task gets checked out on the name of the logged in user ie CPina is the current owner of this task. Currently the task can be executed only once. This is because, on execution, the task is checked out, and a task can be checked out only once by a given user. If the user tries to execute the second time, then "Task Exception" error message would be displayed.

14. COMPLETE - Select the task and click on the "Complete" button. Now the status of the task is marked as completed. The user has to be the current owner for performing this operation on this task.

15. CHECKIN - Select the task and click on the "CheckIn" button. This operation is opposite of check out.the currently logged in user is not the current owner now. The user has to be the current owner for performing this operation on this task.

16. HISTORY - Select the task and click on the "History" button. On clickin this, the task history is shown in a new jsp. All operations that were performed on the task is displayed. Click "Back" button on the task history jsp to come back to the task list page.

17. ESCALATE - Select the task and click on the "Escalate" button. On clicking this, the task gets assigned to the manager of the currently logged in user.The user has to be the current owner for performing this operation on this task.

18. REASSIGN - Select users from the "Reassign selected task to" drop down, and click on the "Reassign" button, the task gets assigned to these users.The user has to be the current owner for performing this operation on this task.

19. DELETE - Select the task and click on the "Delete" button. On this operation, the task is deleted. The user has to be the current owner for performing this operation on this task.

20. Pagination support is provided for the Task List. On the first page the "Previous" link is not displayed. On the last page, the "Next" link is not displayed. On all the other pages, both the "Previous" and "Next" link is displayed.

21. Any Error messages are showed in the top of the portlet in red font.

-- Main.vihang - 15 Jan 2008