Chapter 40. Case roles
Case roles provide an additional layer of abstraction for user participation in case handling. Roles, users, and groups are used for different purposes in case management.
- Roles
- Roles drive the authorization for a case instance and are used for user activity assignments. A user or one or more groups can be assigned to the owner role. The owner is whoever the case belongs to. Roles are not restricted to a single set of people or groups as part of a case definition. Use roles to specify task assignments instead of assigning a specific user or group to a task assignment to ensure that the case remains dynamic.
- Groups
- A group is a collection of users who are able to carry out a particular task or have a set of specified responsibilities. You can assign any number of people to a group and assign any group to a role. You can add or change members of a group at any time. Do not hard code a group to a particular task.
- Users
A user is an individual who can be given a particular task when you assign them a role or add them to a group.
NoteDo not create a user called
unknown
in process engine or KIE Server. Theunknown
user account is a reserved system name with superuser access. Theunknown
user account performs tasks related to the SLA violation listener when there are no users logged in.
The following example illustrates how the preceding case management concepts apply to a hotel reservation with the following information:
-
Role:
Guest
-
Group:
Receptionist
,Maid
-
User:
Marilyn
The Guest
role assignment affects the specific work of the associated case and is unique to all case instances. Every case instance will have its own role assignments. The number of users or groups that can be assigned to a role is limited by the case Cardinality
, which is set during role creation in the process designer and case definition. For example, the hotel reservation case has only one guest while the IT_Orders sample project has two suppliers of IT hardware.
When roles are defined, ensure that roles are not hard-coded to a single set of people or groups as part of case definition and that they can differ for each case instance. This is why case role assignments are important.
Role assignments can be assigned or removed when a case starts or at any time when a case is active. Although roles are optional, use roles in case definitions to maintain an organized workflow.
Always use roles for task assignments instead of actual user or group names. This ensures that the case and user or group assignments can be made as late as required.
Roles are assigned to users or groups and authorized to perform tasks when a case instance is started.
40.1. Creating case roles
You can create and define case roles in the case definition when you design the case in the process designer. Case roles are configured on the case definition level to keep them separate from the actors involved in handling the case instance. Roles can be assigned to user tasks or used as contact references throughout the case lifecycle, but they are not defined in the case as a specific user or group of users.
Case instances include the individuals that are actually handling the case work. Assign roles when starting a new case instance. In order to keep cases flexible, you can modify case role assignment during case run time, although doing this has no effect on tasks already created based on the previous role assignment. The actor assigned to a role is flexible but the role itself remains the same for each case.
Prerequisites
- A case project that has a case definition exists in Business Central.
- The case definition asset is open in the process designer.
Procedure
- To define the roles involved in the case, click on an empty space in the editor’s canvas, and click to open the Properties menu.
Expand Case Management to add a case role.
The case role requires a name for the role and a case cardinality. Case cardinality is the number of actors that are assigned to the role in any case instance. For example, the IT_Orders sample case management project includes the following roles:
Figure 40.1. ITOrders Case Roles
In this example, you can assign only one actor (a user or a group) as the case
owner
and assign only one actor to themanager
role. Thesupplier
role can have two actors assigned. Depending on the case, you can assign any number of actors to a particular role based on the configured case cardinality of the role.
40.2. Role authorization
Roles are authorized to perform specific case management tasks when starting a new case instance using the Showcase application or the REST API.
Use the following procedure to start a new IT Orders case using the REST API.
Prerequisites
- The IT_Orders sample project has been imported in Business Central and deployed to the KIE Server.
Procedure
Create a
POST
REST API call with the following endpoint:http://host:port/kie-server/services/rest/server/containers/itorders/cases/itorders.orderhardware/instances
-
itorders
: The container alias that has been deployed to the KIE Server. -
itorders.orderhardware
: The name of the case definition.
-
Provide the following role configuration in the request body:
{ "case-data" : { }, "case-user-assignments" : { "owner" : "cami", "manager" : "cami" }, "case-group-assignments" : { "supplier" : "IT" } }
This starts a new case with defined roles, as well as autostart activities, which are started and ready to be worked on. Two of the roles are user assignments (
owner
andmanager
) and the third is a group assignment (supplier
).After the case instance is successfully started, the case instance returns the
IT-0000000001
case ID.
For information about how to start a new case instance using the Showcase application, see Using the Showcase application for case management.
40.3. Assigning a task to a role
Case management processes need to be as flexible as possible to accommodate changes that can happen dynamically during run time. This includes changing user assignments for new case instances or for active cases. For this reason, ensure that you do not hard code roles to a single set of users or groups in the case definition. Instead, role assignments can be defined on the task nodes in the case definition, with users or groups assigned to the roles on case creation.
Red Hat Process Automation Manager contains a predefined selection of node types to simplify business process creation. The predefined node panel is located on the left side of the diagram editor.
Prerequisites
- A case definition has been created with case roles configured at the case definition level. For more information about creating case roles, see Creating case roles.
Procedure
- Open the Activities menu in the designer palette and drag the user or service task that you want to add to your case definition onto the process designer canvas.
- With the task node selected, click to open the Properties panel on the right side of the designer.
Expand Implementation/Execution, click Add below the Actors property and either select or type the name of the role to which the task will be assigned. You can use the Groups property in the same way for group assignments.
For example, in the IT_Orders sample project, the
Manager approval
user task is assigned to themanager
role:In this example, after the
Prepare hardware spec
user task has been completed, the user assigned to themanager
role will receive theManager approval
task in their Task Inbox in Business Central.
The user assigned to the role can be changed during the case run time, but the task itself continues to have the same role assignment. For example, the person originally assigned to the manager
role might need to take time off (if they become ill, for example), or they might unexpectedly leave the company. To respond to this change in circumstances, you can edit the manager
role assignment so that someone else can be assigned the tasks associated with that role.
For information about how to change role assignments during case run time, see Modifying case role assignments during run time using Showcase or Modifying case role assignments during run time using REST API.
40.4. Modifying case role assignments during run time using Showcase
You can change case instance role assignments during case run time using the Showcase application. Roles are defined in the case definition and assigned to tasks in the case lifecycle. Roles cannot change during run time because they are predefined, but you can change the actors assigned to the roles to change who is responsible for carrying out case tasks.
Prerequisites
- An active case instance with users or groups is already assigned to at least one case role.
Procedure
- In the Showcase application, click the case you want to work on in the Case list to open the case overview.
Locate the role assignment that you want to change in the Roles box in the lower-right corner of the page.
- To remove a single user or group from the role assignment, click the next to the assignment. In the confirmation window, click Remove to remove the user or group from the role.
- To remove all role assignments from a role, click the next to the role and select the Remove all assignments option. In the confirmation window, click Remove to remove all user and group assignments from the role.
- To change the role assignment from one user or group to another, click the next to the role and select the Edit option.
In the Edit role assignment window, delete the name of the assignee that you want to remove from the role assignment. Type the name of the user you want to assign to the role into the User field or the group you want to assign in the Group field.
At least one user or group must be assigned when editing a role assignment.
- Click Assign to complete the role assignment.
40.5. Modifying case role assignments during run time using REST API
You can change case instance role assignments during case run time using the REST API or Swagger application. Roles are defined in the case definition and assigned to tasks in the case life cycle. Roles cannot change during run time because they are predefined, but you can change the actors assigned to the roles to change who is responsible for carrying out case tasks.
The following procedure includes examples based on the IT_Orders sample project. You can use the same REST API endpoints in the Swagger application or any other REST API client, or using Curl.
Prerequisites
-
An IT Orders case instance has been started with
owner
,manager
, andsupplier
roles already assigned to actors.
Procedure
Retrieve the list of current role assignments using a
GET
request on the following endpoint:http://localhost:8080/kie-server/services/rest/server/containers/{id}/cases/instances/{caseId}/roles
Table 40.1. Parameters Name Description id
itorders
caseId
IT-0000000001
This returns the following response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <case-role-assignment-list> <role-assignments> <name>owner</name> <users>Aimee</users> </role-assignments> <role-assignments> <name>manager</name> <users>Katy</users> </role-assignments> <role-assignments> <name>supplier</name> <groups>Lenovo</groups> </role-assignments> </case-role-assignment-list>
To change the user assigned to the
manager
role, you must first remove the role assignment from the userKaty
usingDELETE
./server/containers/{id}/cases/instances/{caseId}/roles/{caseRoleName}
Include the following information in the Swagger client request:
Table 40.2. Parameters Name Description id
itorders
caseId
IT-0000000001
caseRoleName
manager
user
Katy
Click Execute.
Execute the
GET
request from the first step again to check that themanager
role no longer has a user assigned:<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <case-role-assignment-list> <role-assignments> <name>owner</name> <users>Aimee</users> </role-assignments> <role-assignments> <name>manager</name> </role-assignments> <role-assignments> <name>supplier</name> <groups>Lenovo</groups> </role-assignments> </case-role-assignment-list>
Assign the user
Cami
to themanager
role using aPUT
request on the following endpoint:/server/containers/{id}/cases/instances/{caseId}/roles/{caseRoleName}
Include the following information in the Swagger client request:
Table 40.3. Parameters Name Description id
itorders
caseId
IT-0000000001
caseRoleName
manager
user
Cami
Click Execute.
Execute the
GET
request from the first step again to check that themanager
role is now assigned toCami
:<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <case-role-assignment-list> <role-assignments> <name>owner</name> <users>Aimee</users> </role-assignments> <role-assignments> <name>manager</name> <users>Cami</users> </role-assignments> <role-assignments> <name>supplier</name> <groups>Lenovo</groups> </role-assignments> </case-role-assignment-list>