Encore OS — Documentation

Purpose: Step-by-step guides for common data management workflows using PF-15 (Picklists), PF-16 (Custom Fields), PF-17 (Field Configuration), PF-23 (Object Browser), PF-24 (Custom Objects), PF-25 (Raw Data Editor), and PF-26 (Object Permissions).

Workflow 1: Adding Custom Data to Core Entities

Scenario: Add “Badge Number” field to HR Employees with validation Duration: 10-15 minutes
Prerequisites: Org admin access

Step 1: Create Picklist (Optional)

If the field needs dropdown options, create a picklist first:

Navigate to Settings → Picklists

Click + New Picklist

Fill in:

Name: employee_badge_prefix (snake_case)
Label: “Employee Badge Prefix”
Category: HR
Description: “Prefix codes for employee badges”

Click Create

Add items:

ADM - Administrative
CLN - Clinical
OPS - Operations
SUP - Support

Click Save

Code Example (Programmatic):

import { usePicklistMutation } from '@/platform/picklists';

const { createPicklist, createItem } = usePicklistMutation();

// Create picklist
const picklist = await createPicklist({
  name: 'employee_badge_prefix',
  label: 'Employee Badge Prefix',
  category: 'hr',
  description: 'Prefix codes for employee badges',
});

// Add items
await createItem({
  picklist_id: picklist.id,
  value: 'ADM',
  label: 'Administrative',
  display_order: 1,
});

Step 2: Define Custom Field

Navigate to Settings → Custom Fields

Click + New Field

Fill in:

Entity Type: hr_employees
Field Key: badge_number (snake_case, unique per entity)
Field Label: “Badge Number”
Field Type: text
Required: Yes

Validation Rules:

{
  "pattern": "^[A-Z]{3}-\\d{4}$",
  "minLength": 8,
  "maxLength": 8
}

Help Text: “Format: XXX-#### (e.g., ADM-1234)”
Placeholder: “ADM-1234”

Click Create

Code Example (Programmatic):

import { useCustomFieldMutation } from '@/platform/custom-fields';

const { createDefinition } = useCustomFieldMutation();

await createDefinition({
  entity_type: 'hr_employees',
  field_key: 'badge_number',
  field_label: 'Badge Number',
  field_type: 'text',
  is_required: true,
  validation_rules: {
    pattern: '^[A-Z]{3}-\\d{4}$',
    minLength: 8,
    maxLength: 8,
  },
  help_text: 'Format: XXX-#### (e.g., ADM-1234)',
  placeholder: 'ADM-1234',
  display_order: 100,
  field_group: 'Employment Details',
});

Step 3: Configure Field Layout (Optional)

Navigate to Settings → Field Configuration

Select entity: HR Employees

Select view context: Create Form or Edit Form

Find badge_number field

Configure:

Display Order: 15 (after employee_id)
Field Section: “Employment Details”
Column Span: 1
Visible to Roles: All (or specific roles)
Editable by Roles: HR Admin, Org Admin

Click Save

Code Example (Programmatic):

import { useFieldConfigMutation } from '@/platform/field-config';

const { createConfig } = useFieldConfigMutation();

await createConfig({
  entity_type: 'hr_employees',
  view_context: 'create_form',
  field_source: 'custom',
  field_key: 'badge_number',
  custom_field_definition_id: definitionId,
  display_order: 15,
  field_section: 'Employment Details',
  column_span: 1,
  is_visible: true,
  is_editable: true,
  editable_by_roles: ['hr_admin', 'org_admin'],
});

Step 4: Use in Employee Forms

Update HR employee form to include custom fields:

import { CustomFieldsSection } from '@/platform/custom-fields';

function EmployeeForm({ employee, onSubmit }) {
  const [formData, setFormData] = useState(employee);
  
  const handleCustomFieldChange = (fieldKey, value) => {
    setFormData(prev => ({
      ...prev,
      custom_fields: {
        ...prev.custom_fields,
        [fieldKey]: value,
      },
    }));
  };
  
  return (
    <Form onSubmit={handleSubmit}>
      {/* Standard fields */}
      <FormField name="first_name" />
      <FormField name="last_name" />
      
      {/* Custom fields */}
      <CustomFieldsSection
        entityType="hr_employees"
        values={formData.custom_fields}
        onChange={handleCustomFieldChange}
      />
      
      <Button type="submit">Save</Button>
    </Form>
  );
}

Step 5: View in Data Manager

Navigate to Data Manager

