In this article, we explore the details of using Roles to determine permissions within ActivityInfo. In ActivityInfo, you can create Roles to control what data users can access and what actions you allow users to perform in your Database.
in this article, you can learn about key concepts and see examples related to how you can use Roles to define user permissions.
Key concepts
Resources
Resources refer to Forms, Folders, Reports, and Databases in ActivityInfo.
Operations
Operations refer to any action that is performed on resources and users, such as:
- Record-level permissions, such as viewing, adding, editing or deleting records.
- Operations-related permissions, such as managing users, adding or editing forms, and managing locks.
For more information on all the possible operations in ActivityInfo, see the complete list of operations.
Grants
A Grant identifies the specific resource on which the operations a user is allowed to perform are applied. Grants can be applied to any type of resource.
Grants are inherited by all contained resources. A grant that is applied to a folder applies the settings to all the forms/folders within that folder, while a grant that is applied to an entire database applies the settings to all the resources within that database. Inherited grants can also be “overridden” on a contained resource by applying a new grant on that resource, if desired.
This diagram illustrates how grants are inherited by resources contained within another resource that is given an explicit grant.
This diagram illustrates how inherited grants can be overridden by making an explicit grant to a specified resource contained within another resource.
Optional grants
A grant can be set as optional, which means that you can choose whether to enable the grant for each user that you invite to your database.
Conditions
Conditions enable you to define rules that determine which records a user can perform operations on. Rules are always expressed as a formula that evaluates to TRUE or FALSE. The rule builder helps you write the most common kinds of formulas including determining whether:
- A record is related to a parameter
- A specific field matches a specified value or set of values
- A record is assigned to the user
However, you can always use the formula editor to write your own formulas, including those that make reference to related fields or subrecords.
For example, you want to limit the visibility of records related to underage individuals to authorized personnel. In your “Case” Form, you have a Field labeled "AGE." By creating a condition with a rule where the “VIEW” operation is only allowed when the formula “AGE>18” is TRUE, you ensure that those users to whom this condition applies would only be able to view records where the value in the AGE field is greater than 18.
Multiple rules can be combined to form a condition on a specific operation, and you can decide whether or not all rules are required for the condition to be met. Additionally, you can set different conditions on different operations. For example, you can define a condition that allows a user to VIEW all records in a Form and another condition that would allow the users to EDIT only records that they are assigned to.
Parameters
Parameters are attributes that are assigned to a user which can be used in conditions to control the record-level operations they are allowed to perform.
Parameters are linked to a reference form, such as "Regions", which provides the possible values that can be assigned to a user. When you invite a user to your database, you assign a specific parameter value to that user, which effectively associates that user with the corresponding record in the reference form.
Parameters can then be used as part of a rule in a condition to define the set of records that operations are allowed on. When parameters are used in a condition, you limit the records a user would be allowed to perform actions on to those records that refer to the specific parameter value assigned to the user. For example, if a user has been assigned to “West” for the “Regions” parameter, then a condition can be configured to allow that user to ADD only records related to the “West” region.
IMPORTANT: To enable conditions based on parameters, your form must have a reference field pointing to the form that contains the possible parameter values. If you have a role where you enable conditions on record-level operations that depend on a parameter, users assigned to this role will not be able to perform those record-level operations on forms that do not have a reference field pointing to the form containing the possible parameter values.
Role
A Role is a certain combination of Grants and Parameters that you assign to a specific group of users. Roles are therefore the main way by which you control what actions you permit users to perform in your database. When you invite a user to your database, you specify which of the available roles they should be assigned to, and all the actions they are permitted to take will be constrained by the grants and permissions you have defined for that role.
How many Roles do I need?
Generally, you can define a Role for each group of users who perform the same set of tasks in your database. Quite often, this may align with the various functions within your organization. For example, you can define one role for Project Officers, another role for Sector Leads, and yet another role for Monitoring and Evaluation Officers.
You can use Grants and Parameters to allow for flexibility in what actions different users can take and keep the number of Roles you need to create to a minimum. For example, rather than creating a separate role for each of your reporting partners (which will be difficult to manage if you have many of them), you can create a single role called “Reporting Partner”, which has a Parameter for “Partner”. The “Partner” Parameter can then be used as part of a Condition to ensure that your reporting partners can only perform actions on records associated with their own organization.
In some cases databases are organized by folder along cluster lines, or along programme types. In the case of humanitarian coordination, you might have folders for Health , WASH, and NFI for example. You might also have three different roles depending on a person’s function within the cluster, such as Cluster Lead, Cluster IMO, and Cluster Member. In order to avoid having 3 x 3 = 9 roles for Health Cluster Member, WASH Cluster Member, etc., you can use optional Grants to have only three roles. When you assign a “Cluster Member” role to a user, you will also choose which sector-specific resources you are giving them access to.
This diagram illustrates the relationships between the various concepts related to permissions. Roles can have multiple grants that allow access to various resources within your database. Each grant specifies the permitted operations for the selected resource. Record-level operations can have conditions attached to them. Finally, roles can have multiple parameters defined, which can then be applied in conditions across grants as required.
Examples
In this section, you can see some examples of different roles with various levels of permissions.
Limiting access to records based on a Parameter
Scenario
Let's say you run a national programme where programme staff serve beneficiaries across various regions. You have a form called "Beneficiary Registry” where you have a record containing the personal information for each individual beneficiary served by the programme. Your programme staff are assigned to serve beneficiaries only to their assigned region. To ensure the protection of sensitive personal data, you would like to ensure that programme staff should be able to access only the records of beneficiaries who live in their assigned region. To meet these requirements, you can add a Role with the following settings.
Role
You create a single role called “Programme Officer”.
Parameters
Within the “Programme Officer” role you create a parameter called “Region” which points to a “Regions” reference form which contains the following possible values: “North”, “East”, “South”, and “West”.
Grants
You specify that this “Programme Officer” role should be granted access to the “Beneficiary Registry” form where you select “View records”, “Add records”, and “Edit records” as the permitted operations.
Within this grant, you add a condition with a rule where the VIEW, ADD, and EDIT operations are allowed only on records that are related to the user’s assigned “Region” parameter value.
In this way, users who are assigned to the “Programme Officer” role and given the “Region” parameter value of “North” would only be able to view, add and edit records in the Beneficiary Registry form where the Region field has been set to North.
Limiting access to records based on multiple conditions
Scenario
Imagine you are managing a database for a coordinated humanitarian response with interventions being implemented across various sectors. You have several partner organizations adding records to the database, and you want to control access and actions based on the user’s partner organization and the sector in which they operate. To ensure the integrity of partner submitted data, you want to restrict data entry actions so that users can only add or edit records associated with their own partner organization. However, to facilitate coordination across partners, you would like to enable visibility of records submitted by all partners within a certain sector. To meet these requirements, you can add a Role with the following settings.
Role
You create a single role for all partners, and name it "Reporting Partner".
Parameters
You define two parameters - one for “Partner” which points to your list of partner organizations and another for "Sector" which points to your list of sectors (e.g. “Health”, “Education”, “WASH”).
Grants
You specify that this Role should be granted access to the “Activities” form where you select “View records”, “Add records”, and “Edit records” as the permitted operations.
You then add two conditions within this Grant:
- Condition 1: VIEW only records where the “Sector” field matches the user’s assigned “Sector” parameter value
- Condition 2: ADD and EDIT only records where the “Partner” field matches the user’s assigned “Partner” parameter value
Limiting access to records based on assigned user
Scenario
Say you are managing a Case Management database where each case is assigned to a single Case Worker. Because your database contains highly sensitive information, you want to ensure that Case Workers should only be able to access records of the cases that they are assigned to.
Role
You create a single role called “Case Worker”.
Grants
You specify that this role should have access to the “Cases” form where you select “View records”, “Add records”, and “Edit records” as the permitted operations.
Within this grant, you add a condition with a rule where the VIEW, ADD, and EDIT operations are allowed only on records that are assigned to the user. For this role, you will add a further condition with a formula using the rule builder. This would create a rule with a formula that allows you to match specific records to a current user.You will select the condition "Record assigned to user," and with the formula, assign "Case Worker== @user.
With this role, Case Workers would only be able to access and interact with records belonging to the cases they are assigned to.
The rule builder contains a preset formula that filters records based on whether the selected value in a user field in the form matches the current user.