Composite Application Workflow (hereafter called Workflow) is an IBM WebSphere Portal V22.214.171.124 (hereafter called WebSphere Portal) facility for creating and running workflows inside portal composite applications. Users can create and manage individual workflow definitions, whether they have programming skills or not, using tools provided by WebSphere Portal. Users of composite applications that run in WebSphere Portal can define, customize, and run their own workflows to meet their individual business needs.
The workflow facility originally shipped as a Tech Preview in WebSphere Portal V6.0, and is fully supported beginning with WebSphere Portal V126.96.36.199. The core workflow engine used for running portal workflows is Business Process Choreographer (BPC), which is actually a component of WebSphere Process Server. WebSphere Portal Extend also includes the BPC component and a limited license for using BPC within WebSphere Portal.
This article first describes how to enable the Workflow component in WebSphere Portal. Then, it shows how to use the workflow design and runtime components to implement a simple document approval workflow scenario.
Getting started with Workflow
Because Workflow relies on Business Process Choreographer (BPC) to run, you must first have BPC installed on the WebSphere Portal server you plan to use. On a standalone WebSphere Portal configuration, you can perform the necessary configuration while installing WebSphere Portal by simply answering "Yes" to the question "Do you want to install business process support ?" in the WebSphere Portal install wizard.
Running the configuration task
After installing and properly configuring the prerequisite, you need to run the Workflow configuration task to enable Workflow. Use the following command from the
config directory under the WebSphere Portal installation root:
WPSConfig.bat configure-workflow –DWasPassword=<was_password> - DPortalAdminPwd=<wps_password>
./WPSConfig.sh configure-workflow –DWasPassword=<was_password> - DPortalAdminPwd=<wps_password>
You can specify the appropriate passwords in the
wpsconfig.properties file instead of the command line. For more information on running the workflow configuration task, see the Enabling workflow for use with a composite application topic in the WebSphere Portal InfoCenter.
Workflow is now ready for use.
The document review scenario
In this scenario, a user (the document author) creates a document draft and submits it for approval by another user (the document reviewer). The reviewer can either accept the draft, which then becomes the final version of the document, or reject it and propose changes to the document. If the draft is rejected, the document is returned to the author for changes and re-submission, until it is accepted by the reviewer.
Figure 1. The document review workflow scenario
Designing the workflow using the Builder portlet
The Workflow Builder portlet is the design component of workflow. It enables users to create workflows by defining tasks, transitions, actions and roles using drop down boxes and text fields within the Builder portlet UI. No programming skills or familiarity with enterprise level process modeling tools (for example, WebSphere Integration Developer) are required to do this.
The following sections will show how to implement the document review scenario using the Workflow Builder portlet.
Opening the Workflow Builder portlet
Each workflow definition must be attached to a WebSphere Portal composite application (or composite application template). In the example scenario described in this article, you create an empty composite application; however, you can attach a workflow definition to any existing application. For more information on composite applications and templates in WebSphere Portal, see Composite applications.
To begin the scenario, you create the Document Review composite application, and then you open the Workflow Builder portlet to design the document review workflow.
Important: By default, access to some features of composite applications is not permitted to non-administrative users. To perform the actions described in this article, you must be allowed access to the composite application template and application libraries, and you must be allowed to create an application.
- Log into WebSphere Portal
- Open the Launch menu, and click on Templates.
- Open the Application Library page.
- Click on the New button.
- In the Name field, type a name such as
Document Review Application.
- In the Template dropdown, select Portal Blank Template.
- In the Description field, you can optionally enter a description for the application.
- Verify the input is correct, and then click OK.
- Back in the Application Library, find the application you just created, and click on it to open it.
- After the application is opened, open the context menu of the Blank Page and click Edit Application Workflow (see figure 2).
Figure 2. The page context menu
The Workflow Builder portlet opens. It is composed of a row of buttons (actions available to the user) and 2 tabs: the Basic tab and the Tasks tab.
Setting the workflow basic properties
In the Basics tab you can set the generic properties of the workflow you are designing: a name, an optional description, the user roles that provide the rights to start and administer workflow instances, and whether to enable or disable the workflow.
Figure 3. The Workflow Builder portlet Basics tab
Enter a name for the workflow, such as
Document Review. You can also optionally enter a description for the workflow.
The next step is to assign roles to start and administer the workflow instances. Instead of directly assigning tasks to individual users, WebSphere Portal lets you assign tasks based on the specific set of roles created when the workflow is designed. A role represents a responsibility in the workflow being designed. Two roles interact in the example document approval process: the author role and the reviewer role.
To create roles which are allowed to start and administer the workflow:
- Click on the blue twisty next to "Who can start this workflow?" (see Figure 4)
- Click the New button to open the Define new role panel.
Authorin the Role name field.
- Enter an optional description for the role, such as
The person who writes and edit the documentin the Description field.
- Verify the input and click OK.
- Click on the blue twisty next to "Who can start this workflow?"
- Check the Author role that has been added to the list, and uncheck All Members.
- Click the OK button.
Figure 4. The role pop-up box
You have created the Author role and enabled it to start the workflow. When the workflow runs, all users assigned to the Author role will have the right to start the workflow.
Repeat the same task; this time create a role named
Reviewer and assign it to administer the workflow (that is, use "Who can administer this workflow?").
Creating the tasks of the document approval workflow
In the Tasks tab of the Builder portlet, you can add tasks (or steps) to your workflow. You specify that each task is either a Manual Task (the task will be manually initiated by a user) or an Automated Task (the server automatically runs a predefined action), and you set its properties.
Specify the task, name, and description
The document approval workflow contains two tasks:
- Editing the document (before it is submitted), which is performed by the author
- Reviewing the document, which is performed by the reviewer
The following section shows how to create these two tasks and how to set their basic properties (name and description).
- A manual task named "Untitled Task 1" is created by default. Change its name to
Edit Draftin the task name field.
- Enter a description for the task. The description should instruct the user how to complete the task; for example:
Edit the document draft, attach it as related content and submit the draft by clicking the Submit button.
- Click on the New Task button located above the tasks list on the left side (see Figure 5.) to create a second task.
- Change its name to
Review Draftin the task name field.
- Enter a description for the task, such as:
Review the document draft. Click on the approve button to approve the draft as is. Click on the return document button to return the document to the author for further editing.
Figure 5. The task list and basic task properties
Specify the transitions, page, and role assignments
Next you create the transitions between the two tasks; that is, you indicate how the tasks are organized in the workflow and how the flow transitions from one task to another. You also specify the task page used to run the task, and you provide role assignments for the tasks.
- In the task list (Figure 5.) on the left side, click the Start task.
- In the Select the first task drop down, select Edit Draft to specify that the first task to be executed in the workflow is the draft editing and submission task.
- In the task list, select the Edit Draft task.
- A workflow action named Complete Step is defined by default. Change its name to
- In the Next Task drop down, select Review Draft. After the draft is submitted, the workflow will transition to the draft review task.
- Click on the New Task Page button in the lower part of the form. WebSphere Portal creates a new portal page, named after the task (Edit Draft), to render the task.
- Assign a role for the potential task owner; the task owner is the person who performs the task. In the case of the draft editing task, the task owner is the author. Click the blue twisty, check the Author role in the drop down for "Who can own this task?", and de-select the other roles.
- Assign a role for the potential task editor. The task editor can change the data associated with the task (the document), but cannot complete the task. Click the blue twisty, check the Author role, and de-select all other roles.
- Assign a role for the potential task editor. The task reader can read the data associated with the task (the document), but cannot complete the task. Click the blue twisty, check the Author role, and de-select all other roles.
- In the list of task, select the Review Draft task.
- A workflow action named Complete Step is defined by default. Change its name to
- In the Next Task drop down, select Stop. After the draft is approved, the workflow is complete and will stop.
- Now you need to define another action to enable the draft to be returned.
- Click on the New Workflow Action. A new action named Complete Step is created. Change its name to
Returnand the name of the corresponding Next Task to
Edit Workflow. If the document is returned, the workflow will transition to the editing task so that the author can modify the draft.
- Click on the New Task Page button in the lower part of the form. WebSphere Portal creates a new portal page named after the task (Review Draft) to render the task.
- To assign a role for the potential task owner, click the blue twisty next to "Who can own this task?", check the Reviewer role, and de-select the other roles. (See Figure 6.)
- To assign a role for the potential task editor, click the blue twisty next to "Who can edit this task?", check the Reviewer role, and de-select all other roles.
- To assign a role for the potential task reader, click the blue twisty next to "Who can view this task?", check the Reviewer role, and de-select all other roles.
You have finished creating the tasks and designing the document approval workflow. The tasks panel should look like Figure 6.
Figure 6. The task property panel
- Click on the Save button to save the workflow definition into the composite application.
Running the document review workflow
The Workflow runtime consists of four portlets, rendering different information and letting the user perform various actions on workflows and associated tasks. In this part of the article, you see how to use them to run the document approval workflow you have just designed.
First, you need to pick the people you want to interact in the workflow, and specify the role in which you want them to interact (author or reviewer).
So far, the actors of the workflow are represented by abstract roles, not real users. You must assign people to those roles so that they can participate in the workflow. This assignment requires two steps:
- Map the workflow roles (author, reviewer) to composite application roles.
- Assign new application members to the composite application roles.
Map workflow roles to composite application roles
Composite applications provide their own roles to which workflow roles must be mapped. For this example, and for simplicity, we use the two default roles created in any composite application: administrator and user. We map the author workflow role to the composite application user role, and the reviewer role to the administrator one.
Note that in a real life scenario, you would probably need to create new composite application roles; however, those considerations are beyond the scope of this article. For more information regarding composite applications, please see the Composite applications section of the WebSphere Portal InfoCenter.
To map the author workflow role to the user composite application role:
- Open the context menu of the Blank Page and click Manage Application Roles (see figure 2.). The Roles portlet opens.
- Click on the Users role.
- As shown in Figure 7, in the Pages and Components Access Settings window, select the level of access of the Document Review component (the workflow you just designed) as: Author (The person who writes and edit the document).
- For all the portlets, change the level of access to: User (Users are allowed to view portal content).
- Click OK.
Figure 7. The Pages and Components Access Settings section of the Roles portlet
- Perform the same task for the Administrators application role and the Document Review component. This time select the level of access as: Reviewer (The person who reviews the document). Leave the portlets access level set to Manager. You have finished mapping the two roles.
- Click the Done buttonto close the Roles portlet.
Add members to the composite application
Now that workflow roles are mapped to composite application roles, you add new members to the application and assign them to one of the application roles (user/author or administrator/reviewer).
To perform this task, use the Membership portlet.
- Open the context menu of the Blank Page and click Assign Application Members, as shown in Figure 2. The Members portlet opens.
- Click on the Add button, and select the Add Users option in the drop-down menu.
- The people picker portlet opens. Pick one or several user(s) and click OK.
- Click the Done button.
- You have just added one (or more) member(s) as "User(s)" of the application. Because you mapped the composite application role "User" to the workflow role "Author" role in the previous step, the members you just added to the application have all the rights you granted to the "Author" role when you designed the workflow; that is, they can start the workflow and complete the "Edit Draft" task.
- Similarly, all members that you add to the application as "Administrator" have all the rights you granted to the "Reviewer" workflow role, because the "Administrator" role is mapped to the "Reviewer" role. In this example, we did not add any members as administrators because, as the creator of the application, you are automatically added as an administrator.
Starting the workflow in the Workflow List portlet
- Log in to WebSphere Portal as one of the members you just added to the application.
- To open the application, in the Launch menu, select Templates. Then open the Application Library page, click on the Document Review Application, and open the Document Review page. You see the Workflow List portlet.
Figure 8. The Workflow List portlet
The Workflow List portlet displays information about the workflow currently running in this application. It provides access to the current task in the workflow (if you have access to it). It also provides a way to start new instances of the workflow, delete completed workflows, and to claim and un-claim tasks.
Now you will start a new instance of the document review workflow.
Because you are logged in as one of the members you added to the application in the "User" role (which is mapped to the "Author" workflow role), you have the right to start a new workflow. (The New button is enabled.)
To start a new workflow:
- Enter a unique name for the new workflow instance, such as
- Click on the New button.
The "Contract proposal" workflow starts. You might need to switch to the All Tasks views to see it. It show in the Workflow List portlet, along with the current task, Edit Draft. Depending on how many users you added to the application, the task may or may not be claimed; if only one user can claim the task, it is claimed automatically for him. If the task is claimed, it shows as a clickable link; otherwise, it displays as plain text.
To claim and open the Edit Draft task:
- Check the checkbox for the Contract Proposal workflow.
- Click on the Claim button. The task displays as a clickable link.
- Click on the Edit Draft link in the row for the Contract Proposal workflow.
- The task page opens so you can work on the edit draft task. On this page, because you are the document author, you can submit the document draft for review. The page displays two portlets: the current task portlet and the related content portlet.
Completing a task using the Current Task portlet
The Current Task portlet displays information about the currently opened task, as well as buttons for the possible actions the user can take, as defined when the task is designed.
Figure 9. The Current Task portlet
In the document approval scenario, you created only one action for the edit draft task, "Submit", which transitions the workflow to the review draft task. As a result, there is one button, labeled Submit in the current task portlet for the Edit Draft task. If you click this button, the task will complete and the workflow will transition to the Review Draft task. You will complete the task later after you have attached the draft document to the workflow using the Related Content portlet. (See the next section.)
Attaching content using the Related Content portlet
Every workflow instance carries related content, in the form of a set of documents that is propagated together with the workflow as the workflow proceeds. The content can be accessed in the context of a task by the task owner and the task editors. Documents can be added by directly uploading them from the local file system or by referencing existing documents in a portal document library.
Figure 10. The Related Content portlet
You will now attach the draft of the document that you, the author, wrote and want to get reviewed.
- In the Related Content portlet, click the Add Content button.
- Enter a title for the document in the Title filed, such as
Draft contract 1.
- In the File to add field, select File System in the drop down, and browse to select the document to add (the draft contract proposal).
- You can optionally enter a description for the document.
- Click the Add button. The draft of the contract proposal is attached to the workflow as related content, and is ready for submission. It will be available in all subsequent workflow tasks through the related content portlet.
- Click the Submit button in the current task portlet to complete the task.
Working with tasks using the Task List portlet
The Task List portlet displays task information in a table, and lets users claim, un-claim, and open tasks. It presents different views to the user through a tree. Task details are available by clicking the Details button.
It does not present any information about workflows; in this regard, it differs from the Workflow List portlet presented earlier in the article.
Important: Unlike the other Workflow runtime portlets, the Task List portlet is not automatically inserted into an application when a workflow is added to the application. You must add it manually in the composite application (or the template) using the composite application Edit Layout portlet.
Figure 11. The Task List portlet
Moving the workflow forward
The detailed steps presented above have shown you how to start a new document review workflow, open its first task (edit draft), and complete it. At this stage, the workflow has moved to the Review Draft task.
You can perform the same set of steps again to complete the Review Draft task. Log in as the user who created the application. You will be assigned the "Reviewer" role; you can then claim the new task, open it, use the related content portlet to retrieve the document draft, and then either approve or reject it.
If it is approved, the workflow is finished (it will show in the "Completed" view of the workflow list portlet); if it is rejected, a new "Edit draft" task is created for the author to re-work his draft and resubmit it, and so on until the draft is approved.
This article introduced you to the Composite Application Workflow feature in WebSphere Portal. You learned how to enable it, and how to access and use its various components, both at design time and at run time.
You can now leverage Composite Application Workflow to implement your own collaborative business processes, such as a vacation time request process between an employee and manager, or a workflow to manage technical support requests opened by customers and handled by various technical representatives.
- Participate in the discussion forum.
- Building composite applications and templates in WebSphere Portal V6 describes how to create composite portal applications.
- WebSphere Portal V6 product documentation provides access to the most current documentation available for all releases, in all languages.
- WebSphere Portal zone provides a wide variety of technical resources to help you build and extend your own portals.
- WebSphere Process Server InfoCenter provides access to the current product documentation for WebSphere Process Server.
- WebSphere Process Server and WebSphere Integration Developer provides a wide variety of technical resources to help you create business process applications.
- What's new in WebSphere Portal Version 6? describes the new features and capabilities for Version 6 of WebSphere Portal.
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.