test

Sun GlassFish Web Space Server 10.0 Developer's Guide

Developing Workflows Using Simple API for Workflow in Sun GlassFish Web Space Server

The Sun GlassFish Web Space Server is bundled with the Simple API for WorkFlow (SAW) feature. This section explains about the Simple API for WorkFlow (SAW) feature and how you can develop workflow portlets using NetBeans 6.5 IDE or higher versions. The topics covered in this section are:

Introduction to SAW

SAW is a generic workflow API to perform human workflow interaction with various workflow engines. SAW provides a framework to plug-in any business process specific implementation that implements SAW interfaces. SAW is shipped with a default implementation for Sun JavaTM Composite Application Platform Suite. You can have similar SAW implementations for other business processes such as JBoss Business Process Management (jBPM) and Open Enterprise Service Bus (OpenESB).

Prerequisites

Before you build an application using SAW APIs, you must install and configure the following components:

Before proceeding with the implementation of SAW in your application, you need to configure a business process using Sun Java Composite Application Platform Suite. For more information how to create a business process in Sun Java Composite Application Platform Suite, read the article http://developers.sun.com/portalserver/reference/techart/workflow.html

Creating a Web Application Using the Drag and Drop Features in SAW plug-in

This section provides a procedure to explain how to create a simple web application in NetBeans using the drag and drop features available in SAW plug-in.

ProcedureTo Create a Web Application Using the Drag and Drop Features in SAW plug-in

  1. Click New Project in NetBeans IDE.

  2. Select Web from Categories and Web application from Projects and click Next.

  3. Enter a project name.

  4. From the Server drop down list, select GlassFish v2 and click Next.

  5. From the Frameworks list box, select the SAW plug-in.

    You can see that the Java Composite Application Platform Suite is selected by default, for the SAW implementation

  6. Click Finish.

    Tip –

    Check the SAW project web site https://saw.dev.java.net/ regularly, for updates on these implementations.

  7. Expand the Source Packages folder to see the ImplementationType.properties and WorkflowConfig.properties property files, under the default package folder.

    The ImplementationType.properties file sets the ImplementationType as Java Composite Application Platform Suite. This can be changed in future saw releases to point to JBPM, OS Workflow or other workflow Engines.

  8. Set the WorkflowConfig.properties file appropriately, to point the Java Composite Application Platform Suite Integration server.

    The web application is listed in the Projects tab and the index.jsp appears in the code window. You can see the appropriate Workflow tags listed in the Palette.

    Note –

    If the Workflow tags palette is not loaded in the NetBeans IDE, you can manually load it by clicking Tools and selecting Workflow from the Palette option. Moreover, if you right click on the web application and select Properties, the Libraries Category in the Project Properties window displays the SAW libraries that are added by the SAW plug-in in the NetBeans IDE. The current version of SAW libraries is 0.8. Check the SAW project web site https://saw.dev.java.net/ regularly for updates on the plug-in for new versions of SAW.

  9. Open the Java file in your web application.

    You can notice that the relevant Workflow APIs are listed in the palette. You can drag and drop these Workflow APIs in the Java file, depending upon the usage for your logic. In the default package, you can see various properties required by SAW to execute. These properties are the location of Sun Java Composite Application Platform Suite, SAW implementation and so on.

    Note –

    You cannot drag and drop duplicate methods. There are two ways to use the SAW APIs. One way is to use through JSP tag libraries and the other way is through the Java APIs.

  10. Edit the WorkflowConfig.Properties file to define your runtime execution environment.

    The web application is ready to deploy. The sample WorkflowConfig.Properties file is shown below:


    # the business process to use.