Find Employees object

Click to view details

Go to Fields tab

See badge_number in “Custom Fields” section

Go to Raw Data tab to see/edit badge numbers

Common Pitfalls:

❌ Forgetting to set display_order → Field appears at bottom
❌ Missing validation rules → Invalid data accepted
❌ Not grouping fields → Cluttered form
✅ Always test validation before deploying

Workflow 2: Creating a Custom Entity

Scenario: Create “Clinical Licenses” custom object to track employee certifications Duration: 20-30 minutes
Prerequisites: Org admin access

Step 1: Create Custom Object

Navigate to Data Manager

Click + New Object

Fill in wizard:

Step 1: Basic Information
- Name: “Clinical Licenses”
- API Name: clinical_licenses (auto-generated, can edit)
- Description: “Track clinical licenses and certifications for staff”
- Category: “HR & Workforce”
- Icon: “certificate” (or custom)
- Color: “blue”
Click Next

Step 2: Review → Click Create

Code Example (Programmatic):

import { useCustomObjectMutation } from '@/platform/data-manager';

const { createCustomObject } = useCustomObjectMutation();

const customObject = await createCustomObject({
  name: 'Clinical Licenses',
  api_name: 'clinical_licenses',
  description: 'Track clinical licenses and certifications for staff',
  category_id: categoryId, // From pf_object_categories
  icon: 'certificate',
  color: 'blue',
});

Step 2: Add Fields

Navigate to Data Manager → Clinical Licenses

Go to Fields tab

Click + Add Field

For each field: Field 1: Employee

Select existing field definition: “Employee Lookup” (or create new)
Required: Yes
Show in List: Yes
List Order: 1
Click Add

Field 2: License Type

Create new field definition:
- Field Key: license_type
- Field Type: select
- Picklist: “License Types” (create if needed)
Required: Yes
Show in List: Yes
List Order: 2
Click Add

Field 3: License Number

Create new field definition:
- Field Key: license_number
- Field Type: text
- Required: Yes
- Validation: Pattern ^[A-Z]{2}-\\d{6}$
Show in List: Yes
List Order: 3
Click Add

Field 4: Expiration Date

Create new field definition:
- Field Key: expiration_date
- Field Type: date
- Required: Yes
Show in List: Yes
List Order: 4
Click Add

Drag fields to reorder if needed

Code Example (Programmatic):

import { useCustomObjectFields } from '@/platform/data-manager';

const { addField } = useCustomObjectFields(customObjectId);

// Add employee lookup field
await addField({
  field_definition_id: employeeLookupDefId,
  is_required: true,
  show_in_list: true,
  list_order: 1,
});

// Add license type field (create definition first)
const licenseTypeDef = await createDefinition({
  entity_type: 'clinical_licenses',
  field_key: 'license_type',
  field_label: 'License Type',
  field_type: 'select',
  picklist_id: licenseTypesPicklistId,
  is_required: true,
});

await addField({
  field_definition_id: licenseTypeDef.id,
  is_required: true,
  show_in_list: true,
  list_order: 2,
});

Step 3: Create Records

Go to Records tab

Click + New Record

Fill in form:

Employee: Select from dropdown
License Type: Select from picklist
License Number: Enter (validated)
Expiration Date: Select date

Click Save

Code Example (Programmatic):

import { useCustomObjectRecords } from '@/platform/data-manager';

const { createRecord } = useCustomObjectRecords('clinical_licenses');

await createRecord({
  data: {
    employee_id: employeeId,
    license_type: 'RN',
    license_number: 'RN-123456',
    expiration_date: '2026-12-31',
  },
});

Step 4: Import Existing Data (Optional)

If you have existing license data in CSV:

Go to Records tab

Click Import

Step 1: Upload CSV file

Step 2: Map columns:

CSV “Employee Name” → “Employee” (lookup)
CSV “Type” → “License Type”
CSV “Number” → “License Number”
CSV “Expires” → “Expiration Date”

Step 3: Preview validation

Fix any errors highlighted in red

Step 4: Confirm import

Review success/failure count
Click Done

CSV Format:

Employee Name,Type,Number,Expires
John Smith,RN,RN-123456,2026-12-31
Jane Doe,LCSW,LC-789012,2025-06-30

Code Example (Programmatic):

import { useCSVImport } from '@/platform/data-manager';

const { importRecords } = useCSVImport('clinical_licenses');

