Introduction

Business Automation Workflow provides several features to use BPMN processes for Case Management solutions activities.

While it’s still possible to implement Case Management activities with FileNet processes in order to assure the compatibility with the solution built with IBM Case Manager, they can also implemented with BPMN processes including the possibility to use Coach Views in Case pages and to interact with the case instance from the BPMN process that implements the case activity.

Following this recipe you’ll create and run a simple case solution with the following elements:

• two properties;
• one role;
• one Process Activity Details page which includes the coach view UI;
• one case type.

The case type will execute only one Activity based on a BPMN process composed by three sequential steps:

• two Server-side task steps that will interact with the case using the JavaScript case operations for:
  • updating the case properties;
  • adding comments to the case;
  • complete the case stages.
• one User task implementing the coach view UI that will be shown in the Case client page.

So go ahead with the recipe and have fun!

Login to the the Workflow Center

Open the Workflow Center in your web browser and login with a user authorized to design case management solutions.

The Workflow Center URL is tipically like this: https://servername:port/WorflowCenter

Create a new case solution

From the Workflow Center homepage you can start building Case solutions and Process apps. For this recipe we are going to create a new Case solution.

Click the Create + button in the Case solutions box.

Enter the solution name, check the Open in Designer box if needed and click Create

The Business Automation Workflow builder opens to the solution you just created

Create the solution properties

As the first thing, we need o add the following two properties to the solution:

• Amount (type: Integer)
• Request Status (type: String)

Select the Properties tab and click Add Property > New

 To create the Amount property type Amount in the Name field and select Integer as Type and click OK:

Do the same for the Request Status property.

Here are the properties list once you finished creating them:

Creating the properties, do not forget to write down the Request Status property Unique Identifier, you’d need them later in the recipe. If you can find it clicking the name of the property and look for the Request Status field.

Create a role

In a real-life case solution you usually need more than one role, but for the sample solution we’re building in this recipe, one role is enough.

Select the Roles tab and click the Add Role button.

Name the role Sample Role and click OK.

Create a process activity detail page

Case pages are the Case Management solution element that allow users to process the user task steps included in the activity processes. Business Automation Workflow provides several types of pages, the page type needed for case activities implemented by BPMN processes is the Process Task Details Adapter page.

In this step we just create the page cloning the one provided by default, we’ll design it later in the recipe adding some case widgets .

Select the Pages tab.

Expand the Task Details Pages section and create a new copy of the Process Task Details Adapter page clicking the last button on the right.

Type Sample Process Task Details as the page name and click the OK button.

The Sample Process Task Details page is now listed in the TaskDetails Pages list.

dd a new case type to the solution

Select the Case Types tab and click the Add Case Type Button.

Name the new Case Type Sample Case.

Click Save at the top right corner of the window, all the job done until now is in a safe place!

Add the solution properties to the case type

Now let’s add the case created in the solution to the case type.

Select the Properties tab on the left, then click Add Property, choose Existing, click Select All and then OK.

You’ve added the solution properties to the case type.

Add the case stages

Case Stages helps case users to quickly understand where a case is in a given moment. Let’s add two stages to the case type:

• Request Created
• Request Completed

To create the stages select the Stages tab on the left and click the Add Stage button.

For each stage fill the name and click OK.

Your stages should appears as below.

Create an activity based on a BPMN process

As mentioned in the recipe introduction, the case type will execute one activity based on a BPMN process, so let’s create it.

Select the Activities tab on the left, click the Add Activity button and choose Activity with New Process.

Name the activity Request Approval, scroll down and set the Process Task Details Adapter with the work details page you created at step 6 (you should named it Sample Process Task Details). The page specified in the Process Task Details Adapter is the page tha will be presented to the end users to work on the user task steps defined in the process.

Click OK and then Save (top right corner).

Add some case widgets to the process activity page

Open the Sample Process Task Details page created at step 6 going back to the Pages tab in the solution definition.

You see that the page contains only two widgets:

• the Task Toolbar widget which displays header information about a process activity instance;
• the Client-Side Human Service Viewer widget that displays the content of the process activity (the coach view of the user task steps).

Let’s now add to the page a couple of case widgets:

• the Case Stages widget (to show the user the current stage of the case);
• the Case Information widget (to show the case documents, activities and history).

Your page should appears as following:

Design the activity process

You’re now ready to design the process for the Request Approval activity. The process definition will include three sequential steps that will be execute in the following order:

1. a Server Script step
2. a User Task step
3. another Server Script step

Open the process in the Web Process Designer clicking the first button on the right of the activity.

Delete the Inline User Task step included in the default process diagram.

Add a Server Script step dragging it from the palette on the right to the diagram

Double click on the step and rename it as Update Request Status, connect the Start step with the Server Script step.

Add a User Task step from the palette

Connect the Server Script step to the User Task step and rename the latter as Request Approval

Add another Server Script step, call it Update request status. Connect the Request Approval step to the Server Script and connect it to the End step.

You’re done designing the process, you’ll implement the steps later.

Save the process clicking the Finish editing button on the top right of the Web Process Designer.

Add a variable to the process

