Setting Up Security: Access rights & Permissions, the Practical Guide

  • 28 December 2021
  • 2 replies

Userlevel 5
Badge +4


If you find yourself having read all there is to read about Access Rights already knowing about the security panel, knowing there is a difference between permission and access rights (AR), and also knowing you can limit access to Boards… But you’re still wondering, how exactly do I do this?

Then this guide is for you! 



The Example


We are going to use our kickstarter App - Headcount Planning & Costing. This App provides a readymade structure for you to load your existing employees, manage new positions and is set up to be used by your business users. It contains sensitive data and different user types, making it the perfect example for this user access exercise!


Note: if you want this App, ask Support or your CSM to copy it into your Workspace.


Precautions when working on user management


Correct user management settings is a critical part of your Application. Whenever you create a new rule, or modify one, you must ALWAYS TEST with a TEST user having the SAME ROLE and AR as your target users.

An acceptable test means going over EVERY BOARD in EVERY Application the user has access to.

As you are following this guide, create a test user in your Workspace and connect with a private browser so you can test as we progress.


 Step 1: Roles & Permissions


All Pigment Applications come with pre defined roles that you can use directly. For the purpose of the exercise, we will create a new one to help you understand roles and permissions better.



Like everything security related, you’ll find the Role Dimension & User Role Metric in the Security Folder.

Role Dimension = the definition of the role

User Role Metric = assigns a role to each user and which is then the Permission Metric applied in the security tab


In the Role Dimension, let’s create a new item called “Department Heads”. Now double click on the Permissions Property to see how we will define it (only mentioning the permissions we need and those given in the default contributor role).

Open Application: Allowed → the user will see the App on their homepage and be able to open it, must have

Schedule imports: Allowed → the user will be able to load data from a CSV file where they have access. This is given in the default role, you can keep it or not.

Open Blocks: Unspecified → If given, the role will see all the Blocks in the Block explorer. This can be confusing. Given by default, but currently advising to remove it.

Open Boards: Unspecified → If given, the role will have access to ALL the Boards. Better to leave it to Unspecified for business users (in most cases). We’ll later see how to give access to specific Boards. 

Comment on Boards: Allowed → Role will be able to use the comment/chat functionality. They will only be able to use it on the Boards they have access to anyway so best to give it here.



Now double click on the Access Rights (AR) Property and give the role Read and Write. Meaning by default they can read and write on every Dimension and we will have to manage denials through exceptions (with Dimension specific AR). It will be much easier to work this way.

But in terms of role, it’s all set! The ‘User Role’ Metric is applied by default as a Permission Metric in the Security tab. Start by giving your test user this role and follow along with this guide.



Step 2: Global Access Rights for business access


First thing we’ll do is set-up several access rights that will be applied across the App to make sure business users only access the data they should.

For starters: all Metrics used to manage access rights and permissions should be created in the Security folder. Access Rights do not apply to this folder (which prevents you from locking yourself out of the settings) and it is only accessible for admins (non admins will not have access).


Step 2A: Access by country & department


The number one access right we come across is giving access to a specific country and department. That means when a business user opens their Board, they can only select the country and department they have access to.


You can double click on a cell of an AR Metric (if you select a user) and manually assign access rights. However, that’s not very scalable so we are not going to do this.


Instead, go to the Security folder and create a new Metric called: ‘Access by Country & Department - READ’

Data Type should be boolean and it should have 3 Dimensions: Users, Country & Department.

Now duplicate the Metric and call it ‘Access by Country & Department - WRITE’.

Finally, create a Table called Access by Country & Department and add these two Metrics.

Let’s make it look like this:

Pivot the Dimensions in the configure tab, like below. Note that I have renamed the two Metrics ‘Read’ & ‘Write’ for the Table.

This Table is your admin interface. Now, let’s do the actual AR.

Go back to the security folder and create a Metric called: ‘AR: Country x Department’ of data type Access Rights, using the same Dimensions as before.

You can again pivot the Dimensions and make it look like the Table above.


