Chapter 7. 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, so you should never 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.

The following example illustrates how the preceding case management concepts apply to a hotel reservation with:

  • 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. 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, case management must 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 remains dynamic and actual 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.

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

  1. To define the roles involved in the case, click 3897 to open the Properties menu on the right side of the designer and open the Editor for Case Roles.
  2. Click Add Case Role 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 7.1. ITOrders Case Roles

    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.

7.2. Role authorization

Roles are authorized to perform specifi 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 Process Server.

Procedure

  1. 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 Process Server.
    • itorders.orderhardware: The name of the case definition.
  2. 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.

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

Use the following procedure to assign a case role to a task in the case definition.

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

  1. Click 3898 to open the Object Library on the left side of the process designer.
  2. Open the Tasks list and drag the user or service task you want to add to your case definition on to the process design palette.
  3. With the task node selected, click 3897 to open the Properties panel on the right side of the designer.
  4. Click the field next to the Actors property and type the name of the role to which the task will be assigned. You can use the Groups property in the same way to for group assignments.

    For example, in the IT_Orders sample project, the Manager approval user task is assigned to the manager role:

    case management task assignment

    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 Modifying case role assignments during run time using Showcase or Modifying case role assignments during run time using REST API.

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

  • There is an active case instance with users or groups already assigned to at least one case role.

Procedure

  1. In the Showcase application, click the case you want to work on in the Case list to open the case overview.
  2. Locate the role assignment that you want to change in the Roles box in the lower-right corner of the page.

    showcase role assignments
  3. To remove a single user or group from the role assignment, click the X next to the assignment. In the confirmation window, click Remove to remove the user or group from the role.
  4. To remove all role assignments from a role, click the three dots 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.
  5. To change the role assignment from one user or group to another, click the three dots next to the role and select the Edit option.
  6. 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.

  7. Click Assign to complete the role assignment.

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

  1. 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 7.1. Parameters

    NameDescription

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

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    caseRoleName

    manager

    user

    Katy

    Click Execute.

  3. 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>
  4. 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 7.3. Parameters

    NameDescription

    id

    itorders

    caseId

    IT-0000000001

    caseRoleName

    manager

    user

    Cami

    Click Execute.

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