# Use an access matrix to enable role-based access to data

> This page describes how to use an access matrix to enable role-based access to data for end-users.

## Introduction

This page describes how to use an access matrix to enable role-based access to data for end-users.

## Part 1: Define the access matrix file

The access matrix defines which users have access to which part of the data used in discovery accelerators, apps or processes.

The end user's email will be checked in the access matrix. Access is granted based on the relations between the user's email address and the attribute used to identify the discovery accelerators, apps or processes defined in the access matrix file.

See the illustration below for an example matrix file.

![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-54664-9503de1f-646edc79.webp)

:::note
The Access Matrix file must at least contain the `Email` field and the field that is used to identify the data that the user is allowed to see. In this example, the `Company code visibility` attribute is used to identify the process data.
:::

The email formatting can be with or without capital letters. In the accelerator or app, the format will be checked and adapted if needed. See [Part 4](https://docs.uipath.com/process-mining/standalone/2021.10/user-guide/use-an-access-matrix-to-enable-role-based-access-to-data#use-an-access-matrix-to-enable-role-based-access-to-data).

In this example the Company code visibility is used as the column to filter the data. This column can contain multiple values, so that the data is filtered in a way that users can only see the company codes they are allowed to. Company codes are separated by commas, in the same column.

## Part 2: Upload the access mfatrix File

To use the access matrix file in your discovery accelerator, app or process, you must upload it to the Superadmin **Server data** tab. See [The Server data Tab](https://docs.uipath.com/process-mining/standalone/2021.10/user-guide/the-server-data-tab#the-server-data-tab).

See the illustration below for an example.

![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-54083-70322e90-ab684f41.webp)

In the above example the access matrix for **Purchase-to-Pay Discovery Accelerator** is used, but this can be used in the same way for any other discovery accelerator or app. You can maintain multiple files, or add more columns to the original Excel file.

For application level restrictions see [Authentication](https://docs.uipath.com/process-mining/standalone/2021.10/user-guide/process-mining-set-up-single-sign-on-azure-active-directory#set-up-single-sign-on-through-azure-active-directory).

## Part 3: Create the tables used to access the access matrix

To access the access matrix from your discovery accelerator or app you must create the following

tables:

* a System table that displays the current user;
* a connection string table to access the access matrix in the **Server data** tab.

See illustration below for an example.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-55917-f562f255-d9701e72.webp)

In this example the following tables are used:

* `User`
* `Access Matrix`.

### User Table

Follow these steps to create a System table to show the current user.

| Step | Action |
| --- | --- |
| 1 | Open the accelerator or app in your development environment and go to the **Data** tab. |
| 2 | Right-click in the table list and select **New table -> System table...**. |
| 3 | Double-click on the new table and select **Current user** as the **Table scope**.  Click on **OK**. |
| 4 | Press **F2** and rename the new table to **User**. |

The `User` table is a System table that displays the current user. Access to data is checked based on email.

### Access_Matrix Table

The `Access Matrix` table uses a connection string to the access matrix file in the Superadmin **Server data** tab. Follow these steps to create a connection string table to load the access matrix file.

| Step | Action |
| --- | --- |
| 1 | Right-click in the table list and select **New table -> Connection string...**. |
| 2 | Right-click on the new table and select **Advanced - > Options**. |
| 3 | In the **Table Options** dialog, click on the drop-down list of the **Table scope** field in the **Advanced** section and change the scope to **Server**. |
| 4 | Double-click on the new table and add the connection string to the access matrix file that you uploaded to the **Server data** tab.  Click on **OK**. |
| 5 | Press **F2** and rename the new table to **Access_Matrix**. |

See the illustration below.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-58233-b4a39163-643629e6.webp)

## Part 4: Create expressions to check what data a user is allowed to see

This part consists of the following steps

Step 1: Correct the input format;

Step 2: Match the login user to the access matrix;

Step 3: Create a fallback for cache generation;

Step 4: Filter the data.

### Step 1: Correct the input format

To ensure the email formatting is similar between the access matrix and the end-users found in Active Directory, you must create an expression to strip the email formatting. Follow these steps to create the expression.

| Step | Action |
| --- | --- |
| 1 | Click on the **Access_matrix** table. |
| 2 | Right-click in the table item list and select **New expression...**. |
| 3 | Enter **Email** in the **Name** field and select **Per record** as the **Type**. |
| 4 | Enter the expression:  `trim(lower(Email_input))` |
| 5 | Click on **OK**. |

See the illustration below.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-53696-537b842d-558d62ef.webp)