We are going to use the function accessrights()

This function takes two boolean parameters: read & write and will return an AR formatted data type. So the formula looks like this:

accessrights('Access by Country & Department - READ','Access by Country & Department - WRITE')

If you select a user, you’ll see that the result, for now, is blank. Go back to the Table we previously built and enable some access for your test user:

So now, our AR Metric looks like this:

But that’s not enough. We’ll see later that our test user has a role called Contributor which by default has Read & Write Access and it is better to leave it this way. So, we’ll need to manage that in this AR metric, by giving no access to all others.

We can do this with an IF statement: IF any of the boolean is true, we do accessrights depending on them, otherwise no access.

if('Access by Country & Department - READ' OR 'Access by Country & Department - WRITE',accessrights('Access by Country & Department - READ','Access by Country &

Department - WRITE'),accessrights(false,false))

It should look like this:


Alright, it looks like we finally have the result we want, and we can apply it as a Security Metric.

Head over to the Security Tab, scroll down to the Access Rights section and click on + Add an access rights rule.

On the first drop down, apply the only available Metric. 

On the second drop down, we are going to use “All metrics using some selected Dimension(s)”. That means this rule will be applied on every Metric that has the Dimensions Country and Department (which must be selected in the third drop down automatically). Hit save.


You can now test with your test user and verify that we actually have the result we were looking for!


However, if you test with your normal Admin user, you’ll see that you don’t have access to anything anymore. It’s not scalable to manually give your admins access to everything. But you can modify the AR Metric to account for that, like this:

if('Users roles' = Role."Admin",accessrights(true,true),if('Access by Country & Department - READ' OR 'Access by Country & Department - WRITE',accessrights('Access by Country & Department - READ','Access by Country &

Department - WRITE'),accessrights(false,false)))


You could add any other exception to this formula as well. 


Step 2B: Access rights for employee level


The previous AR rule only applies to Metrics where the Dimensions are Country x Department. However, a big part of the App is the Employee Dimension as well. While in the example App, employees are always shown along with the Country x Department Dimensions, effectively limiting the ability to see employees outside what the user has access to. However, it is SAFER to do AR on the Employee level as well. And when doing user management, we always err on the side of caution. 

So what do we need to do precisely? We need to check to see if a user can access an Employee, meaning check to see if an Employee is within the Department & the Country that the user has access to. And of course, that is going to depend on the version (for example, someone was on a team in the Budget but has now moved on).

We’ll start by creating a boolean Metric which will be true if an Employee was in a Department & Country for all versions and Months. Let’s call it ‘Employee in Department & Country.’ The Formula will be:

if('EmpData-Cost Center'= Department AND 'EmpData-Country' = Country,true,blank)


Step 3: Specific Access Rights


The Kickstarter App has some additional AR applied that aren’t mandatory but very useful. Let’s go over them to complete your understanding of AR.


Step 3A: Lock the past months


In this App, business users are able to change the salaries, dates & other Properties of employees. We don’t want them to be allowed to change past periods (even though if arguably with the switchover applied, it doesn’t change the numbers). It’s just more convenient for them!

This AR rules should be by Versions & Month, as the past periods will differ depending on the versions you have (your budget will be open for the whole year whereas the forecast will be locked for current past periods).


In the security folder, create an AR Metric: ‘AR: Lock Past Month’, of data type AR with Dimensions: Users, Versions, Month.

The formula is simple: 


What it means: this grants read and write access when the period is not actuals (past).

With the ‘IsActuals’ Metric being like this:


Finally, go to the security tab and apply that Metric as an AR rule, like this:


And there you go!


Step 3A: To Be Hired Workflow


The App also includes a workflow on the To Be Hired (TBH) functionality: a user will add a TBH and this will be validated by Finance. You can look at the costs of Approved/Rejected/Pending.


First step in creating this workflow is to define who can validate the TBH.

Let’s do a Metric in the security folder called ‘Validate Request’, of type boolean & dimension Role. 

And a Metric ‘AR: Validate Request’ of type AR & Dimension Users.

The first Metric will be your input to define which role can validate, the second one is the Metric that is applied as an AR rule. Its formula should be:

accessrights(true,'Validate Request'[by:'Users roles'])

Now,you can go to the Security Tab and apply that AR. This time we will use another option, applying this AR only on ONE metric, the one with the validation status:

You can check with your test user to see that it works. But now what do you do with the values? If Finance has validated, but the user is changing the values, that’s a problem!

You guessed it, we can do another AR rule: calculating if a TBH has been validated.

That Metric will be called ‘AR: Lock TBH Input’ of data type AR with Dimensions: Users, TBH, Department,Country,Version and its formula:

accessrights(true,'TBH-Validation'<>'Validation Status'."Approved")[add:User]

It means: always give access rights if the Metric ‘TBH-Validation’ is different from Approved. Then add the User Dimension so that this applies to all users. Note that you could make an exemption so that this doesn’t apply to admins.

Now let’s set that up in the Security Tab. Once again, we will only select a few Metrics onto which we apply this rule: the whole ‘TBH Request’ Table. If you didn’t include an admin exception in the formula, be sure NOT to apply this rule on the ‘TBH-Validation’ Metric otherwise you won’t be able to Approve! 


It works! Check the result in the request table:


Step 4: Board Access


If you’ve followed along with this guide, you’ll see that users with the role '”Department Heads” don’t have access to any Board.

Let’s see how you can define who sees what. How do we proceed? We need a Metric per users to set which Board they can open. The best way to do this is to make general rules by roles and apply those at the user level.

As usual, we’ll go for two Metrics in the security folder:

  • ‘Board Access: Department Heads’, data type Boolean & Dimension Role
  • ‘Board Permission: Department Heads’, data type Permission and Dimension Users

The first metric will be the input of which role has access to which board.

The second metric will be the actual calculation of the permission, given the input and the user role. Formula should be:

if('Board Access: Departments Heads'[by:'Users roles'],permissions("{\"openBoard\": true}"))

Then create a table and add the two board metrics, like this:


Then, go to the Security Tab and apply that Metric as a permission for the Board (just before the access rights section):

Note that in this case, contrary to AR, we aren’t forcing everybody’s access to “Denied“ but leaving it as “Unspecified” for two reasons:

  • For Boards, you actually select the Boards you want to apply the permission on
  • Board access can be cumulative: Often you’ll define generic access at the role level, but make some exceptions for some individuals (VP of X need to access this board besides the regular one).

You can repeat this logic for every board that you have in your application. This allows you a very granular security setting


Step 5: Make an Admin Board


It’s always a good practice to put all of your settings & parameters into Boards. Security is no different.

Create a Board called Security and add the following sections. For Roles & Permissions:

  • A widget List for the Role Dimension
  • The ‘Validate Request’ Metric
  • The ‘User Role’ Metric


For AR management, the Table with Read & Write:

For Board Access, the Metric by role:


And finally the Metric AR: Lock Past Periods. Even if there is no action on it, it’s useful to have it here to remind yourself that it is applied.




We are now at the end. Did you test every board with your test user?

Then congratulations, you have successfully set up powerful security on your App, and are now ready to welcome your business users!

This is pretty much everything there is to know on user access in Pigment! Of course you can do more than that: more precise rules, complex workflows with delegation, automate the role of your users depending on HR data, centralize role settings and AR into your HUB to name a few. 

We’ll cover these in other guides.


2 replies


In the section about Board Permissions, there is a code sample below:

if('Board Access: Departments Heads'[by:'Users roles'],permissions("{\"openBoard\": true}"))

is there documentation on the permissions function and how the \openBoard true bit works? I followed the instructions in this guide but when I impersonate someone, they still have access to that board and I assumed I was doing something incorrectly.

Userlevel 5
Badge +4

I don’t think we have the permission setting via formula documented, but I’ll take the note !


For impersonate, it doesn’t impersonate Board permissions