sawworkflowimplclass = The SAW Workflow Implementation class to use. For example,
com.sun.saw.impls.jcaps.JCAPSWorkflow
# Properties that are needed by the JCAPS Implementation of SAW.
com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverhost = machine name or IP where
Sun Java Composite Application Platform Suite business process is running.
For example, abc.india.sun.com
com.sun.saw.impls.jcaps.JCAPSWorkflow.iiopserverport =
Port on which the IIOP lookup for EJB happens. For example, 18002
com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverusername =
Administrator user name. For example, Administrator
com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverpassword =
Administrator password of JCAPS Integration server. For example, <password>
com.sun.saw.impls.jcaps.JCAPSWorkflow.contextfactory =
The context factory. For example, com.sun.jndi.cosnaming.CNCtxFactory
com.sun.saw.impls.jcaps.JCAPSWorkflow.serviceJndi =
The JNDI look up name. For example, WorkflowService
    Caution – Caution –

    Do not edit the ImplementationType.Properties file.

  11. Right click on the created web application and select Libraries.

  12. Click Add Jar and select the WorkflowServiceClient.jar from Java Composite Application Platform Suite and click OK.

  13. Right click on the web application and select Clean and Build.

  14. Right click on the web application and select Run.

    A web browser is launched and it displays the user interface defined in your web application.

Creating a SAW Portlet Using the SAW plug-in

This section explains you how to create a simple workflow portlet in NetBeans IDE using the SAW plug-in.

ProcedureTo Create a SAW Portlet Using the SAW plug-in

  1. Click New Project in NetBeans IDE.

  2. Select Web from Categories and Web application from Projects and click Next.

  3. Enter a project name.

  4. From the Server drop down list, select Open Portal Portlet Container 2.0 Beta and click Next.

  5. From the Frameworks list box, select Portlet Support and select the Create Portlet checkbox.

  6. Select the SAW plug-in and click Finish.

  7. Expand the Source Packages folder to see the ImplementationType.properties and WorkflowConfig.properties property files, under the default package folder.

    The ImplementationType.properties file sets the ImplementationType as Java Composite Application Platform Suite. This can be changed in future saw releases to point to JBPM, OpenESB or other workflow Engines

  8. Set the WorkflowConfig.properties file appropriately, to point the Java Composite Application Platform Suite Integration server.

  9. Edit the WorkflowConfig.Properties file to define your runtime execution environment.

    The sample WorkflowConfig.Properties file is shown below:


    # the business process to use.
sawworkflowimplclass = The SAW Workflow Implementation class to use.
For example, com.sun.saw.impls.jcaps.JCAPSWorkflow
# Properties that are needed by the JCAPS Implementation of SAW.
com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverhost = machine name or IP
where Sun Java Composite Application Platform Suite business process is running.
For example, abc.india.sun.com
com.sun.saw.impls.jcaps.JCAPSWorkflow.iiopserverport =
Port on which the IIOP lookup for EJB happens. For example, 18002
com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverusername =
Administrator user name. For example, Administrator
com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverpassword =
Administrator password of JCAPS Integration server. For example, <password>
com.sun.saw.impls.jcaps.JCAPSWorkflow.contextfactory = The context factory.
For example, com.sun.jndi.cosnaming.CNCtxFactory
com.sun.saw.impls.jcaps.JCAPSWorkflow.serviceJndi = The JNDI look up name.
For example, WorkflowService

  10. Change the portlet Java and the JSP files in your web application accordingly, to write the portlet.

    You can notice that the relevant Workflow APIs are listed in the palette that you can drag and drop in the Java file, depending upon the usage for your logic.

  11. Right click on the created portlet application and select Libraries.

  12. Click Add Jar and select the WorkflowServiceClient.jar from Java Composite Application Platform Suite and click OK.

  13. Right click on the web application and select Clean and Build.

  14. Right click on the web application and select Run.

    The portlet gets rendered on the portlet container.

Deploying the Workflow Portlet an Open Source Portlet Container

You need to deploy the Workflow portlet in order to work with the Workflow API. This section provides a procedure to explain how to deploy the workflow portlet on Open Source Portlet Container.

