# Configured Role-Based Permissions

Manage the permissions of the System Administrator, Facility Administrator, Researcher, and Collaborator user roles to restrict or allow the following actions:

* Sign in to Clarity LIMS.
* Sign in to the API.
* View and interact with certain features of the interface.
* Perform certain actions in the interface.
* View and restrict any actions in the interface. \[Clarity LIMS v6.1 and above]

**NOTE**: You can use System Settings to configure role-based permission in Clarity LIMS v6.3. For details, see [#roles-and-permissions-management](https://help.connected.illumina.com/clarity-lims/clarity-lims-v6.3-and-lablink-v2.5/administration/system-settings#roles-and-permissions-management "mention").

### Command-line Permissions Tool

Role-based permissions are controlled through the permissions-tool.jar tool, at /opt/gls/clarity/tools/permissions/.

For assistance with running the command-line permissions tool, contact the Illumina Support team.

Functionality includes the following commands:

* [#listroles](#listroles "mention")—List all roles in the system.
* [#describerole](#describerole "mention")—List names and descriptions of all permissions in the system.
* [#createrole](#createrole "mention")—Create a role.
* [#showsummary](#showsummary "mention")—List permissions assigned to each role in the system.
* [#listpermissions](#listpermissions "mention")—List permissions assigned to a specific role.
* [#assignpermission](#assignpermission "mention")—Assign a permission to a role.
* [#removepermission](#removepermission "mention")—Remove a permission from a role.

**NOTE**: The permissions-tool.jar tool function names and property names are case-sensitive. If you type the incorrect case, your command or property cannot be understood.

There can be a delay (up to 20 minutes) before changes to some API-related permissions take effect.

### Supported Commands

#### **listRoles**

List all user roles in the system:

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> listRoles
```

#### **describeRole**

Show permissions for a specific role:

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> describeRole <rolename>
```

#### **createRole**

Create a role:

{% code fullWidth="false" %}

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> createRole <rolename>
```

{% endcode %}

#### **showSummary**

Show assigned permissions for all roles:

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> showSummary
```

#### **listPermissions**

List names and descriptions of all permissions:

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> listPermissions
```

#### **assignPermission**

Assign a permission to a role (the example assigns permission to create controls):

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> assignPermission <rolename> Controls:create
```

\[Clarity LIMS v6.1 and above] Assign a permission to a role (the example assigns read-only permission to a role):

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> assignPermission <rolename> RoleOnly
```

Refer to [#supported-permissions](#supported-permissions "mention").

#### **removePermission**

Remove a permission from a role (the example removes permission to create controls):

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> removePermission <rolename> Controls:create
```

Refer to [#supported-permissions](#supported-permissions "mention").

#### Usage

```
java -jar permissions-tool.jar -a <apiUri> -u <username> -p <password> <command> [<args>]
```

#### **Options**

<table data-header-hidden><thead><tr><th width="71"></th><th width="139"></th><th></th></tr></thead><tbody><tr><td>-a</td><td>--apiUri</td><td>REST API base URI (ends with "/api/&#x3C;version>/") Must be completed as: http://&#x3C;servername>/api/v2/</td></tr><tr><td>-p</td><td>--password</td><td>LIMS password (required)</td></tr><tr><td>-u</td><td>--username</td><td>LIMS sign-in username (required)</td></tr></tbody></table>

### Supported Permissions

The sections below list LIMS permissions and actions, and the user roles to which each permission/action is assigned by default.

By default, System Administrators and Facility Administrators have all permissions listed.

#### **Permission: AdministerLabLink**

The default role with AdministerLabLink permission is Administrator. This permission is added to the existing System Administrator & Facility Administrator roles.

The Collaborator role is based on the existing Collaborator role in LabLink v1.0.

Note: The existing Researcher role does not have the new permission and behaves similarly to the LabLink Collaborator role.

| Action                        | Permission Required            | System Administrator and Facility Administrator | Collaborator |
| ----------------------------- | ------------------------------ | :---------------------------------------------: | :----------: |
| Sign in to LabLink            | CollaborationsLogin action     |                       Yes                       |      Yes     |
| Manage Project                | Projects create, read, update. |                       Yes                       |      Yes     |
| Manage Sample                 | Samples create, read, update.  |                       Yes                       |      Yes     |
| Manage User                   | Users create, read, update.    |                       Yes                       |      No      |
| Manage Configuration          | Configuration update           |                       Yes                       |      No      |
| View the Configuration page   | AdministerLabLink              |                       Yes                       |      No      |
| View the User Management page | AdministerLabLink              |                       Yes                       |      No      |

#### **Permission: ClarityLogin**

Default roles with this permission: Administrator, Researcher

<table><thead><tr><th width="493">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Sign in to ClarityLIMS</li><li>Access Lab View and Projects and Samples screen</li><li>Access Consumables > Reagents configuration tab; view, edit, and delete reagent lots; add lots to existing kits.</li><li>Access Consumables > Controls configuration tab and view control details</li><li>Access Consumables > Instruments configuration tab; add, edit, delete, and activate instruments; view instrument types.</li></ul></td><td><p>Sign In screen</p><ul><li>Sorry, you do not have permission to sign in to Clarity LIMS.</li></ul></td></tr></tbody></table>

#### **Permission: APILogin**

<table><thead><tr><th width="514">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Access LIMS Rest API</li></ul></td><td><p>Sign In screen</p><ul><li>403 Forbidden error via http://host/api/*</li></ul></td></tr></tbody></table>

#### **Permission: Project**

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>create</li></ul></td><td><ul><li>Create project</li><li>Modify project details</li><li>Modify project custom fields</li></ul></td><td><p>Projects and Samples</p><ul><li>New Project button hidden</li><li>View project details (read-only)</li></ul><p>Note: No permission is needed to upload files to a project</p></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Modify project details</li></ul></td><td><p>Projects and Samples</p><ul><li>Save button disabled (if delete is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>View project details (read-only)</li></ul></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete project containing no samples.</li><li>Delete project containing samples (also requires Sample:delete permission)</li></ul></td><td><p>Projects and Samples</p><ul><li>Delete button disabled (if update is permitted)</li><li>Button menu hidden (if update is not permitted)</li></ul></td></tr></tbody></table>

#### **Permission: Sample**

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>create</li></ul></td><td><ul><li>Submit/add samples</li><li>Upload sample list</li><li>Download sample list example</li><li>Modify samples.</li></ul></td><td><p>Projects and Samples</p><ul><li>Submit Samples title hidden</li><li>Download Example Sample List link hidden</li><li>Upload Sample List button hidden</li><li>Add Samples button hidden</li><li>Modify Samples button renamed Download List</li><li>Modify Samples button hidden (sample list)</li></ul><p>Sample Management</p><ul><li>Sample + button hidden</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Modify samples.</li></ul></td><td><p>Projects and Samples</p><ul><li>Modify Samples button renamed Download List</li></ul></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete a submitted sample on Projects and Samples screen, provided no work has been performed on the sample.</li><li>Delete a submitted sample in API, provided no work has been performed on the sample.</li></ul></td><td><p>Projects and Samples</p><ul><li>Delete button hidden</li><li>403 Forbidden error via http://host/api/sample</li></ul></td></tr></tbody></table>

{% hint style="info" %}
The Sample:update permission is automatically granted to roles that have the Sample:create permission at the time of migration to Clarity LIMS v5.x. If you have removed create permissions from any default role, the role does not acquire the update permission.
{% endhint %}

#### **Permission: Controls**

Default roles with these permissions: Administrator

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>create</li></ul></td><td><ul><li>Create control samples.</li></ul></td><td><p>Controls</p><ul><li>New Control button hidden</li><li>New Control button hidden</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Modify control samples.</li><li>Archive control samples (requires both update and delete permissions)</li></ul></td><td><p>Controls</p><ul><li>Save button disabled (if delete is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>View control sample details (read-only)</li></ul></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete control samples.</li><li>Archive control samples (requires both update and delete permissions)</li></ul></td><td><p>Controls</p><ul><li>Delete button disabled (if update is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>Archived toggle disabled</li></ul></td></tr></tbody></table>

{% hint style="info" %}
Users with ClarityLogin permission can access the Consumables > Controls tab and view control sample details (read only).
{% endhint %}

#### **Permission: ReagentKit**

Default roles with these permissions: Administrator

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>create</li></ul></td><td><ul><li>Create reagent kits</li></ul></td><td><p>Reagents</p><ul><li>New Reagent Kit button hidden</li><li>View reagent kit details (read-only)</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Modify reagent kits</li><li>Archive reagent kits (requires both update and delete permissions)</li></ul></td><td><p>Reagents</p><ul><li>Save button disabled (if delete is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>View kit details (read-only - except for Status)</li></ul></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete reagent kits</li><li>Archive reagent kits (requires both update and delete permissions)</li></ul></td><td><p>Reagents</p><ul><li>Delete button disabled (if update is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>Archived toggle disabled</li></ul></td></tr></tbody></table>

{% hint style="info" %}
Users with ClarityLogin permission can access the Consumables > Reagents tab. They can also view, edit, and delete reagent lots, and add lots to existing kits. No additional ReagentKit permissions are required.
{% endhint %}

#### **Permission: Role**

Default roles with these permissions: Administrator

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>read</li></ul></td><td><ul><li>View client (researcher/contact) details, including details such as username and roles in API</li><li>View users and clients (contacts) on Users and Clients screen</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr><tr><td><ul><li>create</li></ul></td><td><ul><li>Create user roles.</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Modify existing user roles.</li><li>Add/remove user role permissions</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete user roles.</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr></tbody></table>

{% hint style="info" %}
APILogin permission is required for role management. All users with ClarityLogin permissions can view and edit their own user details (except for assigning/removing roles).
{% endhint %}

#### **Permission: Read-Only** \[Clarity LIMS v6.1 and above]

Default roles with this permission: Not applicable. You can assign this permission to any role.

{% hint style="info" %}
At least one System Administrator must be available to reconfigure user roles. Therefore, we recommend that you do not assign the Read-Only permission to the default Administrator and API users.
{% endhint %}

<table><thead><tr><th width="132">Action:</th><th width="618">Allows:</th></tr></thead><tbody><tr><td><ul><li>read</li></ul></td><td><ul><li>View project and sample details on the Projects &#x26; Samples screen</li><li>View lab activities, in-progress steps, and steps that are ready to be worked on in Lab View</li></ul></td></tr></tbody></table>

#### **Permission: User**

Default roles with these permissions: Administrator

<table><thead><tr><th width="132">Action:</th><th width="274">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>read</li></ul></td><td><ul><li>View users and clients on Users and Clients screen</li><li>View client details, including details such as username and roles in API</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr><tr><td><ul><li>create</li></ul></td><td><ul><li>Create users and clients on Users and Clients screen (User:update permission is required to assign permissions to the user)</li><li>Send login instructions and password reset emails on Users and Clients screen (either this action or User:update is required)</li><li>Create clients in API.</li><li>Create user credentials and assign roles in API.</li></ul></td><td><p>Users and Clients</p><ul><li>New User button hidden</li><li>View user details (read-only)</li><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Update users and clients on Users and Clients screen</li><li>Send sign in instructions and password reset emails on Users and Clients screen (either this action or User:create is required)</li><li>Modify client details in API.</li><li>Assign role to user in API.</li><li>Remove role from user in API.</li></ul></td><td><ul><li>Save button disabled (if delete is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>View user/client details (read-only)</li><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete users and clients on Users and Clients screen.</li><li>Delete a client and associated user in API.</li></ul></td><td><ul><li>Delete button disabled (if update is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr></tbody></table>

In the LIMS user interface, the term 'contact' has been replaced with 'client.' However, the API still uses the permission Contact.

All users with ClarityLogin permission can view and edit their own user details (except for assigning/removing roles).

#### **Permission: Contact**

Default roles with these permissions: Administrator

<table><thead><tr><th width="132">Action:</th><th width="274">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>read</li></ul></td><td><ul><li>View clients on Users and Clients screen</li><li>View client details in API</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr><tr><td><ul><li>create</li></ul></td><td><ul><li>Create clients on Users and Clients screen.</li><li>Create clients in API.</li></ul><p>Contact:update permission is required to assign permissions to clients.</p></td><td><ul><li>New User button hidden</li><li>View user details (read-only)</li><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Update client details on Users and Clients screen.</li><li>Update client details in API.</li><li>Assign role to/remove role from client.</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/researchers</li></ul><p>This permission does not affect the display of clients in Project and Samples and Sample Accessioning screens.</p></td></tr><tr><td><ul><li>Delete</li></ul></td><td><ul><li>Delete clients in API</li><li>Delete clients on Users and Clients screen.</li></ul><p>Clients with associated user details cannot be deleted</p></td><td><ul><li>Delete button disabled (if update is permitted)</li><li>Button menu hidden (if delete is not permitted)</li><li>403 Forbidden error via http://host/api/researchers</li></ul></td></tr></tbody></table>

In the LIMS user interface, the term 'contact' has been replaced with 'client.' However, the API still uses the permission Contact.

Users with ClarityLogin permission can view and edit their own client and user details.

Clients can edit their own details (except for assigning/removing roles) without having update permission.

#### **Permission: Process**

Default roles with these permissions: Administrator

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>read</li></ul></td><td><ul><li>View master steps</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr><tr><td><ul><li>create</li></ul></td><td><ul><li>Create master steps.</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr><tr><td><ul><li>Update</li></ul></td><td><ul><li>Modify master steps.</li></ul></td><td><ul><li>403 Forbidden error via http://host/api/roles</li></ul></td></tr></tbody></table>

In the LIMS user interface, the term 'process' has been replaced with 'master step.' However, the API still uses the permission Process.

#### **Permission: OverviewDashboard**

Default roles with this permission: Administrator

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>read</li></ul></td><td><ul><li>Access the Overview Dashboard</li></ul></td><td><ul><li>No Dashboards button</li></ul></td></tr></tbody></table>

#### **Permission: Configuration**

Default roles with this permission: Administrator

<table><thead><tr><th width="132">Action:</th><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>update</li></ul></td><td><ul><li>Manage all configuration in the LIMS interface (ClarityLogin permission is also required)</li><li>Manage configuration in API (APILogin permission is also required)</li></ul></td><td><ul><li>403 Forbidden error via any URI that begins with http://host/api/configuration.</li></ul></td></tr></tbody></table>

#### **Permission: ReQueueSample**

Default roles with this permission: Administrator, Researcher, Collaborator

<table><thead><tr><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Requeue a sample in sample search.</li><li>Requeue a sample in container search.</li></ul></td><td><p>Sample and Container Search</p><ul><li>Requeue button hidden.</li></ul></td></tr></tbody></table>

#### **Permission: SampleWorkflowAssignment**

Default roles with this permission: Administrator, Researcher, Collaborator

<table><thead><tr><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Assign sample to workflow from Projects and Samples screen.</li></ul></td><td><p>Sample Management</p><ul><li>Sample cannot be dragged into workflow widgets.</li><li>Workflow selection widget hidden</li><li>Workflow lozenge Remove button hidden</li><li>Delete workflow button hidden.</li></ul></td></tr></tbody></table>

#### **Permission: RemoveSampleFromWorkflow**

Default roles with this permission: Administrator

<table><thead><tr><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Remove sample from queue.</li><li>Remove sample from workflow.</li></ul></td><td><p>Sample Management</p><ul><li>Remove from this queue option hidden (if Move to next step is permitted)</li><li>Options button hidden (if Move to next step is not permitted)</li></ul></td></tr></tbody></table>

#### **Permission: MoveToNextStep**

Default roles with this permission: Administrator

<table><thead><tr><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Move sample to next step in workflow</li></ul></td><td><p>Sample Management</p><ul><li>Move to the next step option hidden (if Remove from this queue is permitted)</li><li>Options button hidden (if Remove from this queue is not permitted)</li></ul></td></tr></tbody></table>

#### **Permission: SampleRework**

Default roles with this permission: Administrator

<table><thead><tr><th width="259">Allows:</th><th>Result - permission granted</th></tr></thead><tbody><tr><td><ul><li>Rework a sample from a previous step.</li></ul></td><td><p>Sample Management</p><ul><li>In Select the next step of the sample drop-down list, Rework from an earlier step option displays.</li><li>On Protocol Step Results screen, a button displays to allow the sample to be reworked from an earlier step.</li></ul></td></tr></tbody></table>

#### **Permission: ReviewEscalatedSamples**

Default roles with this permission: Administrator

<table><thead><tr><th width="259">Allows:</th><th>Result - permission granted</th></tr></thead><tbody><tr><td><ul><li>Review escalated samples.</li></ul></td><td><p>Sample Escalation</p><ul><li>Enter Review Comment box enabled.</li></ul></td></tr></tbody></table>

#### **Permission: ESignatureSigning**

Default roles with this permission: Administrator

<table><thead><tr><th width="259">Allows:</th><th>Result of denied permission</th></tr></thead><tbody><tr><td><ul><li>Sign an eSignature on step completion.</li></ul></td><td><p>Record Details</p><ul><li>Error message in e-Signature popup</li></ul></td></tr></tbody></table>

#### **Permission: CanEditCompletedSteps (LIMS v5.1 and Later)**

Default roles with this permission: None

<table><thead><tr><th width="259">Allows:</th><th>Result - permission granted</th></tr></thead><tbody><tr><td><ul><li>Edit button when viewing a completed step.</li><li>Select button to edit completed step details on Record Details screen.</li></ul></td><td><p>Assign Next Steps.</p><ul><li>Edit button displays.</li></ul><p>Record Details</p><ul><li>After clicking Edit button, Record Details fields are editable, as applicable/permitted.</li></ul></td></tr></tbody></table>

Modifications are limited to what is available on the Record Details screen for the step.

Details such as sample placement or routing cannot be modified.

Only steps completed after upgrading to LIMS v5.1 can be edited. Steps completed in v5.0 or earlier cannot be edited.

Steps that were executed using the Process API cannot be edited.

For details, see [modifying-completed-step-details](https://help.connected.illumina.com/clarity-lims/clarity-lims-v6.3-and-lablink-v2.5/clarity-lims-v6.3-reference-guide/lab-view/modifying-completed-step-details "mention").