CSV Upload

If your organization doesn't use a compatible HIMS with API integration, you can upload your caseload data using CSV files. This guide explains how to prepare your data in the correct aggregate format and upload it to Optimal Workforce.

Optimal Workforce works with aggregate data only. Your CSV file must never contain:

• Names of clients or employees
• Street addresses or specific locations
• Health information or diagnoses
• Any personally identifiable information (PII)
• Any protected health information (PHI)

Only include region identifiers, geographic codes (like postal codes), and numeric metrics.

When to Use CSV Upload

CSV upload is ideal when:

• Your HIMS doesn't have API integration with Optimal Workforce
• You want to test the platform with sample data
• You need to combine data from multiple sources
• You prefer manual control over when data is updated

Required Data Format

Your CSV file must contain aggregate metrics organized by geographic area. This is fundamentally different from individual client or employee records.

Required Columns

Metric Columns

Include one or more numeric columns representing the metrics you want to monitor and optimize:

You can include any numeric metrics relevant to your operations. The column names should be descriptive.

Example CSV Format

Here is an example of a correctly formatted CSV file:

Region,PC,Active_Clients,Available_PSWs,Visit_Count_per_Week
Region-1,M1L,120,53,369
Region-1,M1N,25,33,93
Region-1,M4A,12,25,43
Region-1,M4B,89,49,434
Region-2,M4C,180,61,622
Region-2,M4J,98,66,420
Region-3,M3C,149,64,729
Region-3,M4G,65,57,153

Key Rules

1. No overlap between regions - Each geographic identifier (postal code) must belong to exactly one region
2. All metrics must be numeric - Use whole numbers or decimals, no text
3. Consistent region names - Use the same spelling and format for each region throughout
4. One row per geographic area - Each postal code appears only once

Preparing Your Data

Step 1: Aggregate Your Source Data

If your scheduling system contains individual client and employee records, you'll need to summarize this data before uploading:

1. Group records by postal code or geographic area
2. Count clients, workers, and visits per area
3. Assign each area to a region (no overlaps)
4. Export as CSV

Step 2: Verify Your Format

Before uploading, check that your file:

• Has a header row with column names
• Contains only aggregate counts, not individual records
• Uses consistent region names throughout
• Has no empty rows or malformed data

Step 3: Review for Personal Information

Carefully verify that your file does not contain:

• Any names (client, employee, or otherwise)
• Any addresses beyond postal/ZIP codes
• Any health or clinical information
• Any unique identifiers that could identify individuals

Uploading Your File

Step 1: Navigate to Data Sources

1. Click Data Sources in the sidebar
2. Click Upload CSV or Add Data Source
3. Select CSV Upload

Step 2: Upload and Preview

1. Click Choose File or drag and drop your CSV
2. The system will analyze your file and show a preview
3. Review the first few rows to confirm the data looks correct

Step 3: Map Your Columns

The system will attempt to identify your columns. Verify:

1. The Region column is correctly identified
2. The Geographic Identifier column (postal code) is mapped
3. Metric columns are recognized as numeric data

Step 4: Complete the Upload

1. Review the summary showing row counts
2. Click Import Data or Complete Upload
3. Wait for the import to finish

After Upload

Once your data is uploaded:

• Navigate to Monitoring to see your caseload distribution by region
• Run an optimization to generate recommendations for rebalancing
• Upload new data periodically to keep the platform current

Updating Your Data

To update your caseload data:

1. Prepare a fresh CSV with current aggregate metrics
2. Navigate to Data Sources
3. Upload the new file

The new upload replaces your existing data. Always include all regions and areas, not just changes.

File Requirements

Supported Formats

• CSV (.csv)
• Excel (.xlsx, .xls)

File Size Limits

• Maximum file size: 50MB
• Maximum rows: 100,000

Character Encoding

• UTF-8 encoding recommended
• If you see garbled characters, save your file with UTF-8 encoding

Common Errors

"Region overlap detected"

Two or more regions contain the same postal code. Each geographic identifier must belong to exactly one region.

Fix: Review your data and ensure each postal code appears in only one region.

"Non-numeric value in metric column"

A metric column contains text instead of numbers.

Fix: Ensure all metric columns contain only numeric values. Remove any text, symbols, or empty cells.

"Missing required column"

The file is missing a Region or Geographic Identifier column.

Fix: Verify your file has columns for both region names and geographic codes.

"Duplicate geographic identifier"

The same postal code appears more than once in your file.

Fix: Each postal code should have exactly one row. Combine any duplicate rows.

Best Practices

Regular Updates

For accurate monitoring and optimization, update your data regularly:

• Weekly - Recommended for active caseload management
• Monthly - Minimum for meaningful insights
• Before optimization - Always upload current data before running an optimization

Version Control

Keep track of your uploaded files:

• Save each upload with a date in the filename (e.g., "caseload_2025-01-15.csv")
• Keep a backup of each file you upload
• Document any changes between versions

Data Consistency

Use the same format for every upload:

• Same region names (spelling and capitalization)
• Same column names
• Same geographic identifier format