Understanding Your Data

This guide explains how your caseload data flows through Optimal Workforce and what you need to know to get the most value from the platform.

The Aggregate Data Model

Optimal Workforce works with aggregate metrics rather than individual records. This means the platform analyzes summarized counts and totals organized by geographic region.

Data Structure

Your data is organized in three layers:

1. Regions - Named groupings of geographic areas (e.g., "Region-1", "North District")
2. Geographic Identifiers - Specific locations within each region, typically postal codes
3. Metrics - Numeric values for each geographic area

Example

Instead of tracking individual assignments like:

• "Jane Smith serves Client A at 123 Main St"
• "Jane Smith serves Client B at 456 Oak Ave"

Optimal Workforce tracks aggregate metrics like:

• "Postal code M4A: 120 active clients, 53 available workers, 369 visits/week"
• "Postal code M1N: 25 active clients, 33 available workers, 93 visits/week"

This approach protects privacy while enabling powerful optimization.

How Data Flows

With API Integration

When connected to your HIMS via API:

1. Initial Sync - Optimal Workforce pulls data from your system and aggregates it automatically
2. Regular Updates - Aggregate metrics are refreshed on a regular schedule (typically daily)
3. On-Demand Refresh - You can manually trigger a sync when you need the latest totals

The sync process reads from your system and calculates aggregates - it never makes changes to your source data.

With CSV Upload

When uploading CSV files:

1. Manual Preparation - You aggregate your data into the required format before uploading
2. Data Replacement - Each upload replaces the previous dataset
3. Your Schedule - You control when data is updated

What Data Is Used

Optimal Workforce uses your aggregate metrics for three main purposes:

1. Monitoring Dashboard

The dashboard shows your current state:

• Total clients and workers per region
• Geographic distribution across postal codes
• Workload balance indicators
• Regional comparisons

2. Optimization Engine

When you run an optimization, the system uses:

• Current metric values per geographic area
• Region definitions and boundaries
• Workload distribution patterns

3. Results Comparison

After optimization, you can compare:

• Before and after regional distributions
• Projected improvements in balance
• Changes to geographic assignments

Data Freshness

Why Fresh Data Matters

Stale data leads to:

• Inaccurate dashboards - Metrics don't reflect current reality
• Poor optimization - Recommendations based on outdated distributions
• Wasted effort - Implementing changes that don't match the actual situation

Recommended Update Frequency

Checking Your Data Age

To see when your data was last updated:

1. Navigate to Data Sources
2. Look for the "Last Synced" or "Last Updated" timestamp
3. If using API, check the sync status indicator

Data Quality

What Makes Good Data

High-quality aggregate data has these characteristics:

• Complete - All regions and geographic areas are included
• Accurate - Counts reflect actual current state
• Current - Recent changes are captured
• Consistent - Region names and formats are uniform

Common Data Issues

Missing Geographic Areas Some postal codes or areas aren't appearing. This may happen when:

• Areas have no active clients or workers
• The region isn't selected in your API configuration
• CSV data is incomplete

Region Overlap The same geographic identifier appears in multiple regions. Each postal code must belong to exactly one region.

Inconsistent Region Names "Region-1" vs "Region 1" vs "region-1" are treated as different regions. Use consistent naming throughout.

Non-Numeric Metrics Metric columns contain text instead of numbers. All metric values must be numeric.

Viewing Data Quality Indicators

The platform flags potential issues:

• Warning indicators on the Data Sources page
• Validation results after CSV upload
• Data quality notes in the dashboard

Address these issues in your source data for best results.

What Optimal Workforce Stores

What Is Stored

• Aggregate counts per geographic area
• Region definitions
• Optimization history and results
• Sync history

What Is NOT Stored

Optimal Workforce does not store or access:

• Individual client names or identifiers
• Individual employee names or identifiers
• Street addresses or specific locations
• Personal health information (PHI)
• Clinical notes or care plans
• Financial or billing information

The platform only uses aggregate operational metrics needed for caseload optimization.

Viewing Your Data

You can explore your data in several places:

• Monitoring Dashboard - Visual overview of regional distribution
• Regional Map - Geographic view of metrics by area
• Data Sources - Connection status and sync history

Data Retention

Your data is retained in Optimal Workforce:

• Active data - Your current aggregate snapshot
• Optimization history - Results from past optimization runs
• Sync history - Record of data updates

Contact Optimal Workforce support to request data deletion if needed.

Troubleshooting Data Issues

"No data available"

If dashboards show no data:

1. Check your data source connection status
2. Verify at least one region is selected (for API connections)
3. Confirm your CSV upload completed successfully
4. Wait for the sync to complete if it's in progress

"Metrics don't match my expectations"

If you see discrepancies:

1. Check when data was last synced
2. Trigger a manual refresh if available
3. For CSV, verify your aggregation process and upload fresh data
4. For API, verify permissions include all required data

"Missing regions"

If some regions aren't appearing:

1. Check region selection in your API configuration
2. Verify the regions exist in your source data
3. For CSV, ensure all regions are included in your file

Best Practices

For API Users

• Monitor sync status regularly
• Investigate sync errors promptly
• Review aggregate data after major changes in your HIMS
• Add regions as your service area expands

For CSV Users

• Establish a regular upload routine
• Double-check aggregation before uploading
• Keep backup copies of uploaded files
• Upload fresh data before important optimization runs