Convert - FHIR R4 to Manifest

POST /convert/v1/fhirr4tomanifest

This operation generates a tabular report of clinical concepts from a FHIR R4 bundle generated by another Orchestrate convert operation (e.g., CDA-to-FHIR, HL7-to-FHIR, or multiple “to FHIR” conversions followed by Combine Bundles).

With this tabular data, you can easily scan results, run queries, and understand the value of your clinical data:

• Summarizing the volume and variety of data elements found in a set of CDAs (e.g., number of problems, procedures, labs, etc.).
• Searching for whether the CDAs described contain any relevant information about certain dates of service, codings, or providers.
• Enabling analysis of larger data sets through concatenation of individual manifests.

Inputs and Outputs

The input is a FHIR R4 Bundle containing data for a single patient from one of the other Orchestrate Convert operations.

The output is a ZIP file, so specify accept: application/zip in your request header. See ZIP File Contents for more details about the contents of the output file.

Query Parameters

ZIP File Contents

The output ZIP file contains a number of Comma-Separated Value (CSV) files, corresponding to clinical concepts and other metadata.

Clinical data elements will be extracted from the FHIR bundle and placed into the appropriate CSV file, one per row. For example, if the FHIR bundle contained 5 distinct encounters, the encounters.csv file will contain 5 rows of data (plus a header row). Details for each file can be found in the following references:

• patients.csv
• allergies.csv
• conditions.csv
• encounters.csv
• familymemberhistory.csv
• immunizations.csv
• labs.csv
• medicationrequests.csv
• medicationdispenses.csv
• metadata.csv
• procedures.csv
• providers.csv
• questionnaireresponses.csv
• socialhistoryobservations.csv
• vitals.csv

CSV File Format

By default, the files in the ZIP archive use commas for their delimeter. You can optionally select certain other delimeters using the delimeter query parameter.

Patient ID and Identifier

The patient’s ID (reflected in the patient_id column of patients.csv and cross-linked in many other manifest files) always refers to the Patient.id field from the Patient resource in the FHIR bundle. This is effectively the primary key for the patient, and is often set in a previous “to FHIR” Convert API operation.

The patient’s primary business identifier (reflected in the identifier column of patients.csv) may be passed in as a query parameter or derived from the FHIR bundle. The order of precedence is:

• patientIdentifier query parameter.
• The first patient.identifier of type usual.
• The first patient.identifier of type official.
• The first patient.identifier of any other type.

Field Mapping

The Convert API analyzes each FHIR resource to determine where the data belongs. For example, an Observation resource in the FHIR bundle may be reported in labs.csv, vitals.csv, or socialhistoryobservations.csv depending on the underlying data.

ID and Identifier Fields

FHIR ID columns (patient_id, provider_id, etc.) are populated from the resource ID fields in the FHIR bundle. These serve as primary keys and allow each row in the output to be connected back to the original input bundle. These fields also help link data across the individual CSV files, e.g., renderingprovider_id in encounters links to provider_id in providers file.

The identifier columns are populated with identifier fields from FHIR resources (e.g. patient.identifier, encounter.identifier, etc.) and usually represent the source identifier for a given resource.

See Patient ID and Identifier for additional notes about how patient identifiers are derived.

Codings

Clinical data like conditions, procedures, etc. will have columns representing the primary code for the concept as it came from the source (the original CCDA/HL7/etc. message). For example: source_code, source_display, source_code_system.

These source values are mapped to corresponding code value(s) in standard code systems. If multiple mappings are available for the original source code, multiple columns will be populated. For example: snomedcode1, snomeddisplay1, snomedcode2, snomeddisplay2, icd10code1, icd10display1, etc.

Measurement Codes and Values

Many kinds of observations (e.g., labs, vital signs, or social history observations) use multiple fields to capture both what is being measured as well as the corresponding measurement value.

For example, in a social history there might be an observation for smoking history. This observation has two components.

The first is the type of measurement:

"code": {
	"coding": [
		{
			"system": "http://rosetta.careevolution.com/codes/Proprietary.1.3.6.1.4.1.22812.18.9.1/ObservationType",
			"code": "22154",
			"display": "Tobacco use",
			"userSelected": true
		},
		{
			"system": "http://loinc.org",
			"code": "72166-2",
			"display": "Tobac smoke stat",
			"userSelected": false
		}
	],
	"text": "Tobacco use"
}

Reflected in the manifest as follows:

The second is the value of the measurement:

"code": {
	"coding": [
		{
			"system": "urn:oid:2.16.840.1.113883.6.96",
			"code": "449868002",
			"display": "Current every day smoker",
			"userSelected": true
		},
		{
			"system": "http://snomed.info/sct",
			"code": "449868002",
			"display": "Smokes tobacco daily (finding)",
			"userSelected": false
		}
	],
	"text": "Current every day smoker"
}

Reflected in the manifest as follows:

Labs, Vitals, and Social History Values

The value for a lab, or vital sign, or social history observation can be a coded concept, a quantity, a boolean, a string, an integer, a datetime or a time period. The columns that are thus populated depends on how the data is shared in the source bundle:

Metadata and Provenance

The metadata.csv file is used to convey the associated Provenance resource information for data in the FHIR bundle. See the manifest specification for details.

Example

FHIR Bundles and the resulting CSV files are verbose, so the example below just shows a small sample to illustrate how the data is structured. For a more complete example, try out the API in the Developer Portal Sandbox.

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "35b77437-425d-419c-90b5-af4bc433ebe9",
        ... (patient fields)
      }
    },
    {
      "resource": {
        "resourceType": "Procedure",
        "id": "7.bc640751160d4dce960769e09f6a7de1",
        ... (encounter fields)
      }
    },
    ...
  ]
}

patients.csv:

patient_id,identifier,lastname,firstname,middlename,birthdate,gender,race_code,race_display,race_string,ethnicity_code,ethnicity_display,ethnicity_string,postalcode,primarycareprovider_npi,primarycareprovider_lastname,primarycareprovider_firstname,primarycareprovider_local_identifier,primarycareprovider_id,metadata_id
35b77437-425d-419c-90b5-af4bc433ebe9,IheTestPatient,Smith,Patient,,1956-08-13,female,,,,,,,90210,,,,,,4c13de1e-3c38-4209-bd9d-5f0ad088f7fc

procedures.csv:

resource_id,performed_date,encounter_date,status_code,status_display,status_code_system,source_code,source_display,source_code_system,source_code_text,hcpcscode1,hcpcsdisplay1,hcpcscode2,hcpcsdisplay2,snomedcode1,snomeddisplay1,snomedcode2,snomeddisplay2,icd10code1,icd10display1,icd10code2,icd10display2,loinccode1,loincdisplay1,loinccode2,loincdisplay2,patient_id,encounter_id,metadata_id
7.bc640751160d4dce960769e09f6a7de1,2009-08-10T23:00:00-04:00,,completed,,http://hl7.org/fhir/ValueSet/event-status,3227,"Bronchoscopic bronchial thermoplasty, ablation of airway smooth muscle",urn:oid:2.16.840.1.113883.6.12,,,,,,,,,,,,,,,,,,35b77437-425d-419c-90b5-af4bc433ebe9,,4c13de1e-3c38-4209-bd9d-5f0ad088f7fc

etc.