### Step 2: Match the login user to the access matrix

You must create a lookup expression in the `User` table that returns the company codes (or other data attributes) the user is allowed to see.

| Step | Action |
| --- | --- |
| 1 | Click on the **User** table. |
| 2 | Right click in the table item list and select **New expression...**. |
| 3 | Enter **Company code visibility lookup** in the **Name** field and select **Lookup** as the **Type**. |
| 4 | Select **Access_Matrix** as the **Input table** |
| 5 | Enter the expression:  `any(records.Company_code_visibility_input)` |
| 6 | Right-click in the **Settings** panel and select **Add level**. |
| 7 | Click on **...** and select the **Email** expression. |
| 8 | Right click on the **Email** expression** and select **Set as expression level**. |
| 9 | Click on **OK**. |

See the illustration below.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-56401-8239b496-bfceab62.webp)

If a user is allowed to see everything, `ALL` is returned. If a user is not defined in the access matrix, the lookup will return `NULL`, to ensure that new users will not see any data.

### Step 3: Create a fallback for cache generation

This is a necessary step to ensure that during cache generation all data is taken to generate the cache. To avoid the access matrix returning NULL during cache generation and filtering all the data, you need to set a fallback.

To ensure the cache is generated for the entire dataset, the `ALL` can be used as a fallback. This means no filtering is applied when the cache is being generated. The data is only filtered for the specific user after cache generation. This logic is built on that the email field is a mandatory field when creating new users, so it will not be empty for other users. During cache generation the email field is empty, so no filter is applied.

Follow these steps to create an expression to have a fallback for.

| Step | Action |
| --- | --- |
| 1 | Click on the **User** table. |
| 2 | Right-click in the table item list and select **New expression...**. |
| 3 | Enter **Company code visibility** in the **Name** field and select **Per record** as the **Type**. |
| 4 | Enter the expression:  `if ( Email = NULL , "ALL" , Company_code_visibility_lookup )` |
| 5 | Click on **OK**. |

See the illustration below.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-54836-1bf50c11-e4ce3bf2.webp)

If a user has assigned 'ALL', the user is allowed to see all data. Otherwise, the data the user is allowed to see is determined by the company code (or any other attribute that you have specified).

### Step 4: Filter the data

The expression must check whether the user has assigned "ALL". In this case, all data is shown to the user. Otherwise, the expression must extract the attribute and check whether this attribute is in the list.

Since the Company Codes from the access matrix are maintained on a single row, these also need to be split and trimmed to ensure a list is created for each company code (or any other attribute that you have specified). The trimming is used to remove any unwanted spaces in the text.

Follow these steps to create an expression to filter the data.

| Step | Action |
| --- | --- |
| 1 | Click on the **Cases_data** table. |
| 2 | Right-click in the table item list and select **New expression...**. |
| 3 | Enter **Company code filter user** in the **Name** field and select **Per record** as the **Type**. |
| 5 | Enter the expression to define the list of company codes:  `var list := trim(split(Company_code_visibility, ","));` |
| 8 | Enter the expression to if the user has assigned "ALL".  `if( "ALL" in list , TRUE , split(Company_code, " " ,0) in list )` |
| 9 | Click on **OK**. |

See the illustration below.

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-56021-d60ce2b2-399c1c3c.webp)

This expression is then used in the joins to filter out the data, to ensure only the granted data is shown. Below is an example join that shows the results for one specific company code for filtering case data, resulting in significant less cases.

:::note
It is advised to use filters for cases. However, this approach can also be used to filter events.
:::

  ![docs image](https://dev-assets.cms.uipath.com/assets/images/process-mining/process-mining-docs-image-57261-1620d8f1-64b0d80b.webp)