Configure user roles

Roles allow you to grant rights to individual users. When you configure your application in the Studio, you grant rights to roles to define the content that users in the those roles can see and the activities they can perform. When you deploy your application to your environments, you add users to roles in order to give them permission to view content and perform activities.

Platform roles and casetype roles

You can create both platform roles and roles on individual casetypes. Platform roles allow you to give users the same rights on all cases in your application. By contrast, casetype roles allow you to give users rights to a particular case without granting them the same rights on other cases of that type.

For example, in an expense claim management system you might have the role names Employee, Manager, and Administrator. You might want to give the Employee role the right to open new expense claims and view existing expense claims, and give the Manager role the right to approve or reject expense claims. By using direct and indirect roles on casetypes, you can ensure employees can only view details of their own expense claims and that managers can only approve claims for their own employees.

Continuing the example, you may also want to grant some users (such as members of the finance team) permission to approve or reject all expense claims. You can achieve this by adding these users to the Manager platform role. Users in the platform role have the permissions that have been granted to the role on all cases, so these users would have the right to approve and reject all expense claims without being added to each case first.

Finally, you might want users in the Administrator role to have access to everything in your system. Rather than explicitly granting the Administrator role rights to perform each activity or view content, you can configure the Administrator platform role to inherit the rights granted to the Manager role (and other roles as required). This makes it easy to ensure administrator users can do everything that other users can and more.

Tip:

You grant rights to a role name, rather than to a platform role or casetype role. If you are using a casetype role to restrict users to specific cases, you should not add the same users to a platform role of the same role name.

Create role names

Role names identify the different roles in your application, such as Administrator, Manager or Customer. You can use the same role name to create both platform roles and casetype roles.

To create a role name, from your Studio navigate to Roles > Role names and then click Add role name. Enter the name you want to use in the Name box.

To grant users in this role permission to use developer tools to debug the application, select the appropriate developer role properties. These additional permissions are usually only granted to users in an administrator-type role.

Add platform roles

Platform roles apply across the application. This is in contrast to casetype roles, which grant rights to specific cases.

To give users permission to perform activities or view content on all cases of a particular type, add users to a platform role. For example, if you grant a Manager role the right to perform an Approve expense claim activity, any users that have been added to the Manager platform role can perform the activity on all Expense claim cases. If a platform role has not been granted rights to a particular activity, widget, or navigation item, then users in that role will not be able to perform the activity or view the content (unless they also belong to another role that has been granted those rights).

Often you will want to be able to add users to platform roles explicitly, using a dedicated "User management" page. You can set this up using a page casetype with attributes for each role and activities to add users to the attributes. You must create the page casetype and role attributes before you can create direct platform roles. For more information, see Manage application users.

You can also configure platform roles that reference existing platform roles (for example, to inherit their permissions) or create platform roles that apply to all application users.

To create a platform role:

1. From the Studio, navigate to Roles > Platform roles and then click Add platform role.
2. Select the role name that you want to use.
3. Select the type of platform role you want to create according to how you want to identify users in the role.
   • Direct: Identify users from an attribute on a page casetype, such as a "User management" page. This is useful if you want to add users to the role explicitly using an activity. (Note that you can perform the activity manually or automatically. The latter option is useful if you want to add users to roles based on their attributes or other criteria.)
   • Indirect: Identify users via an existing platform role. This is useful if:
     • You want to add all users in another platform role to this platform role. For example, you may want to add all Administrator users to the Manager role automatically, so that when you grant the Manager role permission to view content or perform activities, users in the Administrator role inherit those rights automatically. To do this, create an indirect platform role for the Manager role name and set the Indirect platform role to Administrator.
     • You have imported a component from Grexx Marketplace and you want to map a platform role used in that component to an existing platform role in your application.
   • Special: Add all authenticated (i.e. logged in) or unauthenticated (i.e. not logged in) users to the platform role. This is useful if you want to grant rights to all users of your application. For example, you may want to make some or all of the widgets on your homepage visible to everyone.
4. To apply security requirements to users in the role (such as minimum password requirements or mandating two-factor authentication), select an existing security profile. You can also edit the platform role later to apply or change the security profile.
5. When you are ready, click Add platform role. The role is created and can be granted rights to activities, widgets, and navigation items.

Tip:

Platform roles offer performance advantages, so we recommend using them in preference to casetype roles where possible.

Add direct casetype roles

Direct casetype roles allow you to grant users rights in relation to particular cases, rather than to all cases of a particular type. A direct casetype role identifies users via an attribute on the current case.

For example, to allow employees to edit their own expense claims but not those of other employees, you might add the Claimant role name as a direct role on the Expense claim casetype. To identify the users to add to the role, you might use a User attribute (which identifies the user that opened the claim) on the Expense claim casetype. You can then add a form activity to the Expense claim casetype so that users can update the details of a claim. By granting the Claimant role Request rights on the activity, you can ensure that users can only update their own expense claims.

To create a direct casetype role:

1. From your Studio, open the relevant casetype. Ensure the casetype includes an attribute that identifies the User case(s) that you want to add to the direct role. In order to identify users, the attribute must be of type Case ID and may contain a single value or multiple values.
2. Remain on the casetype and open the Direct roles tab and then click Add direct role.
3. Select the role name that you want to use.
4. Select the case ID attribute that will identify the user(s) you want to add to the role for each case.
5. To apply security requirements to users in the role (such as minimum password requirements or mandating two-factor authentication), select an existing security profile. You can also edit the direct role later to apply or change the security profile.
6. When you are ready, click Submit. The role is created and can be granted rights to activities and widgets (on the casetype view).

Add indirect casetype roles

Like direct roles, indirect casetype roles allow you to grant users rights in relation to particular cases, rather than to all cases. An indirect role identifies users via a direct role on a related case, rather than from an attribute on the same case.

For example, you might want to give users in the Manager role permission to perform activities on Expense claim cases relating to their own employees, but not on all Expense claim cases in the application. If there is an attribute on the Expense claim casetype that identifies the related Employee case ID, you could use this to identify users in a direct role on the related Employee case. Specifically, the Employee casetype may have a Manager direct role (which uses an attribute on the Employee case to identify the relevant user), so you could use this to identify the users that should have the Manager role on each Expense claim case.

To create an indirect casetype role:

1. From your Studio, open the relevant casetype. Ensure the casetype includes an attribute that identifies the case with the direct role that you want to reference. The attribute must be of type Case ID and can refer to any casetype, including standard casetypes (such as Customer, Product, Claim, or Order) and pages. The attribute may contain a single value or multiple values. In the case of a multivalue attribute, all related cases will be used to identify users for the indirect role.
2. Remain on the casetype and open the Indirect roles tab and then click Add indirect role.
3. Select the role name that you want to use.
4. Select the case ID attribute that will identify the case(s) with users in a direct role.
5. If the direct role on the related case does not have the same role name as the indirect role you are creating, specify the role name for the direct role that you want to reference.
6. To apply security requirements to users in the role (such as minimum password requirements or mandating two-factor authentication), select an existing security profile. You can also edit the indirect role later to apply or change the security profile.
7. When you are ready, click Submit. The role is created and can be granted rights to activities and widgets (on the casetype view).

Next steps

Once you have set up roles for different types of user, you can grant those roles rights to perform activities, view widgets, and use navigation items. When you add users to your application in each environment, you can add them to platform roles as required. They may also gain rights via direct or indirect casetype roles.