The human workflow engine in Oracle SOA and BPM suite manages the assignment and life-cycle of human tasks deployed to the run-time infrastructure. In this post, I will share an interesting use case around restricting task reassignments to only certain group of users. This article will provide comprehensive documentation (solution, what happens in the background, limitations and behaviors across different versions of Oracle BPM ) of how to implement this requirement using a demo application.
Before that let me provide a mind map of how task assignments work in the Oracle human workflow engine.
As you can gather from the above image, there are many strategies for task assignment that an organization can adopt to suit their specific needs. I would definitely recommend reading the following blogs to go over each of them in more detail.
The use case discussed and demonstrated in this post is different from the ones discussed in the amazing blogs above.
Swimlane roles are only indicative of the default task assignment mechanism used by the human workflow engine which can be easily overridden by any of the strategies discussed above. Once a task has been assigned, either to a pool of users or an individual user, it may undergo many state transitions before being completed. The most common state transition is Task Reassignment. Although the actual state of a task is still Assigned, a task may be transferred between different participants from its original assignee. When a task is to be reassigned to another user, the BPM workspace queries the underlying directory for all available members. Task can then be reassigned to a member selected from the returned list. There is often a requirement to restrict reassignments to a custom group of users with certain privileges or access (such as users only belonging to certain roles).
The post demonstrates the requirement and use case through a sample BPM application. In order to view, deploy and execute the application, a list of prerequisites is provided here.
- Oracle JDeveloper 188.8.131.52 [BPM and SOA Extensions]
- Oracle JDeveloper 12.2.1 [BPM and SOA Extensions] [Optional]
- SQLDeveloper 4.1.3 [Optional]
- Oracle BPM Suite 184.108.40.206.8
- Oracle BPM Suite 220.127.116.11 [Optional]
- Expense Management Project [JDeveloper 11g]
- Expense Management Project [JDeveloper 12c]
- Assignment of a Task [XMind Mindmap]
- Sample Payload [getPermittedAssignees TaskQuery API operation]
The best way to illustrate the use case is through a simple expense management process illustrated below:
The process has three different swim lane roles namely, Employee, EmployeeManager and FinanceManager, one each for the type of task and their performers in the process. These swim lane roles can be mapped to users, groups or application roles from either the Fusion Middleware Enterprise Manager console or the BPM workspace so that only users with designated access can view these tasks.
Once an Administer Payment task is created, it will be assigned to either a user, group or role based on the assignment strategy.
Now imagine that a user who has an access to this task wishes to reassign this task to only peer i.e users within his working group. As indicated earlier, task reassignments is a very common feature of workflow based systems. Tasks can be reassigned for many reasons such as to transfer ownership, when a user is on vacation, for peer review to name a few. Follow the steps provided below after you have deployed the sample application to see what it the default task reassignment behavior of the BPM workspace.
- Login to WebLogic Administration console as an administrator and create three dummy users (employee, manager and finmanager).
- Login to the Oracle BPM Workspace as a workflow admin user and access the Role administration console.
- Once a process is deployed, the swim lane roles will be created automatically and can be viewed via Organization > Roles in the BPM workspace.
- Edit these roles to add/associated the users that were created before. The swim lane role to user association is simple. (Employee > employee, EmployeeManager > manager and FinanceManager > finmanager)
- Now login to the BPM workspace as an employee user to to initiate an instance of the process (An initiator task allows creating a BPM process instance through the BPM workspace)
- Under the Applications menu, you would notice a link titled Approve Employee Expenses (same name as the BPM process name).
- Click the link to open a pop-up window of the task form, enter some expense information and submit the form. For the purpose of this use case, ensure that the total of all expenses is less than 1000.
- Once the form is submitted, the process sequence will execute the business rule to check if the expenses needs a manager approval. If the total of these expenses is below 1000, then a manager approval is not required and it will go directly to the Administer Payment task.
- Log back in to the BPM workspace, this time as a user in the FinanceManager role (finmanager). A Review Expense Application task will appear in the inbox.
- Try to reassign this task by clicking on the Action > Reassign button from within the taskflow. A Reassign Task popup will appear allowing you to search for users, groups or application roles that this task can be reassigned to.
- Perform a blank search and and see that it lists all available users, groups and roles currently configured in WebLogic as potential candidates for this reassignment.
The Oracle BPM workspace is typically integrated with an active directory (AD) either directly or through a wrapper. As such the number of users, groups or roles available for any workflow based operations depends upon the base AD query filter. More often than not, this is a problem as workspace users may want to restrict this search to a limited base and only be able to reassign tasks among their group.
Solving the Puzzle####
Reassignments can be restricted in Oracle BPM Suite 11g using what is known as Potential Assignee. This feature allows restricting the task assignment to only users or group of users assigned to an application role. It is a design time configuration available from the Organization.xml file in the BPM project. In order to demonstrate how this works, we would need a new WebLogic group, a new user, change associations of two users to a group and map this group to the FinanceManager role.
- Login to the WebLogic Administration console as an administrator and create another dummy user. Name it financereviewer or something that you would prefer.
- Also create a group and name it as finance (or choose a well suited name for a group)
- Now select the user finmanager and financereviewer one at a time and from the Groups tab assign them to the newly created finance group.
- Login to the Oracle BPM Workspace as a workflow admin user, access the Role administration console and modify the FinanceManager role mapping.
- Remove the previously associated finmanager user from it and add the finance group to this role.
Now go to the composite project in JDeveloper in BPM Project Navigator view and open Organization. All the swimlane roles used in the project/processes will be part of this file. Select the FinanceManager role from the list of available roles. You would notice that there is an input field in this palette against Potential Assignee. The magnifier icon allows searching for application roles from within the Organization.xml file or from a configured identity provider (here AD provider configured in WebLogic).
Restricting reassignment could be as simple as selecting the same swimlane role against this field. This will limit the users available for reassignment of any task(s) in the FinanceManager role to the role configured against the Potential Assignee field. In this example the FinanceManager role is mapped to the finance group which in turn has two users associated to it (finmanager and financereviewer). The mechanics of how this works can be verified by deploying the project to the server again with the Update existing object on deploy option checked.
When the project is redeployed with this flag checked, the role associations for the swimlane roles would be lost and have to be recreated through the BPM workspace.
Once the process is redeployed, create another expense record as an employee and submit it so that it reaches the FinanceManager queue. Open the **Review Expense Application **task from the inbox view of the BPM workspace and from the Actions menu click on Reassign. In the Reassign Task popup, if we do a blank search, we would see only the swimlane role, the finance group and the users belonging to the group instead of all directory users, groups and roles.
The scenario depicted here simply mapped the same swimlane role to the Potential Assignee field which is a simple use case. For complex restrictions on reassignments, create an application role under the BPMRolesApp strip to map selected users/groups that a task is allowed to reassigned to and use this role instead.
What Happens Under the Hood####
It is also interesting to know what happens under the hood. When a BPM project is deployed with a Potential Assignee set, it creates an entry in the BPM_EXT_USER_PROPERTY_GLOBAL table (in the < APP>_SOAINFRA schema). The PROPERTY_VALUE_COLUMN_NAME contains a value of STR_COL_< N>. The BPM_EXT_USER_PROPERTY_VALUE table in the same schema has STR_COL_< N> column where the value of potential assignee for the application role in the deployed project is stored.
When a search is performed in BPM Workspace for users from the Reassign Task popup, the getPermittedAssignees operation is invoked on the human workflow engine. This operation returns a boolean value indicated if the reassignment should be restricted along with a list of permitted assignees.
Further reading on Oracle Human Workflow web service APIs is available in the following blog post.
Potential Assignee only effects reassignments. It does not restrict assignment of the task into the application role configured for the Potential Assignee field
Known Issues and Limitations####
Unique Constraint Violation when Potential Assignee is Set for Multiple Application Roles#####
If a BPM project has multiple swimlane roles with Potential Assignee is deployed to the infrastructure, it will try to add this entry multiple times in the BPM_EXT_USER_PROPERTY_GLOBAL creating a unique constraint violation in the database.
There was an error deploying the composite on server: Deployment Failed: oracle.toplink.exceptions.DatabaseException: java.sql.SQLIntegrityConstraintViolationException: ORA-00001: unique constraint (DEVBPM_SOAINFRA.PROP_NAME_PROP_VALUE_UNIQUE) violated Call: INSERT INTO BPM_EXT_USER_PROPERTY_GLOBAL (GUID, LAST_UPDATED_BY_IDCTX, LAST_UPDATED_DATE, CREATED_BY_IDCTX, MULTI_VALUED_PROPERTY, PROPERTY_DATA_TYPE, CREATED_BY, PROPERTY_NAME, LAST_UPDATED_BY, PROPERTY_STRING_VALUE, CREATED_DATE, PROP_VALUE_COLUMN_NAME) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) bind => [4a195fc8-083c-4af0-81d5-942f0deacf0a, jazn.com, 2016-03-10 11:58:40.877, jazn.com, 0, FREEFORM_STRING, workflowsystem, POTENTIAL_ASSIGNEE, workflowsystem, null, 2016-03-10 11:58:40.877, STR_COL5]
This is a know product bug and can be fixed by applying patch 22779160 available from Oracle support site. This patch is only available for 18.104.22.168.8 version of Oracle BPM presently but if you are running a different version, a back port patch can be requested.
Potential Assignee is mapped to a Swimlane and not Task#####
Remember that potential assignee can only be mapped to the swimlane and not directly to the task. If you have two tasks in the same swimlane and each needs a different restricted reassignment then this will not work. There are two options to overcome this limitation.
Either split the swimlane into two, each having its own task which is a quick and cheap option but interferes with the process modelling best practice.
Create a custom Java Class which is associated to a .task file to handle restricted assignment and reassignments.
Reassignments in Oracle BPM Suite 12c#####
Reassignments work completely opposite in BPM Suite 12c to how they work in 11g. By default, reassignments are restricted to the members configured for the swimlane role. I deployed the same process in the 12c runtime, created an instance of the expense management application and submitted it. The expense was created to exceed the auto approval threshold and the process flow created a approval task for the manager to approve the expenses. Potential Assignee was not set for the EmployeeManager role but a blank search in the Reassign Task popup from the BPM Process Workspace only returned users associated to the swimlane role instead of all directory members. It is remarkable to see how a certain functionality is completely juxtaposed between two product versions.
The usage of Potential Assignee is still significant in BPM processes developed in 12c albeit to cater to task reassignments if they are to be to be allowed for a wider list of members than those associated to the swimlane role.
Reassignment of tasks is a core function of any BPM based workflow. This article provides a deep dive into how this feature works across two Oracle BPM suite versions and what is provided in the tool to accommodate restricted reassignment.
Please feel free to share opinions, feedback and suggestions and I will be glad to provide any help.