Compass - Nimbly Documentation

Data Visibility Backend

4 min read

1. Overview

This code is part of Nimbly Common, which provides shared utilities across multiple services.
To determine a user’s data access level, you can import the getDataVisibility function internally in any repo where visibility rules need to be enforced. The getDataVisibility function determines the level of data visibility a user has based on their role and permissions.

System Integration Points:

2. Libraries Used

No external libraries are used in the implementation of the data visibility rules. The logic relies on TypeScript constructs and internal enumerations and constants.

3. Specific File Paths

3.1. Core Logic: src/functions/common/dataVisibility.ts

Contains the getDataVisibility function, which evaluates permissions and roles to determine the appropriate DataVisibility value.

3.2. Enumerations: src/enumerators/dataVisibility.ts

Defines the DataVisibility enum, representing the possible visibility levels:

  • ALL   - SPECIFIC_SITE   - SPECIFIC_DEPT   - SPECIFIC_DEPT_SITE

3.3. User Roles: src/models/entities/userRole.ts

  • Defines the userRoles constants and the UserRole type, which are used to evaluate the user’s role in the getDataVisibility function.
  • Integrates with Admin, Supervisor, Auditor, and Account Holder role definitions.

4. Visibility Levels

Visibility levels define what portion of organisational data a user can access:

  • ALL: User can access all sites and departments within the organisation.

  • SPECIFIC_DEPT: User can access data for all sites, but only for the department they are part of.

  • SPECIFIC_SITE: User can access data for all departments, but only for the site they are part of.

  • SPECIFIC_DEPT_SITE: User can access data only for the specific site and department they are associated with.

5. Data Visibility Implementation

The data visibility rules are calculated using a combination of permission-based and role-based evaluations:

5.1. Function Signature

 
export const getDataVisibility = (resourceMap: { [access: string]: any }, role: string): DataVisibility

5.2. Parameters

  1. resourceMap (Object):

  • A map of access rules and their associated permissions.

  • Example structure:

{
  "data-visibility:rules:all": { "permission": ["view"] },
 
  "data-visibility:rules:specific-dept": { "permission": ["view"] }
}
  • Purpose: Defines the permissions for various data visibility rules.
  1. role (String):

  • The role of the user (e.g., SUPERADMIN, ADMIN, SUPERVISOR). User Roles

  • Purpose: Specifies the user’s role to determine fallback visibility if no permissions match.

5.3. Return Value

The function returns a value of the DataVisibility enumerator, which can be one of the following:

  • DataVisibility.ALL: Full access to all data.

  • DataVisibility.SPECIFIC_DEPT: Access limited to a specific department.

  • DataVisibility.SPECIFIC_SITE: Access limited to a specific site.

  • DataVisibility.SPECIFIC_DEPT_SITE: Access limited to a specific department and site.

5.4. Logic Breakdown

  1. Permission-Based Rules:

    If the resourceMap contains specific permissions, the function checks for the following rules in order:

 
if (resourceMap["data-visibility:rules:all"]?.permission.includes("view"))
  return DataVisibility.ALL;
 
if (
  resourceMap["data-visibility:rules:specific-dept"]?.permission.includes(
    "view",
  )
)
  return DataVisibility.SPECIFIC_DEPT;
 
if (
  resourceMap["data-visibility:rules:specific-site"]?.permission.includes(
    "view",
  )
)
  return DataVisibility.SPECIFIC_SITE;
 
if (
  resourceMap["data-visibility:rules:specific-site-dept"]?.permission.includes(
    "view",
  )
)
  return DataVisibility.SPECIFIC_DEPT_SITE;

  • data-visibility:rules:all → Returns DataVisibility.ALL.

  • data-visibility:rules:specific-dept → Returns DataVisibility.SPECIFIC_DEPT.

  • data-visibility:rules:specific-site → Returns DataVisibility.SPECIFIC_SITE.

  • data-visibility:rules:specific-site-dept → Returns DataVisibility.SPECIFIC_DEPT_SITE.

  1. Role-Based Fallback:

    If no permissions match, the function uses the user’s role to determine visibility:

switch (role) {
  case userRoles.SUPERADMIN:
  case userRoles.ACCOUNT_HOLDER:
  case userRoles.ADMIN:
    return DataVisibility.ALL;
 
  case userRoles.SUPERVISOR:
  case userRoles.AUDITOR:
    return DataVisibility.SPECIFIC_DEPT_SITE;
 
  default:
    return DataVisibility.SPECIFIC_DEPT_SITE;
}

6. Example Usage

import { getDataVisibility } from "./dataVisibility";
 
import { DataVisibility } from "../../enumerators";
 
const resourceMap = {
  "data-visibility:rules:all": { permission: ["view"] },
 
  "data-visibility:rules:specific-dept": { permission: [] },
};
 
const role = "ADMIN";
 
const visibility = getDataVisibility(resourceMap, role);
 
console.log(visibility); // Output: DataVisibility.ALL

7. Notes

  • Ensure the resourceMap is correctly structured to avoid unexpected results.
  • The function assumes that roles and permissions are predefined and consistent with the application’s access control policies.

Graph View