const result = await importRecords(csvFile, {
  columnMapping: {
    'Employee Name': 'employee_id', // Lookup mapping
    'Type': 'license_type',
    'Number': 'license_number',
    'Expires': 'expiration_date',
  },
});

console.log(`Imported: ${result.imported}, Errors: ${result.errors.length}`);

Step 5: Configure Permissions

Go to Permissions tab (admin only)

Configure object-level permissions:

HR Admin: View, Create, Edit, Delete
HR Manager: View, Create, Edit
Staff: View only

Configure field-level permissions:

License Number: Hide from Staff role
Expiration Date: View only for HR Manager

Click Save

Code Example (Programmatic):

import { useObjectPermissions } from '@/platform/data-manager';

const { updateObjectPermissions } = useObjectPermissions('clinical_licenses');

await updateObjectPermissions({
  object_permissions: [
    {
      app_role: 'hr_admin',
      can_view: true,
      can_create: true,
      can_edit: true,
      can_delete: true,
    },
    {
      app_role: 'hr_manager',
      can_view: true,
      can_create: true,
      can_edit: true,
      can_delete: false,
    },
  ],
  field_permissions: [
    {
      field_key: 'license_number',
      app_role: 'staff',
      permission_level: 'hide',
    },
  ],
});

Common Pitfalls:

❌ Forgetting to set show_in_list → Fields don’t appear in table
❌ Missing required fields → Records can’t be created
❌ Invalid CSV format → Import fails
✅ Always test with sample data first

Workflow 3: Managing Organization Data Structure

Scenario: Organize all data objects by category and set up favorites Duration: 15-20 minutes
Prerequisites: Org admin or power user access

Step 1: Browse All Objects

Navigate to Data Manager
View objects table:
- Grouped by category (default)
- Search by name or API name
- Filter by type (Core vs Custom)
- Filter by favorites

Step 2: Manage Categories

Click Categories in Data Manager sidebar

Create Category:

Click + New Category
Name: “Clinical Operations”
Description: “Clinical and operational data”
Icon: “stethoscope”
Color: “green”
Click Create

Edit Category:

Click category row
Update name, description, icon, color
Click Save

Delete Category:

Click category row → Delete
Confirm (only if no objects assigned)

Code Example (Programmatic):

import { useCategoryMutation } from '@/platform/data-manager';

const { createCategory } = useCategoryMutation();

await createCategory({
  name: 'Clinical Operations',
  description: 'Clinical and operational data',
  icon: 'stethoscope',
  color: 'green',
  display_order: 5,
});

Step 3: Assign Objects to Categories

In Data Manager, click an object row

Go to Settings tab

Select Category: “Clinical Operations”

Click Save

Code Example (Programmatic):

import { useObjectMetadataMutation } from '@/platform/data-manager';

const { updateMetadata } = useObjectMetadataMutation();

await updateMetadata('hr_employees', {
  category_id: clinicalOpsCategoryId,
});

Step 4: Set Favorites

In Data Manager objects table

Click star icon on frequently-used objects

Filter by ★ Favorites to see only favorited objects

Favorites persist across sessions

Code Example (Programmatic):

import { useObjectFavorites } from '@/platform/data-manager';

const { toggleFavorite } = useObjectFavorites();

await toggleFavorite('hr_employees', true);

Step 5: Edit Object Metadata

Click object row → Settings tab

Update:

Display Name: Custom name for your org
Description: What this object is used for
Icon: Visual identifier
Category: Organize with related objects

Click Save

Common Pitfalls:

❌ Creating too many categories → Hard to navigate
❌ Not setting favorites → Slow to find objects
❌ Missing descriptions → Users don’t understand purpose
✅ Use consistent naming conventions

Workflow 4: Bulk Data Operations

Scenario: Export employee data, edit offline, import updates Duration: 30-45 minutes
Prerequisites: Org member access (view), org admin (import)

Step 1: Export Data

Navigate to Data Manager → Employees

Go to Raw Data tab

Apply filters if needed (e.g., specific department)

Click Export button

CSV downloads with:

All standard fields
All custom fields (from PF-16 definitions)
Current filter applied

Code Example (Programmatic):

import { useRawDataExport } from '@/platform/data-manager';

const { exportToCSV } = useRawDataExport('hr_employees');

// Export with filters
await exportToCSV({
  filters: {
    department_id: 'dept-123',
    employment_status: 'active',
  },
  includeCustomFields: true,
});

Step 2: Edit Offline

Open CSV in Excel, Google Sheets, or text editor

Make bulk edits:

Update multiple records
Add new records (follow CSV format)
Fix data errors

Important: Don’t modify:

id column (primary key)
organization_id (will be set automatically)
Column headers

Save CSV file

CSV Format:

id,first_name,last_name,email,department_id,custom_fields
uuid-1,John,Smith,john@example.com,dept-123,"{""badge_number"":""ADM-1234""}"
uuid-2,Jane,Doe,jane@example.com,dept-456,"{""badge_number"":""CLN-5678""}"

Important: Custom fields are exported as a single JSON column named custom_fields. The value is a JSON object stored as a string within the CSV cell (with quotes escaped as ""). When editing custom fields in Excel or Google Sheets:

Keep the JSON structure valid: {"field_key":"value","another_field":"value2"}

Escape internal quotes by doubling them: "{""badge_number"":""ADM-1234""}"

Do not add spaces inside the JSON unless they are part of the value

To add a new custom field, include it in the JSON: "{""badge_number"":""ADM-1234"",""employee_code"":""E001""}"

The system validates JSON syntax on import and will flag rows with malformed custom_fields.

Step 3: Import Updates

Go back to Raw Data tab

Click Import button

Step 1: Upload

Select CSV file
Click Upload

Step 2: Map Columns

System auto-detects column mappings
Verify mappings are correct
Fix any mismatches

Step 3: Preview

Review validation results
Green: Valid rows
Red: Errors (fix before importing)
Yellow: Warnings (review but can import)

Step 4: Confirm

Review summary:
- Total rows: 150
- Valid: 148
- Errors: 2
Click Import to proceed

Step 5: Results

Success: 148 rows imported
Errors: 2 rows failed (download error report)
Click Done

Code Example (Programmatic):

import { useRawDataImport } from '@/platform/data-manager';

const { importFromCSV } = useRawDataImport('hr_employees');

const result = await importFromCSV(csvFile, {
  columnMapping: {
    'first_name': 'first_name',
    'last_name': 'last_name',
    'email': 'email',
    'Badge Number': 'custom_fields.badge_number', // Custom field mapping
  },
  updateExisting: true, // Update records with matching id
  createNew: false, // Don't create new records
});

if (result.errors.length > 0) {
  console.error('Import errors:', result.errors);
  // Download error report
  downloadErrorReport(result.errors);
}

Step 4: Verify Import

Go to Raw Data tab

Verify updated records show new values

Check error report if any failures

Re-import fixed rows if needed

Common Pitfalls:

❌ Modifying id column → Creates duplicates
❌ Wrong date format → Validation fails
❌ Missing required fields → Rows rejected
❌ Custom field JSON format wrong → Data not saved
✅ Always export first to see format
✅ Test with 5-10 rows before bulk import

Workflow 5: Configuring Field-Level Permissions

Scenario: Hide salary field from non-HR users Duration: 10 minutes
Prerequisites: Org admin access

Step 1: Navigate to Object Permissions

Go to Data Manager → Employees

Click Permissions tab (admin only)

View permission matrix

Step 2: Configure Object-Level Permissions

In Object Permissions section:
- HR Admin: ✅ View, ✅ Create, ✅ Edit, ✅ Delete
- HR Manager: ✅ View, ✅ Create, ✅ Edit, ❌ Delete
- Staff: ✅ View, ❌ Create, ❌ Edit, ❌ Delete
Click Save Object Permissions

Step 3: Configure Field-Level Permissions

Scroll to Field Permissions section

Find salary field (or custom field)

Set permissions per role:

HR Admin: Edit
HR Manager: View
Staff: Hide

Click Save Field Permissions

Code Example (Programmatic):

import { useFieldPermissions } from '@/platform/data-manager';

const { updateFieldPermissions } = useFieldPermissions('hr_employees');

await updateFieldPermissions({
  field_key: 'salary',
  permissions: [
    {
      app_role: 'hr_admin',
      permission_level: 'edit',
    },
    {
      app_role: 'hr_manager',
      permission_level: 'view',
    },
    {
      app_role: 'staff',
      permission_level: 'hide',
    },
  ],
});

Step 4: Verify Permissions

Navigate to HR → Employees → [Employee]

Verify salary field is hidden

Verify salary field is visible but read-only

Common Pitfalls:

❌ Forgetting to save → Changes not applied
❌ Hiding required fields → Forms break
❌ Too restrictive → Users can’t do their job
✅ Test with different roles after configuring

Troubleshooting

Custom Fields Not Appearing