In order to update the requestStatus property value from the coach view implemented in the User Task step, a variable in the process must be created.

Select the Variables tab and click the plus (+) button to add a Private variable.

Name the new variable RequestStatus typing the name in the Details pane on the right

Once you added the requestStatus variable, the Variables pane should appears like this:

Add the Javascript code to the server script steps

Let’s now add some Javascript code to the Server Script steps to interact with the case instance from the BPM process.

Both the scripts execute the following operations:

• set the Request Status property stored in the case with the current value;
• move the case to the next stage;
• add a comment to the case.

While the first operation is just a property assignment, the other ones require an interaction with the case and are done using the case operations provided by the TWProcessInstanceParentCase class included in the Javascript APIs.

To add the script code to the Server Script steps go back to the process diagram selecting the Definition tab.

Select the first Update Request Status step and select the Script tab in the bottom section of the window.

Copy the following code and paste it in the Script text area:

//Set the RequestStatus case property to "Approval in progress"
tw.local.caseProperties.RequestStatus.value = "Approval in progress";

//Move to the next case stage
tw.system.currentProcessInstance.parentCase.completeCurrentStage(true);

//Add a comment to the case
tw.system.currentProcessInstance.parentCase.addCommentToCase("The request approval will begin shortly.");

Select the last Server Script step and copy the following code in the Script text area:

//Set the case property variable in the current status
tw.local.caseProperties.RequestStatus.value = tw.local.requestStatus;

//Move to the next case stage
tw.system.currentProcessInstance.parentCase.completeCurrentStage();

//Add a comment to the case
tw.system.currentProcessInstance.parentCase.addCommentToCase("The request approval has been completed.");

Save the process.

The summary of the available methods of the class is reported in the Interacting with a parent case from a process page of the Business Automation Workflow documentation. The detailed documentation of the class is in the JavaScript API in processes and service flows page.

Assign the user task step to the case role

It’s now time to assign the User Task step to the role defined at the step 5.

Click the Request Approval step, select the Assignments tab and set the Assign To field to Team:

Click the Select button close to the Team field and pick the Sample Role role from the popup window.

Doing that, your User Task step will be assigned to the Sample Role’s users:

Create a client-side service for the user task step implementation

In order to provide the end users a user interface to process the User Task steps, they need to be implemented by a Client-side human service which provides the coach view. In this recipe the coach view provided by the service will be shown in the case page we created and configured previously.

Go to the Implementation tab and click the New… button in the Implementation section

Give a name to the new  Client-side Human Service (i.e. Request Approval) and click Next

Select the case properties that will be used in the coach view and the local variable defined in the previous steps as reported in the picture below.

Click Finish and Save the process definition.

Now we need to configure the properties that will be shown in the user interface.

To do that go to the Implementation tab of the Request Approval user task step and click on the Request Approval implementation.

Clicking the implementation link opens the user interface designer for this step.

Select the Variables tab, expand Input, select the CaseProperties (Sample Case) entry and click the button with the wheel on the right.

Select both the case properties available and click Save.

Design the coach view

In this step of the recipe you’ll design the user interface (the coach view) that will be shown to the users part of the Sample Role role to process the Request Approval user task step through the Website Viewer widget in the Sample Process Activity Details case page.

The coach view will include the following UI components:

• A read only text field to show the request status property value;
• An editable integer field for the amount property;
• One button to approve the request;
• Another button to reject the request.

Select the Coach:Coach tab and delete any field included by default in the view:

On the right side panel called Drag a component to your page, select the Variable item from the combo box.

Expand Input and caseProperties, select Request Status and drag it in the Drop Content Here panel.


Since we want just display the Request Status property, it's needed to change the UI object associated with the property.
To do that, in the Behavior panel click the Select button close to UI Toolkit and in the Select Library Item search the Display text UI Toolkit object and select it.


The Request Status field will appears as in the following picture

Now it’s time to add a field for the Amount property.

In the same way, select the Amount property in the right side panel and drag it under the Request Status field.

As you finished, the coach view should be as below.

In addition to the fields to interact with the case properties, the coach view should include also two buttons to allow users to approve or reject the request.

For the Approve button we can reuse the OK button already present in the view: select it, go to the General tab and type Approve in the Label field.

Add the Reject button dragging a Button object it from the right side panel (select All views and search it typing Button in the search field if needed)

Rename the button label to Reject.

We finished to design the coach view for the case page. This is how it looks now.

Save the process.

Design the human service diagram

To complete the Client-Side Human Service, it’s needed to design the diagram that manage the actions taken by the users in the coach view.

For the sample solution implemented in this recipe, it’s needed to add 2 script steps where the local requestStatus variable will be updated accordingly with the action taken by the user.

To modify the service diagram select the Diagram tab.

This is how the diagram looks like at the beginning:

Add to the diagram one Client-Side Script steps. You can find them in the palette on the right.

Double click the step and rename it to Request Approved, then disconnect the Approve route from the End step and connect it to the Request Approved step. The diagram should appears as below.

 Now add another Client-Side script step and connect it to the Coach step dragging one of the steps dots

In the same way, connect both the Client-Side script steps to the End step. The diagram should be as in the picture below.

