> ## 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.

# Use Case Guide: Data Manager (PF-23/24/25)

> System: Platform Foundation (PF) Features: Object Browser (PF-23) + Custom Objects (PF-24) + Raw Data Editor (PF-25) Created: 2025-01-27 Updated: 2025-12-05 St…

**System:** Platform Foundation (PF)\
**Features:** Object Browser (PF-23) + Custom Objects (PF-24) + Raw Data Editor (PF-25)\
**Created:** 2025-01-27\
**Updated:** 2025-12-05\
**Status:** ✅ Complete

***

## Quick Reference

**When to Use Data Manager:**

* ✅ You need to **browse/discover** all data objects in system
* ✅ You need to **create new entity types** (custom objects)
* ✅ You need to **understand object structure** (fields, relationships)
* ✅ You need to **manage object metadata** (categories, descriptions)
* ✅ You need to **browse and edit records** (raw data editor)
* ✅ You need to **export data to CSV** (raw data export)

**When NOT to Use Data Manager:**

* ❌ You need to **create a form** → Use Form Builder (FW-01)
* ❌ You need to **extend existing entity** → Use Custom Fields (PF-16)
* ❌ You need to **control field visibility** → Use Entity Field Configuration (PF-17)

***

## What Is Data Manager?

Data Manager provides a **unified interface** for browsing, managing, and discovering data objects across the Encore Health OS platform. It consists of:

1. **Object Browser (PF-23)**: Browse all objects (core + custom), view metadata, manage categories
2. **Custom Objects (PF-24)**: Create new entity types with custom fields
3. **Raw Data Editor (PF-25)**: Browse, edit, and export records from core objects

**Key Characteristics:**

* Unified view of all data objects
* Object discovery and metadata management
* Custom object creation and management
* Category organization
* Favorites/bookmarks
* Raw data browsing and inline editing
* CSV export functionality

***

## Common Use Cases

### Use Case 1: Discover Available Objects

**Scenario:** You're new to the system and want to see what data objects exist (employees, residents, invoices, etc.).

**Solution:** Use Object Browser (PF-23)

**Why Object Browser:**

* Unified view of all objects
* Search and filter capabilities
* Category organization
* Object metadata (API names, descriptions)

**Implementation:**

1. Navigate to Settings → Data Manager
2. Browse objects by category (HR, Finance, Operations)
3. Search for specific objects
4. View object details (fields, metadata)
5. Favorite frequently-used objects

**Benefits:**

* Discover objects without navigating each module
* Understand object structure and relationships
* Quick access to frequently-used objects

***

### Use Case 2: Create Clinical Licenses Entity

**Scenario:** Your organization needs to track clinical licenses (RN, LCSW, etc.) with fields like license number, expiration date, renewal status.

**Solution:** Use Custom Objects (PF-24)

**Why Custom Objects:**

* New entity type (not extending existing entity)
* Need to track multiple records over time
* Need CRUD operations (create, read, update, delete)
* Need to query and report on records

**Implementation:**

1. Navigate to Settings → Data Manager
2. Click "Create Custom Object"
3. Enter object details:
   * Name: "Clinical Licenses"
   * API Name: `clinical_licenses`
   * Category: HR & Workforce
4. Add fields using PF-16 field definitions:
   * License Type (select, picklist: license\_types)
   * License Number (text, required)
   * Issue Date (date)
   * Expiration Date (date, required)
   * Status (select, picklist: license\_status)
5. Save object
6. Object appears in Data Manager
7. Create/manage records in object

**Not Forms Because:**

* Not one-time data capture (tracking records over time)
* Need CRUD operations (not just submissions)
* Need to query and report on records

**Not Custom Fields Because:**

* Not extending existing entity
* New entity type (not metadata on existing records)

***

### Use Case 3: Browse and Edit Employee Records

**Scenario:** You need to view all employees and update their custom field values (badge numbers, shirt sizes).

**Solution:** Use Raw Data Editor (PF-25)

**Why Raw Data Editor:**

* Browse records from core objects
* View standard + custom fields together
* Inline editing for custom fields
* Bulk export to CSV

**Implementation:**

1. Navigate to Settings → Data Manager
2. Click on "Employees" object
3. Select the "Raw Data" tab
4. Browse employee records with search and pagination
5. Click any custom field cell to edit inline
6. Make changes and click "Save Changes"
7. Use Export button to download CSV

**Benefits:**

* View all fields (standard + custom) in one table
* Edit custom field values without opening each record
* Export data for reporting or backup

***

### Use Case 4: Export Data to CSV

**Scenario:** You need to export all resident records to CSV for a compliance report.

**Solution:** Use Raw Data Editor Export (PF-25)

**Why Raw Data Editor:**

* Export ALL records (bypasses pagination)
* Includes standard + custom fields
* Applies current search filter
* Downloads as CSV

