Understanding drift reports

When drift detection is enabled, the bulk job writes an aggregate report named jobLevelDriftResult.json to your output location. The report tells you how much of your source data the profile actually captured, and what it missed: so you know where to improve your mappings.

The report's structure depends on the source format: C-CDA reports are organized around document sections and entries (identified by OIDs), while CSV reports are organized around tables, columns, and rows. Both share the same coverage-rate concept (a fraction from 0.0 to 1.0, where higher means more of your source was captured).

C-CDA drift report

{
  "jobId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "profileId": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "profileVersion": 3,
  "timestamp": "2026-07-14T18:30:00Z",
  "filesProcessed": 500,
  "totalFilesFailed": 2,
  "avgSectionCoverageRate": 0.92,
  "avgEntryCoverageRate": 0.85,
  "avgOverallCoverageRate": 0.88,
  "avgResourceAccuracy": 0.97,
  "totalUnknownSections": 14,
  "totalUnknownEntries": 63,
  "documentOids": { 
    "2.16.840.1.113883.10.20.22.1.2": 480 
    },
  "unknownSectionOidCount": 2,
  "unknownSections": { 
    "2.16.840.1.113883.10.20.22.2.14": 12 
    },
  "unknownEntryOidCount": 5,
  "unknownEntries": { 
    "2.16.840.1.113883.10.20.22.4.13": 40 
    },
  "missingResources": { 
    "2.16.840.1.113883.10.20.22.2.6.1": { 
      "AllergyIntolerance": 8 
      } 
    },
  "perFileDrift": { 
    "patient-001.xml": 0.95, 
    "patient-002.xml": 0.61 
    }
}

How to read it

Start with the coverage rates. These are averages across all processed files, expressed as a fraction from 0.0 to 1.0 (multiply by 100 for a percentage). Higher is better: a higher rate means more of your source data made it into the FHIR output.

Then find what was missed. These fields point you to the specific mappings to add:

Prioritize by frequency. The counts in unknownSections, unknownEntries, and missingResources tell you which gaps affect the most records. An OID that appears 40 times is a bigger win to map than one that appears twice.

Drill into specific files. perFileDrift maps each source file to its overall coverage rate. Sort by the lowest values to find the files the profile handled worst: for example, patient-002.xml at 0.61 is worth inspecting. For a full per-file breakdown (which specific OIDs each file missed), see the individual reports under the driftDetectionPerFileResults/ folder.

Improving coverage

CSV drift report

For CSV jobs, the report is organized around tables (each CSV file is a table), columns, and rows: not sections and OIDs.

{
  "jobId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "profileId": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "profileVersion": 3,
  "summary": {
    "totalTablesInProfile": 4,
    "totalTablesInInput": 5,
    "tablesProcessed": 4,
    "tablesUnmapped": 1,
    "totalColumnsInInput": 42,
    "columnsMapped": 35,
    "columnsUnmapped": 7,
    "totalRowsScanned": 120000,
    "rowsConvertedSuccessfully": 119850,
    "rowsFailedCustomerError": 140,
    "rowsFailedServerError": 10,
    "totalResourcesGenerated": 245000,
    "tablesCoverageRate": 0.80,
    "columnsCoverageRate": 0.83,
    "overallCoverageRate": 0.83
  },
  "unmappedTables": [
    {
      "tableName": "billing",
      "fileName": "billing.csv",
      "reason": "No matching table declared in the mapping profile",
      "columns": ["invoice_id", "amount", "payer"]
    }
  ],
  "unmappedColumns": [
    {
      "tableName": "patients",
      "columns": ["preferred_language", "ethnicity_detail"],
      "reason": "Present in CSV but not referenced by any field mapping"
    }
  ]
}

How to read it

Start with the summary. The coverage rates are fractions from 0.0 to 1.0 (higher is better):

Then check the counts to understand conversion outcomes:

Then find what was missed:

Sync CSV drift report

How to read it describes the bulk (asynchronous) format that a transformation job writes to Amazon S3. When you run drift detection synchronously, the API response includes the comma-separated value (CSV) drift report inline. To enable this, set enableDriftDetection to true on a TransformData request. Because a sync request processes a single input rather than a whole dataset, its report has a simpler structure.

{
  "sourceFormat": "CSV",
  "summary": {
    "totalTablesInProfile": 1,
    "totalTablesInInput": 1,
    "tablesProcessed": 1,
    "tablesUnmapped": 0,
    "totalColumnsInInput": 10,
    "columnsMapped": 7,
    "columnsUnmapped": 3,
    "totalRowsProcessed": 2,
    "totalResourcesGenerated": 2,
    "tablesCoverageRate": 1.0,
    "columnsCoverageRate": 0.7,
    "perTableRowCounts": { "patients": 2 }
  },
  "unmappedTables": [],
  "unmappedColumns": [
    {
      "tableName": "patients",
      "columns": ["ETHNICITY", "LANGUAGE", "NICKNAME"],
      "reason": "Columns present in CSV but not referenced in any field mapping"
    }
  ],
  "warnings": []
}

The summary, unmappedTables, and unmappedColumns fields carry the same meaning as in the bulk report. The sync report differs from the bulk CSV report in the following ways:

Improving coverage (both formats)