Object Permissions Tab V2 Migration Plan

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Current State (V1)

• Uses hardcoded ORDERED_ROLES array (only 5 core roles)
• Uses hardcoded ROLE_CONFIG object
• Doesn’t include all system roles (18 total, only shows 5)
• Doesn’t support custom roles
• Role list is static and doesn’t reflect database state

• src/platform/data-manager/components/ObjectPermissionsTab.tsx - Main component
• src/platform/data-manager/components/ObjectPermissionMatrix.tsx - Matrix display
• src/platform/data-manager/types/permissions.ts - Type definitions with V1 constants

​

Target State (V2)

• Fetch all system roles dynamically (all 18 roles from app_role enum)
• Support custom roles (when PF-26 is updated to support them)
• Use V2 permission system hooks
• Remove hardcoded role constants
• Make role list dynamic and database-driven

• Use useAvailableRoles() hook to fetch roles
• Update ObjectPermissionsTab to use dynamic roles
• Update ObjectPermissionMatrix to work with dynamic roles
• Keep PF-26 tables (pf_object_permissions, pf_field_permissions) - these are V2 compatible

​

Migration Steps

​

Step 1: Create Role Fetching Hook ✅

​

Step 2: Update ObjectPermissionsTab ✅

1. Replace ORDERED_ROLES import with useAvailableRoles() hook
2. Update role initialization to use dynamic roles
3. Remove dependency on hardcoded ROLE_CONFIG
4. Use role labels from hook

• src/platform/data-manager/components/ObjectPermissionsTab.tsx ✅

​

Step 3: Update ObjectPermissionMatrix ✅

1. Remove ROLE_CONFIG import
2. Use dynamic role labels from props (via PermissionMatrixRow.roleLabel)
3. Remove sorting logic (parent component handles ordering)

• src/platform/data-manager/components/ObjectPermissionMatrix.tsx ✅

​

Step 4: Update FieldPermissionsSection ✅

1. Replace ORDERED_ROLES and ROLE_CONFIG with useAvailableRoles() hook
2. Use getRoleLabel() helper for display names
3. Filter roles dynamically (exclude platform_admin and org_admin)

• src/platform/data-manager/components/FieldPermissionsSection.tsx ✅

​

Step 5: Update Type Definitions ✅

1. Mark ORDERED_ROLES and ROLE_CONFIG as deprecated
2. Add migration notes
3. Keep types for backward compatibility during transition

• src/platform/data-manager/types/permissions.ts ✅

​

Step 6: Testing ⏳

1. Verify all 18 system roles appear in matrix
2. Verify role ordering is correct
3. Verify permissions can be saved for all roles
4. Verify custom roles appear (when supported)
5. Verify backward compatibility with existing permissions

​

Implementation Details

​

Role Fetching

// V1 (Hardcoded)
import { ORDERED_ROLES, ROLE_CONFIG } from '../types/permissions';
const roles = ORDERED_ROLES; // Only 5 roles

// V2 (Dynamic)
import { useAvailableRoles } from '../hooks/useAvailableRoles';
const { roles } = useAvailableRoles(); // All 18 system roles + custom roles

​

Role Display

// V1 (Hardcoded)
const roleLabel = ROLE_CONFIG[role]?.label || role;

// V2 (Dynamic)
import { getRoleLabel } from '../hooks/useAvailableRoles';
const roleLabel = getRoleLabel(role);

​

Role Sorting

// V1 (Hardcoded)
const sorted = roles.sort((a, b) => {
  const orderA = ROLE_CONFIG[a.role]?.order ?? 99;
  const orderB = ROLE_CONFIG[b.role]?.order ?? 99;
  return orderA - orderB;
});

// V2 (Dynamic)
import { getRoleOrder } from '../hooks/useAvailableRoles';
const sorted = roles.sort((a, b) => 
  getRoleOrder(a.role) - getRoleOrder(b.role)
);

​

Database Compatibility

• pf_object_permissions - Uses app_role enum (supports all system roles)
• pf_field_permissions - Uses app_role enum (supports all system roles)

• Tables already support all system roles
• Migration is UI-only (removing hardcoded constants)

​

Custom Roles Support (Future)

• Update pf_object_permissions.role column to support both app_role and custom role IDs
• Or create separate pf_object_permissions_custom table
• Update useAvailableRoles() to include custom roles when supported

​

Rollback Plan

1. Revert to using ORDERED_ROLES and ROLE_CONFIG constants
2. Component will continue to work (just shows fewer roles)
3. No data loss (all permissions remain in database)

​

Testing Checklist

• All 18 system roles appear in permission matrix
• Roles are sorted correctly (by order)
• Role labels display correctly
• Permissions can be saved for all roles
• Existing permissions load correctly
• Field permissions work with all roles
• Site scope configuration works
• Component handles loading states
• Component handles error states
• No console errors or warnings

​

Timeline

• 2026-01-26: Migration plan created, useAvailableRoles hook created ✅
• 2026-01-26: Updated ObjectPermissionsTab component ✅
• 2026-01-26: Updated ObjectPermissionMatrix component ✅
• 2026-01-26: Updated FieldPermissionsSection component ✅
• 2026-01-26: Updated type definitions with deprecation notices ✅
• 2026-XX-XX: Testing and validation ⏳
• 2026-03-31: Sunset date - V1 constants can be removed after this date

​

See Also

• PF-26 Object Permissions Spec
• PF-30 Permissions System V2 Spec
• Permissions System Guide