**Implementation:**

1. Navigate to Settings → Data Manager
2. Click on "Residents" object
3. Select the "Raw Data" tab
4. (Optional) Use search to filter records
5. Click the Export button (Download icon)
6. CSV file downloads with all matching records

**Export Features:**

* Column headers use field labels (not API keys)
* Date fields formatted as ISO 8601
* Boolean fields export as "Yes"/"No"
* Filename includes object name, record count, and date

***

### Use Case 5: Organize Objects by Category

**Scenario:** You want to organize objects into categories (HR, Finance, Operations) for easier navigation.

**Solution:** Use Object Browser (PF-23)

**Why Object Browser:**

* Category management
* Object categorization
* Filter by category

**Implementation:**

1. Navigate to Settings → Data Manager → Categories
2. Create/edit categories:
   * HR & Workforce
   * Finance & Accounting
   * Operations & Facilities
3. Assign objects to categories
4. Filter objects by category

**Benefits:**

* Organized object discovery
* Easier navigation
* Better user experience

***

### Use Case 6: View Object Structure

**Scenario:** You're building an integration and need to understand object structure (fields, API names, relationships).

**Solution:** Use Object Browser (PF-23)

**Why Object Browser:**

* Object detail view
* Field listing (standard + custom)
* API name display
* Metadata information

**Implementation:**

1. Navigate to Settings → Data Manager
2. Click on object (e.g., "Employees")
3. View object details:
   * API Name: `hr_employees`
   * Fields: Standard fields + custom fields
   * Category: HR & Workforce
   * Description: Object description
4. Use API name and field structure for integration

**Benefits:**

* Understand object structure
* Get API names for integration
* See all fields (standard + custom)

***

## When NOT to Use Data Manager

### ❌ Don't Use Data Manager For: Creating Forms

**Example:** "I need to create a resident intake form"

**Why Not Data Manager:**

* Not creating new entity type
* Creating data capture interface (form)
* One-time data capture (form submission)

**Use Instead:** Form Builder (FW-01)

***

### ❌ Don't Use Data Manager For: Extending Existing Entities

**Example:** "I need to add badge\_number to employees"

**Why Not Data Manager:**

* Not creating new entity type
* Extending existing entity (hr\_employees)
* Adding metadata field

**Use Instead:** Custom Fields (PF-16)

***

### ❌ Don't Use Data Manager For: Controlling Field Visibility

**Example:** "I want to hide salary field from non-admins"

**Why Not Data Manager:**

* Not creating new entity
* Controlling existing entity form
* Field visibility configuration

**Use Instead:** Entity Field Configuration (PF-17)

***

## Integration with Other Systems

### Data Manager + Custom Fields (PF-16)

**Use Case:** Custom object needs fields

**Example:** Clinical Licenses object needs license fields

**Implementation:**

1. Create custom object (PF-24)
2. Add fields using PF-16 field definitions
3. Fields appear in object detail view
4. Use fields in custom object records

**Benefits:**

* Reuse PF-16 field definitions
* Consistent field types and validation

***

### Data Manager + Picklists (PF-15)

**Use Case:** Custom object field needs dropdown values

**Example:** License Type field needs license types (RN, LCSW, etc.)

**Implementation:**

1. Create picklist: `license_types`
2. Create custom object field (PF-24)
3. Select field type: `select`
4. Choose picklist: `license_types`
5. Field renders with picklist values

**Benefits:**

* Reusable picklist values
* Consistent values across system

***

### Data Manager + Forms (FW-01)

**Use Case:** Form needs to reference custom object

**Example:** Intake form needs to select clinical license

**Implementation:**

1. Create custom object: Clinical Licenses (PF-24)
2. Create form (FW-01)
3. Add lookup field (FW-15):
   * Data Source: Table Lookup
   * Table: `pf_custom_object_records` (filtered by custom\_object\_id)
4. Form renders with licenses from custom object

**Benefits:**

* Forms can reference custom objects
* Real-time data from custom objects

***

## Decision Tree

```
I need to work with data objects
├─ Do I need to browse/discover objects?
│  ├─ Yes → Use Object Browser (PF-23) ✅
│  └─ No → Do I need to create a new entity type?
│       ├─ Yes → Use Custom Objects (PF-24) ✅
│       │   Example: Clinical Licenses, Training Classes
│       └─ No → Do I need to browse/edit records?
│            ├─ Yes → Use Raw Data Editor (PF-25) ✅
│            │   Example: View employees, edit custom fields, export CSV
│            └─ No → Do I need to extend an existing entity?
│                 ├─ Yes → Use Custom Fields (PF-16) ✅
│                 └─ No → Do I need to create a form?
│                      └─ Yes → Use Form Builder (FW-01) ✅
```

***

## Raw Data Editor Features (PF-25)

