Clari Upgrade & Migration

Overview

Handle Clari API changes: version migrations, export schema updates, and Copilot API adoption.

Prerequisites

• Current and target API/schema versions recorded in change control
• Representative non-production exports and an approved compatibility baseline
• Version-pinned client, warehouse migration, and rollback paths
• Data-owner approval for any field, retention, or analytics semantic change

Instructions

Step 1: Check Current API Version

# v4 is the current version
curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list | jq .

# If using v3 (deprecated), migrate to v4

Step 2: Schema Change Detection

def detect_schema_changes(
    current_export: dict, expected_fields: set[str]
) -> dict:
    if not current_export.get("entries"):
        return {"status": "empty", "changes": []}

    actual_fields = set(current_export["entries"][0].keys())
    new_fields = actual_fields - expected_fields
    removed_fields = expected_fields - actual_fields

    return {
        "status": "changed" if new_fields or removed_fields else "compatible",
        "new_fields": list(new_fields),
        "removed_fields": list(removed_fields),
    }

# Track expected schema
EXPECTED_FIELDS = {
    "ownerName", "ownerEmail", "forecastAmount", "quotaAmount",
    "crmTotal", "crmClosed", "adjustmentAmount", "timePeriod"
}

Step 3: Database Schema Migration

-- Add new columns when Clari adds export fields
ALTER TABLE clari_forecasts ADD COLUMN IF NOT EXISTS new_field_name VARCHAR;

-- Backfill historical data
UPDATE clari_forecasts SET new_field_name = 'default' WHERE new_field_name IS NULL;

Rollback

Keep the previous client version alongside the new one until migration is verified:

# Pin client to specific behavior
client_v4 = ClariClient(ClariConfig(api_key=api_key, base_url="https://api.clari.com/v4"))

Error Handling

Condition	Response
Source removes or renames a field	Block promotion, update the compatibility contract, and revalidate transformations.
Backfill produces unexpected values	Stop the migration, preserve the prior certified table, and investigate with redacted samples.
New client or endpoint fails	Restore the pinned prior client and record the provider/job evidence.
Schema is empty or ambiguous	Do not infer compatibility; obtain an approved source contract or defer the change.

Output

Create a migration receipt with source/target versions, detected fields, compatibility decision, tested transform, backfill counts, validation evidence, rollback result, and named approver. Keep live credentials and raw forecast values out of the receipt.

Examples

Detect a new export field in staging, add it behind a nullable warehouse migration, compare redacted records with the prior client, and verify the analytics contract before promotion. If a mandatory field disappears, retain the previous client and certified dataset while the data owner decides the new semantic mapping.

Resources

• Clari Developer Portal
• Clari Community

Next Steps

For CI integration, see clari-ci-integration.