Add Your First Parameter to a Role

In this tutorial, you will learn how to limit a user’s permission to view only the records that are related to the organization they are working for. We will do this by adding a role with a parameter and a condition.

Before you start

  • Make sure you have already added a database and
  • You have been assigned to a role with the “Manage roles” and “Manage users” operation permitted.
  • If not, you can use the Who's doing what where (3W) database template to add a new database.

In this tutorial, you will learn how to limit a user’s permission to view only the records that are related to the organization they are working for. We will do this by adding a role with a parameter and a condition.

In this tutorial, we will use the example of a linking records and permissions to reporting partner organizations, but you can apply the same logic to any reference field, such as province, or region, or sector.

Add a Partner Form

Before beginning, we need a form which contains the list of the partners that a user can be assigned to.

  • Go to Database Settings, and then in the Design section. Click “Add Form”.
  • In the following screen, enter the form label as “Partner Organization"
  • Add a single Text field called "Name". Make this field Required and a Key field.
  • Save the form.
  • Now you should see the table view of this form.
  • Click "Add Record" to add the first Partner. In this example, we are using the name "GlobalCare" and then Save.
  • Click Add Record to add each Partner, with the names “EduBright International”,”FoodFirst Initiative”, “AquaLife Foundation” , “ShelterSphere” , “TechAid”, “EmpowerHer”, and “SafeHaven Network” and after adding these partner names as records, Save.
  • Return to the Database Settings.

Add a form for monthly progress reports

To apply conditional permission on forms, it is important that each form has a reference to your Partner Form. This helps establish the relationship between each record and the partner to whom it belongs.

Go to Database Settings, and then in the Design section. Click “Add Form”.

  • In the following screen, enter the form label as “Progress report”
  • Add a Month field, make it required
  • Add a Partner field, that references the Partner Form, make it required.
  • Add a Quantity field called “Number of beneficiaries” and make it required
  • Save the form.
  • You can add a few records for all the partners; "GlobalCare" “EduBright International”,”FoodFirst Initiative”, “AquaLife Foundation” , “ShelterSphere” , “TechAid”, “EmpowerHer”, and “SafeHaven Network”

Add a Role

Now we are ready to add a role that restricts users to seeing and adding only records that are related to the partner to which they have been assigned.

  • To set up roles in your database, follow these steps:
  • Go to your database settings. Find and click on "Roles."
  • Click "Add role" .
  • Type in the role name, such as "Reporting Partner," and click ok .You'll see the new role in a list.
  • Click on the new role. The partner will be displayed in the side panel

Add a Role Parameter

  • Switch to the “Parameters” tab and click “Add Parameter”
  • Fill in the Parameter ID as “partner” and the Label “Partner”. Select the Partner form you previously added that includes the list of partners.
  • Click done.
  • The parameter should appear in the list of parameters.

Add conditions to the permissions

Adding a parameter alone does not have any effect on permissions. In the next step, we will use the parameter as part of a condition to limit the permissions associated with the role.

We will now assign a set of permitted operations to this role for the "partner organization" and "progress report" forms, which, for our current use, make up the whole database.

  • Switch back to the “resources” tab.

  • Click “Grant Resource”.

  • Select “Entire database” from the first column and click “Select resource”

  • Check the following permissions:

  • View

  • List

  • Add record

  • Edit record

  • Delete record

  • Then, from the bottom of the card, click “Manage conditions”

  • In the modal that appears, click “Add rule”

  • From the first column, select “Record is related to parameter”
  • From the second column in the rule, select the “Partner” parameter that you just added
  • Then click “Set conditions”
  • Then click “Save” to add the new grant.

Now you have added a role, which allows the users assigned to this role to only view, add, edit or delete records that are associated with their partner.

Add a user to the new Role

Let’s see how this looks for a partner that you might invite to contribute progress to the database. For this part of the tutorial, you can invite yourself using an alternate email, such as your personal email address, so that you can see how this looks for a reporting partner.

  • To use this parameter for a user, go to the “User management” section in the Database Settings, and then click “Add user”
  • Add user "email"
  • Add the users "Name"
  • Select the "Reporting Partner" role
  • Select the specific value for the parameter and
  • Click "Send invite" to invite them

Testing the role

  • Log out of ActivityInfo.

  • Using the alternate email address that you invite, log into the application.

  • Go to the database

  • Go to the Progress report form.

  • You should see only the records belonging to partner “GlobalCare”. Assuming you set the parameter value for this user to “EduBright International”,”FoodFirst Initiative”, “AquaLife Foundation” or any other partner name, they would only see the records belonging to these partners.

  • When you click “Add record”, the partner “Globalcare” should be prefilled, and you should not be able to select the other partners.

Next item
Understanding Roles