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. Note Do not create a user called unknown in process engine or KIE Server. The unknown user account is a reserved system name with superuser access. The unknown 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. Important 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 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 the manager role. The supplier 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 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 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 and manager ) 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 Section 40.1, "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 the manager role: In this example, after the Prepare hardware spec user task has been completed, the user assigned to the manager role will receive the Manager 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 Section 40.4, "Modifying case role assignments during run time using Showcase" or Section 40.5, "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 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 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 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 , and supplier 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 user Katy using DELETE . /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 the manager 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 the manager role using a PUT 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 the manager role is now assigned to Cami : <?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>

Commands:
{ "case-data" : { }, "case-user-assignments" : { "owner" : "cami", "manager" : "cami" }, "case-group-assignments" : { "supplier" : "IT" } }
<?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>
<?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>
<?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>