Programming Guide

This guide introduces some basic concepts and workflows that will be important as you begin using the API.

Single Patient

All Convert API operations assume the input data represents a single individual.

Patient Identifiers

The “to FHIR” operations allow you to specify optional patient identifiers. You may specify either or both types of identifiers.

patientID

The optional patientId query parameter provides a unique resource ID for the patient. In the output bundle, this will be used for Patient.id in the resulting resource.

For example, if the parameters are: /convert/v1/cdatofhirr4?patientID=3aa0bfc6-89fa-400c-a0d1-81a303b85591

The output would include:

"resource": {
                "resourceType": "Patient",
                "id": "3aa0bfc6-89fa-400c-a0d1-81a303b85591",
                ...
            }

patientIdentifier and patientIdentifierSystem

The optional patientIdentifier and patientIdentifierSystem query parameters specify a business identifier, such as an MRN or MPI identifier. Both parameters must be specified together.

In the output bundle, these parameters will be used for the first identifier field in the resulting Patient resource. Other identifiers from the original payload are also included as subsequent entries in the identifier list. The patientIdentifierSystem specifies the identifier’s system URI.

For example, if the parameters are: convert/v1/cdatofhirr4?patientidentifier=XYZ123456&patientIdentifierSystem=urn:oid:1...

The output would include:

"resource": {
                "resourceType": "Patient",
                "identifier": [
                  {
                      "use": "usual",
                      "type": {
                          "coding": [
                              {
                                  "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                  "code": "MR"
                              }
                          ]
                      },
                      "system": "urn:oid:1.2.840.000.1.13.246.2.7.2.688879.7700",
                      "value": "XYZ123456"
                  },
                ...
            }

Output FHIR R4 Bundles

All of the “to FHIR” operations (including Combine FHIR Bundles) return a FHIR R4 Bundle containing the input data converted into FHIR resources. The bundle will be of type collection.

The following special considerations apply to the FHIR bundles from these operations.

OperationOutcomes

These bundles include an OperationOutcome resource. An OperationOutcome is a collection of issue elements detailing what was parsed from the input, as well as any problems with the conversion. See Operation Outcomes for details.

Resource IDs

The convert API will generate unique logical ids for all resources that were converted from the input. Resources within a bundle may refer to other resources within the same bundle (e.g., a Condition referencing a Patient/{ID}). The convert API is stateless, and different requests are considered independent of one another. Submitting the same input information to the API multiple times will result in different logical ID elements being generated for the equivalent input concept. Business identifiers are retained if sent in the input data.

Codes/Codings/CodeableConcepts

As part of the conversion process, the API will use the Terminology service to standardize input codes. This will result in the following enhancements to output data.

Codes

FHIR code elements represent enumerations with a set of possible values (e.g., Patient.gender, Condition.status). In these situations, the code in the FHIR bundle will be the equivalent input field translated into an equivalent value in the enumeration. An extension element will be added (e.g., Patient._gender, Condition._status) that contains the input code as sent represented as a Coding.

CodeableConcepts

In addition to the data directly present in the input, CodeableConcepts may have additional codings representing the standardized reference codes from the Terminology service. These added codings can be identified by the userSelected: false property.

This can include the following:

• Source data coded with a reference CodeSystem OID will also result in a Coding with the appropriate system URI with a reference code and display. (e.g., a source ICD10CM code sent as “E119” with no display and system=”2.16.840.1.113883.6.90” may result in an additional Coding with code=E11.9 display=”Type 2 diabetes mellitus without complications” system=”http://hl7.org/fhir/sid/icd-10-cm” - a standardized coding conformant with the FHIR specification).
• Additional reference codings may be included if they represent an equivalent concept (e.g., an input NDC code may result in several additional reference codings for equivalent NDC, RxNorm and CVX codes).
• Uncoded source data may result in a reference Coding if the textual description is sufficient to derive a representative reference Coding.