The last thing to do on the diagram is to write some javascript code in the Client-Script steps to set the requestStatus local variable with the proper value.

Click the Request Approved step and select the script tab. Replace the code in the script text area with the following line:
tw.local.requestStatus = "Approved";

Do the same for the Request Rejected step setting the following javascript code:
tw.local.requestStatus = "Rejected";

You’re done with the Human service diagram, don’t forget to save the process!

Map the properties in the user task step

The last configuration needed for the process is to map the properties in the  user task step.

Let’s go back to the process clicking the Request Approval service on the top left of the screen an selecting the Request Approval process, as in the picture below.

Select the Request Approval step and click on the Data Mapping tab.

The properties mapping should looks like in the picture, if not select the right property to map clicking the icon with the 3 coloured baloons next to each property.

You’re done implementing your sample solution, so save the process and close the Web Process Designer window.

Save and deploy the solution

Go back to the Business Automation Workflow Case Builder window.

Save the Case Type and go back to the Solution definition clicking first the Save button and then the Back button.

Now Save the solution clicking the Save button, then Deploy it clicking the arrow button highlighted in the picture below.

Before deploying the case manager asks you to commit to the design FileNet object store the artifacts that has been created for this sample solution.

Select the Commit my changes and make them available for deployment check box and click Deploy.

The solution deployment to the test environment can take some time depending on your system capacity. When the deploy has been completed successfully a green check will appear close to the arrow button.

Go ahead to the last steps to test your solution in the Business Automation Workflow Case Client!

Configure the solution roles

The last thing you need to do before testing the solution is to configure the users that belong to the sample role defined in the solution.

To make things easy, you could add to the role the case administrator/designer user you’ve logged in to the Workflow Center to design this sample solution. In the system used to write this recipe the user name is dadmin, you could obviously have a different one).

The role can be managed directly in the Business Automation Workflow Case Client, so let’s start it clicking the Play button above to the deployment button.

The Business Automation Workflow Case Client window opens.

Expand the solutions list in the top right of the window, the list of the solutions deployed on your test system will appears.

Click Manage Roles under your Sample Case solution.

A window showing the users part of the role opens.

Select the Sample Role (it should be by default because we’ve defined only one role in the solution) and click the Add Users and Groups button.

Another window opens: it allows to search the users and groups defined in the directory server and select them to be added to the role selected in the previous window.

Select Users in the Search for field, type the user name in the search field and click the magnifying glass (or just press the enter key).

The users matching the search will be listed in the Available column on the left.

Select the user you wish to add to the role and move it to the Selected column clicking the arrow key.

Click the Add button.

Now in the Manage Roles windows you should see the selected user in the role members list, if so click the Save button.

You’re done with configuring the roles and you can finally test your sample solution!!

Go ahead to the last step of the recipe.

Test the solution

The Business Automation Workflow Case Client windows should refresh and if you added to the Sample Role the same user you’re logged on the Solution page should appears.

The Cases tab should be selected by default. The Cases tab can be customized at design time, but because we left as is it present its default features allowing to create new cases and search for existing ones.

Let’s add the first case for this solution clicking the Add Cases button and selecting the Sample Case case type.

A window to fill the properties of the new case opens.

Type any integer number in the Amount field, left the Request Status field blank and click the Add button

Switch to the Work tab, in few seconds a new task for the Sample Role should appears in the role’s in-basket. If it doesn’t happens immediately, be patient and refresh the In-basket clicking on the Sample Role tab.

This is the User Task step we created in the BPMN process that implements the Request Approval case activity.

Click the Step:Request approval link. A dialog opens asking you if you wish to claim the task. Let’s claim it  clicking the Claim button.

A new tab with the Process Activity Detail page we created before opens.

As you can see, the widget on the left shows the coach view which implements the Request Approval User Task step defined in the BPMN process.

Moreover, the javascript code executed by the Update Request Status Server Script step modified the case as follow:

• set the Request Status property to Approval in progress (creating the case you left the property blank);
• completed the Request Created case stage (see the Case Stages widget);
• added a comment to the case (see the History tab in the Case Information widget on the right).

Click the Approve button.

Clicking the Approve button, both the coach view diagram and the last Server Script step defined in the BPMN process have been executed, so the process itself has been completed as the case activity implemented by the process. And because the Approval Request activity is the only activity for this sample case type also the case instance is completed.

Now let’s search it using the search function switching to the Cases tab.

Select the Added On criteria, enter the date we created the case (it should be set this way by default) and click Search.

The cases that match the search will appear in the list on the right.

Click on the case title to open the case in the Case Details page defined for the solution.

Note that the Server Script step execution Request Status updated the Request Status property value, completed the case stage and added another comment to the case.

With this last step you completed the recipe and you’ve prepared a sample Business Automation Workflow case management solution implementing a case activity using a BPMN process including its coach view in a case page and interacting with the case from it using the case javascript APIs.

Useful resources

Here are the links to some documentation pages related with the recipe.

Business Automation Workflow Knowledge Center

Adding an activity with a new process

Work Details pages

Interacting with a parent case from a process

JavaScript API in processes and service flows