Securing with Access Rights
Roles vs Permissions vs Access Rights
Keep these three concepts separate — they are managed by different tools and control different things:
Golden rule: Roles and Permissions protect actions; Access Rights protect data. Fine-grained data security is enforced by AR rules, not by roles alone. Managing Roles or Permissions themselves is out of scope for this skill.
Access Rights Mental Model
Access rights control which data cells a member can read or write, based on dimension values.
Two layers:
- Default access rights: assigned per Role (Read/Write defaults on the Roles page)
- Specific access rights: custom AR metrics with Apply and Ignore rules in Data Access Rights settings
When multiple rules apply to the same Role x dimension combination, the most restrictive wins. BLANK in an AR metric is restrictive (No Read / No Write).
Access rights inherit along the metric dependency graph: if Metric B references Metric A, A's access rules flow to B unless cleared.
AR Components
- AR Metric: Access Rights-typed metric dimensioned by Role (or User) x secured dimension. Formula returns read/write settings per combination.
- Apply Rule: Links an AR metric to target metrics, lists, or all metrics using specific dimensions.
- Ignore Rule: Exempts specific metrics or blocks from an otherwise broad Apply rule.
Building an AR metric and applying it are two separate steps. Never skip the Apply rule after creating the metric.
Build an AR Metric Step by Step
Step 1 -- Choose Role-based or User-based dimensioning
Role-based (recommended): Dimension by Role x secured dimension. Assign members to roles via Users roles. Scales cleanly.
User-based: Dimension by User x secured dimension. Use only when individual exceptions cannot be expressed through roles.
Step 2 -- Create the AR metric
Use tool:create_metric with data type Access Rights, dimensioned by Role x the dimension to secure. Example: [Role] x [Country].
Step 3 -- Populate allowed combinations
Use tool:update_metric. Set TRUE (via ACCESSRIGHTS) only for allowed pairs; leave all others BLANK (never FALSE).
Read-only access:
Critical: BLANK means no access and is not stored (sparse). FALSE also denies access but is stored and degrades performance. Always prefer BLANK.
Step 4 -- Wrap in IFDEFINED for performance
Users with no role produce BLANK, skipping expensive evaluation. Ensure administrators retain access:
Step 5 -- Create Apply rules
No agent tool exists for creating Apply/Ignore rules; ask the user to configure them in the Pigment UI (Application Settings -> Roles, permissions & access -> Data access rights):
- Add a rule, set scope to Apply
- Select the AR metric
- Target: specific metrics, specific lists, or all metrics using specific dimension(s)
- Enable the rule
Use Ignore rules to exempt metrics from the broad Apply rule.
Formula Patterns for Access Control
ACCESSRIGHTS(ReadBoolean, WriteBoolean): Convert boolean flags into Access Rights values inside the AR metric.IFDEFINED('Users roles', ...): Skip AR computation for users without role assignments.RESETACCESSRIGHTS(expression): Clear inherited AR from a referenced block; essential in PULL metrics from source apps.
Apply RESETACCESSRIGHTS to the specific expression referencing the shared block:
No agent tool exists for the RESETACCESSRIGHTS setting. Ask the user to enable "Use RESETACCESSRIGHTS() to remove inherited access rights for Blocks shared from other Applications" in Data access -> Manage inheritance.
Multi-Application AR from a Hub
- Define master AR metrics in the Hub (Role x Country, Role x Cost Center)
- Share AR-related dimensions and mapping metrics via Libraries
- In consuming apps, reference Hub AR metrics or PULL secured data
- Apply RESETACCESSRIGHTS on PULL expressions to prevent unintended inheritance
- Ask the user to create local Apply rules in each consuming app (no agent tool available)
Members need at least Read access in every application whose shared blocks they consume.
Debug "Why Can/Cannot This User See Data?"
- Role assignment: Confirm the user has a Role in Users roles for this application
- AR metric value: Check the AR metric at Role x dimension item; must be non-BLANK with Read enabled
- Apply rule coverage: Verify an enabled Apply rule targets the metric or dimension
- Ignore rules: Check whether an Ignore rule exempts the target block
- Inheritance chain: Dependency diagram with Show Access Rights mode is UI-only; ask the user to inspect. Trace referenced metrics for inherited restrictions
- Default vs specific: Compare Role default access with specific rules; most restrictive wins
- Public blocks: Blocks with Data visibility management set to Public override read restrictions (UI-only setting)
Critical AR Rules
- BLANK not FALSE for denied access -- same security, better performance
- IFDEFINED guard on every AR metric formula referencing Users roles
- Build then Apply: creating the metric alone does nothing until an Apply rule exists (no agent tool; ask user)
- Admin fallback: always preserve administrator access when restricting defaults
- List Item Values rules: protect list property values, not metric data; apply metric-level rules for data security
- Toggle rules: disable rules temporarily during maintenance rather than deleting them
Access Rights Anti-Patterns
Flag and fix these when auditing or building AR:
- AR applied at every step of a dependency chain: AR should be applied once at the end of a calculation chain (on the output metric), not on every intermediate step. Applying AR at each step multiplies scheduled computation time.
- AR applied before aggregation or filtering: Place AR after aggregation and filtering, not before. If AR restricts cells before aggregation, downstream totals may silently exclude data the user should see in aggregate form.
- Version/period-lock rules built on User instead of Role: Time-lock and version-lock rules (which periods are editable, which versions are closed) should be dimensioned by Role, mapped via
'Users roles'. Building them on User creates per-user maintenance overhead and breaks when users change roles. - Overly complex multi-condition AR formulas: When a single AR formula has 4+ nested IF/AND/OR conditions, split into named sub-rule metrics (e.g.
ARM_Country_Access,ARM_Period_Lock,ARM_Role_Write) and combine them in one final AR metric. Easier to debug and maintain. - One giant AR metric covering all dimensions: Instead of a single AR metric dimensioned by Role x Country x Department x Version x Month, create composable sub-rules per concern (geographic access, period lock, role write). Apply each independently or combine at the end. A single mega-metric is hard to debug and expensive to compute.
- Business logic embedded directly inside
ACCESSRIGHTS(...): Complex business rules (revenue thresholds, approval status, etc.) should be precomputed into boolean metrics outside the AR formula. The AR formula should reference those booleans, not re-derive them. Keeps AR formulas auditable and separates security from business logic. - User x Time dimensioned AR when Role x Time suffices: If every user in a Role has identical time-based access, dimension the AR by Role x Time (not User x Time). User-level time dimensions multiply computation by user count for no benefit.
- Security enforced only via Board visibility: Hiding data on boards does not prevent access via Block Explorer, API, or other boards. Real data security requires AR metrics with Apply rules, not just board layout choices.