ProcedureTo Deploy the Workflow Portlet on Open Source Portlet Container

  1. Download the workflow portlet from the SAW project web site https://saw.dev.java.net/.

  2. Extract the workflowPortlet.war into a local directory using the jar -xvf workflowPortlet.war command.

  3. Modify the WorkflowConfig.properties file in the \workflowPortlet\WEB-INF\classes directory by providing suitable values to the following properties:

    • sawworkflowimplclass = com.sun.saw.impls.jcaps.JCAPSWorkflow. This means that you are using SAW Workflow implementation class, JCAPSWorkflow.

    • com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverhost = machine name or IP address, where Sun Java Composite Application Platform Suite business process is running. For example, abc.india.sun.com.

    • com.sun.saw.impls.jcaps.JCAPSWorkflow.iiopserverport = port on which the IIOP lookup for EJB happens. For example, 18002.

    • com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverusername = Administrator user name. For example, Administrator.

    • com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverpassword = Administrator password. For example, xxx.

    • com.sun.saw.impls.jcaps.JCAPSWorkflow.contextfactory = The context factory. For example, com.sun.jndi.cosnaming.CNCtxFactory.

    • com.sun.saw.impls.jcaps.JCAPSWorkflow.serviceJndi = The JNDI look up name. For example, WorkflowService.

  4. Modify the workflowportlet.properties file in \workflowPortlet\WEB-INF\classes directory by providing appropriate values to the properties. The sample workflowportlet.properties file to deploy on Portlet Container is shown below.

    authenticationRepository = accessManager. Specify the authentication repository that is used.

    Note –

    accessManager is the default value that is provided for authenticationRepository in the workflowportlet.properties file. Only if you want to deploy the .war file using the Open Source Portlet Container, then change the authenticationRepository value to appServer.

  5. Ensure that you have the client stubs (WorkflowServiceClient.jar) generated out of the workflow service, deployed on Sun Java Composite Application Platform Suite. Copy this to \workflowPortlet\WEB-INF\lib directory by using the cp WorkflowServiceClient.jar workflowServiceClient-1.0.jar command.

  6. Recreate the .war file using the jar —cvf command.

  7. Deploy the Workflow portlet using the admin tab of the Portlet Server Administration Console.

    To deploy the workflow portlet on Open Source Portlet Container:

    • Create a user under admin-realm of GlassFish V2 or Application Server 9.1, on which the Open Source Portlet Container is running. For example, create a user, CPina in the admin-realm of GlassFish V2.

    • Login to the GlassFish V2 admin.

    • Navigate to Configuration -> Security -> Realms.

    • Click admin-realm and Click Manage Users.

    • Add CPina, group list : asadmin and passowrd as CPina.

    • Access the portlet by typing http://machine:port/portal/dt in a web browser.

    • Log in as user, CPina. The tasks that are assigned to CPina will be displayed on the workflow portlet.

    If it is a web application, then the saw-api-0.6.jar should be in the appropriate classpath. The saw.tld, saw-impl-jcaps-0.6.jar, and WorkflowServiceClient.jar should be bundled with the application.

  8. Modify the jreHome\lib\logging.properties file. To do this, update the java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter property. The logging levels can be configured here. For example, INFO, ERROR and so on.

    Note –

    You need not modify the logging.properties file in the case of OpenPortal. For stand alone Java applications, you need to modify the logging.properties file to specify the type of format and the level of log.

Deploying the Workflow Portlet on Sun GlassFish Web Space Server

You need to deploy the Workflow portlet in order to work with the Workflow API. This section provides a procedure to explain how to deploy the workflow portlet on Open Portal 7.2.

