Overview

Skill Level: Intermediate

This recipe provides a step-by-step guide to create a simple case management solution that leverage the Business Automation Workflow features to integrate BPMN processes in Case Management solutions.

Ingredients

A Business Automation Workflow v19.0.0.3 or later system.

Some case management and workflow knowledge.

A web browser.

Step-by-step

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

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

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

    00-Create-solution-button

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

    01-Create-solution

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

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

    02a-Create-a-property-1

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

    02b-Property

    Do the same for the Request Status property.

    Here are the properties list once you finished creating them:

    02b-Solution-properties

    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.

     

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

    03a-Sample-Role

     

     

  6. 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 Activity Details 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 Work Details Pages section and create a new copy of the Process Activity Details page clicking the last button on the right.

    04-Create-a-new-process-activity-details-page-1

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

    04a-Creating-the-page

    The Sample Process Activity Details page is now listed in the Work Details Pages list.

    05-New-page-created

  7. Add a new case type to the solution

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

    06a-Add-a-new-case-type

     

    Name the new Case Type Sample Case.06b-Give-the-new-case-type-a-name

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

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

    07-Add-the-solution-properties-to-the-case-type

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

    08-Case-type-properties

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

    09a-Add-Stages-1

    For each stage fill the name and click OK.

    09b-Stage-Name

    Your stages should appears as below.

    Case stages

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

    10-Create-a-new-process-activity

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

    11-Set-the-page-for-the-process-activity

    Click OK and then Save (top right corner).

  11. Add some case widgets to the process activity page

    Open the Sample Process Activity 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 Website Viewer widget that displays the content of the process activity (the coach view of the user task steps).

    12a-Default-widgets-for-Process-Activity-Details-page-

    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:

    12b-Add-the-case-stages-and-the-case-information-widgets-to-the-page-1

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

    13-Open-the-web-process-designer

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

    14-Delete-the-default-step

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

    15-Add-a-server-script-step

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

    16-Rename-the-server-script-step

    Add a User Task step from the palette

    17a-Add-a-user-task-step

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

    User Task step

    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.

    The last step of this process

    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.

    Save the process

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

    Add a private variable

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

    Variable details

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

    Variable added

  14. 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 case property that stores locally in the process the status of the request with the current value;
    • 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 inJavascript 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"
    var propertiesNames = new tw.object.listOf.String();
    var propertiesValues = new tw.object.listOf.String();
    propertiesNames [0]= "SC_RequestStatus"; //where SC is the solution unique identifier
    propertiesValues [0] = "Approval in progress";
    tw.system.currentProcessInstance.parentCase.setCasePropertyValues(propertiesNames, propertiesValues, true);

    //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.", true);

    //Set the case property variable in the process with the current status
    tw.local.caseProperties.RequestStatus.value = "Approval in progress";

    Each Business Automation Workflow solution has its own unique prefix which is generated by the system when the solution is created; the solution prefix is also used by BAW to build the variables unique identifier which are composed automatically as SolutionPrefix_NameOfThePropertyWithoutSpaces (where the SolutionPrefix is unmodifiable while the NameOfThePropertyWithoutSpaces can be edited during the property creation).

    As previously mentioned, one of the operations performed by the Javascript code is to set the value of the Request Status property to Approval in progress and it’s done with the following lines of code:

    //Set the RequestStatus case property to "Approval in progress"
    var propertiesNames = new tw.object.listOf.String();
    var propertiesValues = new tw.object.listOf.String();
    propertiesNames [0]= "SC_RequestStatus"; //where SC is the solution unique identifier
    propertiesValues [0] = "Approval in progress";
    tw.system.currentProcessInstance.parentCase.setCasePropertyValues(propertiesNames, propertiesValues, true);

    As you see, the first argument of the setCasePropertyValues(..) method is an array containing the unique identifiers of the properties; for our sample the array contains only one element: the unique identifier of the Request Status property. Because the solution prefix is generated automatically by the system, the unique identifier of the Request Status property on your system may be different from the one reported in the code you just copied.

    So, remember to check that the unique identifier of the Request Status property defined on your system is the same in the code pasted in the script step. If it’s different, replace SC_RequestStatus with the unique identifier generated for the Request Status property on your system.

    You should took note of the Request Status property unique identifier at step 4, if you didn’t you can find it in the property tab at solution level (click on the property name to expand it).

     

    Server Script Step code

    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;

    //Set the RequestStatus case property to Approved or Rejected based requestStatus local variable value 
    var propertiesNames = new tw.object.listOf.String();
    var propertiesValues = new tw.object.listOf.String();
    propertiesNames [0]= "SC_RequestStatus"; //where SC is the solution unique identifier
    propertiesValues [0] = tw.local.caseProperties.RequestStatus.value;
    tw.system.currentProcessInstance.parentCase.setCasePropertyValues(propertiesNames, propertiesValues, true);

    //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 has been completed.", true);

    As you did for the first Server Script step, check that the unique identifier of the Request Status property defined on your system is the same in the code pasted in the script step. If it’s different, replace SC_RequestStatus with the symbolic name generated for the Request Status property on your system.

     

    21b-Add-the-javascript-code-to-the-server-side-script-step

    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.

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

    22-Set-the-proper-role-to-the-user-task-1

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

    24-Set-the-proper-role-to-the-user-task-3

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

    Set the proper role to the user task

     
  16. 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 sectionConfigure the implementation of the user task stepGive a name to the new  Client-side Human Service (i.e. Request Approval) and click Next

    Give a name to the client-side service

    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.

    Select the case properties

    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.

    Open the coach view

    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.

    Open the coach variables configuration

    Select both the case properties available and click Save.

    Select the case properties to be viewed in the coach UI

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

    Delete the default UI components

    Click the plus (+) sign close to the Add Content Here above the OK button

    Add a read only field

    Add a read only field selecting the Display Text field (if needed you can search it using the search bar):

    Add a read only field

     

    We’re going to use this field to show the Request Status value, so we need to bind the field with the case property. To do that select the field, go to the General tab and click the Select… button close to Binding field

    Bind the field with the case property

    Select the value of the RequestStatus field as reported in the picture below

    Bind the read only field with the case property

    Now let’s rename the label of the field to Request Status clicking on the small pencil that appears selecting the field:

    Edit the label of the field

    The field should appears as below:

    Modify the label of the field

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

    In the same way, add an Integer field, bind it with the Amount case property and rename the label to Amount.

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

    Fields added

    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.

    Configure the Approve button

    Add the Reject button clicking the (+) button below the Approve button and selecting a Button object (as usual you can search it using the search bar)

    Adding the Reject button

    Rename the button label to Reject.

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

    Coach View Completed

    Save the process.

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

    The human service diagram at the beginning

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

    The Client-Side step

    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.

    The Request Approved script step

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

    45-Coach-View-Add-a-client-side-script-step-for-Request-Rejected-action

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

    Diagram completed

    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";

    Script to set the requestStatus local variable

    Do the same for the Request Rejected step setting the following javascript code:

    tw.local.requestStatus = "Rejected";

    Script to set the requestStatus local variable

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

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

    Go back to the process

    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.

    Map the properties in the user task step

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

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

    Save the Case Type

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

    Save and Deploy the solution

    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.

    Confirm the commit of the solution artifacts and 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.

    Deploy succeded

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

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

    Run the solution

    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.

    Manage Roles for the Sample 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.

    Add Users to the role

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

    Search for a user

    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.

    Add an available user to the selected users

    Click the Add button.

    Selected users

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

    Save the solution roles

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

    Go ahead to the last step of the recipe.

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

    Creating a new case

    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

    Create a new case

    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.

    The process task in the role in basket

    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.

    Claiming the task

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

    The process activity detail page in action

    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.

    Search the case

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

    The case details

    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.

     
  23. Useful resources

    Here is 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

Join The Discussion