### Supported Tables

* `hr_employees` - Employee records
* `rh_residents` / `rh_resident_profiles` - Resident records
* `fa_invoices` - Invoice records
* `fa_vendors` - Vendor records
* `fa_customers` - Customer records
* `fw_forms` - Form definitions

### Feature Summary

| Feature            | Description                                           |
| ------------------ | ----------------------------------------------------- |
| **Browse Records** | View all records with pagination (25/50/100 per page) |
| **Search**         | Filter by name/identifier fields                      |
| **Sort**           | Click column headers to sort                          |
| **Inline Edit**    | Click custom field cells to edit in place             |
| **Batch Save**     | Save all changes at once                              |
| **CSV Export**     | Export all matching records to CSV                    |

### Export Details

* Exports ALL records matching current search (bypasses pagination)
* Column headers use field labels, not API keys
* Date fields formatted as ISO 8601 (YYYY-MM-DD)
* Boolean fields export as "Yes" / "No"
* Filename format: `{object_name}_{count}_records_{date}.csv`

***

## Examples by Module

### HR & Workforce

* **Custom Objects:**
  * Clinical Licenses (track licenses with expiration dates)
  * Training Classes (track training sessions)
  * Performance Goals (track employee goals)
* **Object Browser:**
  * Browse: Employees, Departments, Positions
  * View: Employee fields, custom fields
  * Manage: Object metadata, categories
* **Raw Data Editor:**
  * Browse employee records
  * Edit custom fields (badge numbers, etc.)
  * Export employee data to CSV

### Finance & Accounting

* **Custom Objects:**
  * Budget Categories (track budget categories)
  * Cost Centers (track cost centers)
  * Vendor Categories (track vendor types)
* **Object Browser:**
  * Browse: Invoices, Transactions, Accounts
  * View: Invoice fields, custom fields
  * Manage: Object metadata, categories
* **Raw Data Editor:**
  * Browse invoice records
  * Export invoice data for reporting

### Operations & Facilities

* **Custom Objects:**
  * Asset Types (track asset categories)
  * Maintenance Schedules (track maintenance)
  * Inventory Categories (track inventory types)
* **Object Browser:**
  * Browse: Work Orders, Assets, Inventory
  * View: Work order fields, custom fields
  * Manage: Object metadata, categories

***

## Best Practices

### 1. Use Descriptive API Names

✅ **Do:** Use snake\_case, descriptive names (`clinical_licenses`, `training_classes`)\
❌ **Don't:** Use abbreviations (`clin_lic`, `train_cls`)

### 2. Organize by Category

✅ **Do:** Assign objects to appropriate categories\
❌ **Don't:** Leave objects uncategorized

### 3. Add Object Descriptions

✅ **Do:** Add descriptions to objects (help users understand purpose)\
❌ **Don't:** Leave objects without descriptions

### 4. Use Favorites

✅ **Do:** Favorite frequently-used objects\
❌ **Don't:** Navigate to objects manually every time

### 5. Reuse Field Definitions

✅ **Do:** Use PF-16 field definitions for custom object fields\
❌ **Don't:** Create duplicate field definitions

### 6. Use Raw Data Editor for Bulk Updates

✅ **Do:** Use inline editing for bulk custom field updates\
❌ **Don't:** Open each record individually

***

## Common Mistakes

### Mistake 1: Using Custom Objects for Forms

**Problem:** Creating custom object for intake form\
**Solution:** Use Form Builder (FW-01) instead

### Mistake 2: Using Custom Objects for Entity Extension

**Problem:** Creating custom object to add badge\_number to employees\
**Solution:** Use Custom Fields (PF-16) instead

### Mistake 3: Not Using Categories

**Problem:** Objects not organized, hard to find\
**Solution:** Assign objects to categories

### Mistake 4: Not Adding Descriptions

**Problem:** Objects without descriptions, unclear purpose\
**Solution:** Add descriptions to all objects

### Mistake 5: Editing Standard Fields in Raw Data Editor

**Problem:** Trying to edit standard fields (read-only)\
**Solution:** Use module-specific forms for standard field updates; Raw Data Editor is for custom fields

***

## Related Documentation

* [PF-23: Object Browser Spec](../../../specs/pf/specs/PF-23-data-manager-object-browser.md)
* [PF-24: Custom Objects Spec](../../../specs/pf/specs/PF-24-custom-objects.md)
* [PF-25: Raw Data Editor Spec](../../../specs/pf/specs/PF-25-raw-data-editor.md)
* [PF-16: Custom Field Definitions Spec](../../../specs/pf/specs/PF-16-custom-field-definitions.md)
* [Custom Objects Use Case Guide](./custom-objects.md)
* [Clarity Analysis](./clarity-analysis.md)

***

**Last Updated:** 2025-12-05\
**Next Review:** After user feedback