Symptoms: Field defined but not showing in form Solutions:

Check field is active (is_active = true)

Verify field configuration (PF-17) allows visibility

Check user role has permission to view field

Verify CustomFieldsSection component is in form

Check browser console for errors

Picklist Items Not Loading

Symptoms: Dropdown empty or loading forever Solutions:

Verify picklist exists and is active

Check picklist has items (is_active = true)

Verify usePicklistItems hook is called correctly

Check QueryClient staleTime/gcTime configuration

Verify organization context is set

Import Validation Errors

Symptoms: CSV import fails with validation errors Solutions:

Check CSV format matches export format

Verify required fields are present

Check data types match field definitions

Validate custom field JSON format

Review error report for specific issues

Permissions Not Working

Symptoms: Users can see/edit fields they shouldn’t Solutions:

Verify RLS policies are enabled

Check object-level permissions are set

Verify field-level permissions are configured

Check user role assignment

Clear browser cache and re-login

Best Practices

Custom Fields

✅ Use descriptive field keys (snake_case)
✅ Add help text for complex fields
✅ Set validation rules to prevent bad data
✅ Group related fields in sections
✅ Test validation before deploying

Custom Objects

✅ Use clear, descriptive names
✅ Follow API naming conventions (snake_case)
✅ Set appropriate categories
✅ Add helpful descriptions
✅ Test with sample data first

Data Management

✅ Organize objects into logical categories
✅ Set favorites for frequently-used objects
✅ Keep object metadata up-to-date
✅ Use consistent naming conventions
✅ Document custom objects for team

Bulk Operations

✅ Always export first to see format
✅ Test import with small dataset
✅ Validate data before importing
✅ Keep backups before bulk changes
✅ Review error reports carefully

Last Updated: 2026-01-08
Next Review: When new workflows are added or existing workflows change

​Workflow 1: Adding Custom Data to Core Entities

​Step 1: Create Picklist (Optional)

​Step 2: Define Custom Field

​Step 3: Configure Field Layout (Optional)

​Step 4: Use in Employee Forms

​Step 5: View in Data Manager

​Workflow 2: Creating a Custom Entity

​Step 1: Create Custom Object

​Step 2: Add Fields

​Step 3: Create Records

​Step 4: Import Existing Data (Optional)

​Step 5: Configure Permissions

​Workflow 3: Managing Organization Data Structure

​Step 1: Browse All Objects

​Step 2: Manage Categories

​Step 3: Assign Objects to Categories

​Step 4: Set Favorites

​Step 5: Edit Object Metadata

​Workflow 4: Bulk Data Operations

​Step 1: Export Data

​Step 2: Edit Offline

​Step 3: Import Updates

​Step 4: Verify Import

​Workflow 5: Configuring Field-Level Permissions

​Step 1: Navigate to Object Permissions

​Step 2: Configure Object-Level Permissions

​Step 3: Configure Field-Level Permissions

​Step 4: Verify Permissions

​Troubleshooting

​Custom Fields Not Appearing

​Picklist Items Not Loading

​Import Validation Errors

​Permissions Not Working

​Best Practices

​Custom Fields

​Custom Objects

​Data Management

​Bulk Operations

​Related Documentation

Workflow 1: Adding Custom Data to Core Entities

Step 1: Create Picklist (Optional)

Step 2: Define Custom Field

Step 3: Configure Field Layout (Optional)

Step 4: Use in Employee Forms

Step 5: View in Data Manager

Workflow 2: Creating a Custom Entity

Step 1: Create Custom Object

Step 2: Add Fields

Step 3: Create Records

Step 4: Import Existing Data (Optional)

Step 5: Configure Permissions

Workflow 3: Managing Organization Data Structure

Step 1: Browse All Objects

Step 2: Manage Categories

Step 3: Assign Objects to Categories

Step 4: Set Favorites

Step 5: Edit Object Metadata

Workflow 4: Bulk Data Operations

Step 1: Export Data

Step 2: Edit Offline

Step 3: Import Updates

Step 4: Verify Import

Workflow 5: Configuring Field-Level Permissions

Step 1: Navigate to Object Permissions

Step 2: Configure Object-Level Permissions

Step 3: Configure Field-Level Permissions

Step 4: Verify Permissions

Troubleshooting

Custom Fields Not Appearing

Picklist Items Not Loading

Import Validation Errors

Permissions Not Working

Best Practices

Custom Fields

Custom Objects

Data Management

Bulk Operations

Related Documentation