Interface Guide

Code Mapping

Various FHIR resources and data types use codes with a fixed set of predefined values. The corresponding CareEvolution concept typically uses a term with an arbitrary set of possible values.

For example: the FHIR HumanName has a use property with possible values usual, official, temp, nickname, anonymous, old, maiden). The corresponding DemographicName CareEvolution concept is a property referencing a term (typically in the NameType family).

To convert from CareEvolution terms to FHIR codes, the system uses term mappings: each FHIR code has a unique corresponding term in the FhirCodes or FhirCodesAlternate1 or FhirCodesAlternate2 namespaces. Every CareEvolution term mapped to one of these terms is converted to the corresponding code.

The FHIR server automatically creates all these code terms the first time any FHIR Interface is called. Also, the Automated Term Mapping Service maps terms in the relevant families to FHIR code terms.

Multiple Mappings

Certain CareEvolution term families–for example OrderStatus–are mapped to different FHIR code sets using the alternate namespaces because the underlying CareEvolution concept is mapped to different FHIR resources. For example, Order is mapped to FHIR DiagnosticOrder, FHIR MedicationOrder and FHIR MedicationStatement.

Mapping Errors

If a term does not have a mapping the FHIR request fails with an error 500 like

Search failed: Unable to map the term BeaconTestTermNamespace.OrderStatus.Order4Status to a FHIR DiagnosticOrderStatus code: there is no valid term mapping and the term code does not correspond to any of the allowed values

Codeable Concept Extensions

Converting arbitrary terms to fixed sets of codes potentially loses information. To mitigate this the system renders the original term–converted to a FHIR CodeableConcept–as a http://careevolution.com/fhirextensions#term extension of the corresponding FHIR code. So for example a gender term F in the term namespace Demo is mapped to:

    "gender": "female",
    "_gender": {
        "extension": [
                "url": "http://careevolution.com/fhirextensions#term",
                "valueCodeableConcept": {
                    "coding": [
                            "system": "http://fhir.carevolution.com/codes/Demo/Gender",
                            "code": "F",
                            "userSelected": true

Pre-Defined Mappings

Some term families have predefined values in the CareEvolution namespace. The system convert some of these terms (and terms mapped to them) directly to a corresponding FHIR code:

CareEvolution Term Code CareEvolution Term Family FHIR Code FHIR Element
LegalName NameType official Human Name Use
HomeAddress AddressType home Address Use
OfficeAddress AddressType work Address Use
Email ContactInfoType email Contact Point System
Fax ContactInfoType fax Contact Point System
Home Phone ContactInfoType phone Contact Point System
Office Phone ContactInfoType phone Contact Point System

Finally, if contact info use code terms cannot be mapped to FHIR contact point use, the system looks at the contact info type:

  • If it is HomePhone then the contact point use is set to home.
  • If it is OfficePhone then the contact point use is set to work.