ProcedureTo Deploy the Workflow Portlet on Sun GlassFish Web Space Server

  1. Extract the workflowPortlet.war into a local directory using the jar -xvf workflowPortlet.war command.

    Note –

    The workflow portlet is available in the Sun GlassFish Web Space Server install under the /opt/sun/portal/portlet/ directory for Linux and /opt/SUNWportal/portlet/ directory for Solaris. You can also download the workflow portlet from the Portlet Repository http://wiki.java.net/bin/view/OpenPortal/PortletsInTheRepository.

  2. Ensure that you have the client stubs (WorkflowServiceClient.jar) generated out of the workflow service, deployed on Sun Java Composite Application Platform Suite. Copy this to \workflowPortlet\WEB-INF\lib directory by using the cp WorkflowServiceClient.jar workflowServiceClient-1.0.jar command.

  3. Recreate the .war file using the jar —cvf command.

  4. Deploy the Workflow portlet using the admin tab of the Portal Server Administration Console.

    To deploy the workflow portlet on Open Portal:

    • Create a channel with this portlet provider and add it to one of the tab

    • Click the created new channel created and change the following portlet preferences:

      • sawworkflowimplclass = com.sun.saw.impls.jcaps.JCAPSWorkflow. This means that you are using SAW Workflow implementation class, JCAPSWorkflow.

      • com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverhost = machine name or IP address, where Sun Java Composite Application Platform Suite business process is running. For example, abc.india.sun.com.

      • com.sun.saw.impls.jcaps.JCAPSWorkflow.iiopserverport = port on which the IIOP lookup for EJB happens. For example, 18002.

      • com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverusername = Administrator user name. For example, Administrator.

      • com.sun.saw.impls.jcaps.JCAPSWorkflow.appserverpassword = Administrator password. For example, xxx.

      • com.sun.saw.impls.jcaps.JCAPSWorkflow.contextfactory = The context factory. For example, com.sun.jndi.cosnaming.CNCtxFactory.

      • com.sun.saw.impls.jcaps.JCAPSWorkflow.serviceJndi = The JNDI look up name. For example, WorkflowService.

      Note –

      accessManager is the default value that is provided for authenticationRepository in the workflowportlet.properties file. You need not change this property, if the portlet is deployed on Open Portal.

  5. Create a user with userId as CPina in Access Manager with the status as active. Assume that the Business process assigns the newly created tasks to this user.

  6. Access the portlet by typing http://machine:port/portal/dt in a web browser.

  7. Log in as user CPina. The tasks that are assigned to CPina will be displayed on the workflow portlet.

    Only in the case of Open Portal, the saw-api-0.6.jar should be available in the server classpath. If it is a web application, then the saw-api-0.6.jar should be in the appropriate classpath. The saw.tld, saw-impl-jcaps-0.6.jar, and WorkflowServiceClient.jar should be bundled with the application.

Using the Workflow Portlet

  1. Login to the Portal Server 7.2 desktop (http://portalmachine:port/portal) with username and password as CPina.

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

    • First section — Search Criteria section, where the user can mention the criteria based on which the tasks have to be filtered and displayed.

    • Second section — Task List section that displays all the tasks that match the search criteria of a user.

    • Third section — Displays the buttons, which are the operations that can performed on any task.

  3. The search criteria section has the following attributes using which the user can filter tasks:

    • Start Date and End date - Filter tasks based on a valid start date and end date.

    • TaskIds - If the user knows the taskids, then the user can enter them in the text area that is separated by commas.

    • UserIds - Filter tasks based on the current owner of the task.

    • Task Status - Filter tasks based on the status of the task. For example, pending or completed.

    • GroupId - Filter tasks based on the group id. For example, Vice President Marketing and so on.

    • Flex String Type - Filter tasks based on a flex string type. For example, flexString1, flexInt1, flexDouble1 and so on.

    • Flex String Value - The value of the flex string type that is selected by the user.

  4. When the user clicks the Search button, tasks are filtered based on the search criteria that the user has entered and displayed in the "Task List" section.

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

  6. Assume that a new task is allocated to the user "CPina". Then “CPina” can do the following operations on the task that is assigned:

    • EXECUTE - Select the task and click the Execute button. A new page for executing a task is displayed. This 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 the Save button. These values get updated for the task. On executing, the task gets checked out on the name of the logged in user (CPina), who 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 will be displayed.

    • COMPLETE - Select the task and click 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.

    • CHECKIN - Select the task and click 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.

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

    • ESCALATE - Select the task and click 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.

    • REASSIGN - Select users from the Reassign selected task to drop down, and click 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.

    • DELETE - Select the task and click 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.

  7. 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.

  8. Any Error messages are displayed in the top of the portlet in red font.

  9. Any confirmation messages are displayed in the top of the page in blue font.

  10. The attributes that can be modified using the portlet preferences are the noOfrecords and the executeJSP. You need to click the edit mode to change the values for the portlet preferences.

  11. All the messages that are displayed are internationalized.

References

For more information on SAW implementation, refer the following resources: