ConceptMap Profile
This ConceptMap profile is part of the set of resource profiles supported by the API Server used with the athenaPractice 12.3 and athenaFlow 9.12 products. It further describes read and search capabilities of these products. Note: The create and update operations are NOT supported for this resource.
Overview
A statement of relationships from one set of concepts to one or more other concepts - either code systems or data elements, or classes in class models.
Scope and Usage
This profile is used to define the content that will be returned by the API Server in response to requests to access ConceptMap resources. All elements listed in the differential profile view are Supported, which means that the API Server is capable of supplying these fields from the product database when they have been populated via the product or its APIs.
Source
The ConceptMap resource provides information about mappings used by the API Server to translate between athenaPractice and athenaFlow specific codes to standard codes used by HL7 FHIR Resources. The content is derived from an external file created during system installation.
Supported Operations
The operations supported by this resource are listed below.
Read Operation
Read operations are executed as specified in the HL7 FHIR RESTful API implementation definition. To read a ConceptMap, an application shall perform an HTTP GET, specifying the identifier of the resources being retrieved.
GET [base]/fhir/ConceptMap/[id]{?_format=[json|xml]&_summary=[true|data]}
Read Operation Parameters
| Parameter | Description |
|---|---|
| [base] | Specifies the base URL of the FHIR Server, e.g., https://cpsapisandbox.virenceaz.com:9443/demoAPIServer |
| [id] | Specifies the identifier of the ConceptMap resource to retrieve |
| [_format] | Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request. |
| [_summary] | Filters the output to include only summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides slightly improved API response times. |
Read Operation HTTP Response Codes
| Response Code | Description |
|---|---|
| 200 OK | The requested resource was found and is contained within the body of the HTTP response. |
| 401 Unauthorized | Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required. |
| 404 Not Found | The requested resource does not exist. The body of the HTTP response will contain an OperationOutcome resource that indicates that the resource could not be found. |
| 500 Server Error | The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error. |
Search Operation
ConceptMap resources can be enumerated by retrieving the fhir/List resource with an id of ConceptMap
GET [base]/fhir/List/ConceptMap?{_format=[json|xml]&_summary=[true|text|data]}
Search Operation Parameters
| Parameter | Description |
|---|---|
| [base] | Specifies the base URL of the FHIR Server, e.g., https://cpsapisandbox.virenceaz.com:9443/demoAPIServer |
| [_count] | Specifies the maximum number of search results to return in a single query. Note: The count of results does not limit the number of additional resources returned via the _include parameter. No more than max-results ConceptMap resources which match the search criteria will be returned. The API Server has default and maximum limits for the value that can be specified for this parameter. These limits may vary depending upon the client application vendors participation level in the AthenaHealth Partner program. Note: The API Server support the HL7 FHIR Paging capability. |
| [_format] | Specifies the format of the output and may be xml or json. When present, the _format value overrides the value of the Accept header in the request. |
| [_summary] | Filters the output to include only narrative elements (_summary=text), summary elements (_summary=true) or to omit the generated narrative (_summary=data). Note: If the generated html narrative for the resource is not going to be used by the call, using _summary=data provides improved API response times, especially when returning larger result sets. |
Search Operation HTTP Response Codes
| Response Code | Description |
|---|---|
| 200 OK | The query was performed and any results found are contained within the body of the HTTP response. Note: The search API will return 200 OK when the query itself is successful, regardless of whether or not any matching results were found. |
| 401 Unauthorized | Authorization is required for this request, and either the Authorization header is missing or the supplied user credentials in the Authorization header are not valid or have expired. The body of the HTTP response will contain an OperationOutcome resource that indicates that Authorization is required. |
| 500 Server Error | The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error. |
Other Operations
This Implementation guide defines 1 operation:
| $translate | Concept Translation |
For more information about operations, including how they are invoked, see Operations .
Concept Translation
Translate a code from one value set to another, based on the existing value set and concept maps resources, and/or other additional knowledge available to the server.
One (and only one) of the in parameters (code, coding, codeableConcept) must be provided, to identify the code that is to be translated.
The operation returns a set of parameters including a 'result' for whether there is an acceptable match, and a list of possible matches. Note that the list of matches may include notes of codes for which mapping is specifically excluded, so implementers have to check the match.equivalence for each match
GET [base]/$translate?{operation-parameters}GET [base]/$translate?{operation-parameters}| In Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| code | 0..1 | code | The code that is to be translated. If a code is provided, a system must be provided | ||
| system | 1..1 | uri | The system of the code that is to be translated. | ||
| targetcode | 0..1 | code | The target code that is to be translated to. If a code is provided, a targetsystem must be provided. This allows "reverse" lookup of translations. | ||
| targetsystem | 0..1 | uri | The target system for the code that is to be translated from/to. | ||
| dependency | 0..* | Another element that may help produce the correct mapping | |||
| dependency.element | 0..1 | uri | The element for this dependency | ||
| dependency.concept | 0..1 | CodeableConcept | The value for this dependency | ||
| Out Parameters: | |||||
| Name | Cardinality | Type | Binding | Profile | Documentation |
| result | 1..1 | boolean | True if the concept could be translated successfully. The value can only be true if at least one returned match has an equivalence which is not unmatched or disjoint | ||
| message | 0..1 | string | Error details, for display to a human. If this is provided when result = true, the message carries hints and warnings (e.g. a note that the matches could be improved by providing additional detail) | ||
| match | 0..* | A concept in the target value set with an equivalence. Note that there may be multiple matches of equal or differing equivalence, and the matches may include equivalence values that mean that there is no match | |||
| match.equivalence | 0..1 | code | A code indicating the equivalence of the translation, using values from [ConceptMapEquivalence]{concept-map-equivalence.html} | ||
| match.concept | 0..1 | Coding | The translation outcome. Note that this would never have userSelected = true, since the process of translations implies that the user is not selecting the code (and only the client could know differently) | ||
| dependency | 0..* | Dependencies for this target (replicates input) | |||
| dependency.element | 0..1 | uri | The element for this dependency | ||
| dependency.concept | 0..1 | Coding | The value for this dependency | ||
Profile Content
The official URL for this profile is:
http://hl7.org/fhir/StructureDefinition/conceptmap-profile
A map from one set of concepts to one or more other concepts
| Name | Flags | Card. | Type | Description & Constraints | |
|---|---|---|---|---|---|
  ConceptMap | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts | ||
 meta | ∑ | 0..1 | Meta | Metadata about the resource | |
 implicitRules | ?! ∑ | 0..1 | uri | A set of rules under which this content was created | |
| language | 0..1 | code | Language of the resource content Binding: IETF BCP-47  (required ) | ||
| text | I | 0..1 | Narrative | Text summary of the resource, for human interpretation | |
| contained | 0..* | Resource | Contained, inline Resources | ||
 extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| url | ∑ | 0..1 | uri | Globally unique logical id for concept map | |
 identifier | ∑ | 0..1 | Identifier | Additional identifier for the concept map | |
| version | ∑ | 0..1 | string | Logical id for this version of the concept map | |
| name | ∑ | 0..1 | string | Informal name for this concept map | |
| status | ?! S∑ | 1..1 | code | draft | active | retired Binding: ConformanceResourceStatus (required ) | |
| experimental | ∑ | 0..1 | boolean | If for testing purposes, not real usage | |
| publisher | ∑ | 0..1 | string | Name of the publisher (organization or individual) | |
| contact | ∑ | 0..* | BackboneElement | Contact details of the publisher | |
 extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| name | ∑ | 0..1 | string | Name of a individual to contact | |
 telecom | ∑ | 0..* | ContactPoint | Contact details for individual or publisher | |
| date | ∑ | 0..1 | dateTime | Date for given status | |
| description | ∑ | 0..1 | string | Human language description of the concept map | |
| useContext | ∑ | 0..* | CodeableConcept | Content intends to support these contexts Binding: Context of Use ValueSet (extensible ) | |
| requirements | 0..1 | string | Why needed | ||
| copyright | 0..1 | string | Use and/or publishing restrictions | ||
 source[x] | ∑ | 1..1 | uri , Reference (ValueSet ), Reference (StructureDefinition ) | Identifies the source of the concepts which are being mapped | |
| target[x] | ∑ | 1..1 | uri , Reference (ValueSet ), Reference (StructureDefinition ) | Provides context to the mappings | |
| element | 0..* | BackboneElement | Mappings for a concept from the source set | ||
 extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| codeSystem | 0..1 | uri | Code System (if value set crosses code systems) | ||
| code | 0..1 | code | Identifies element being mapped | ||
| target | I | 0..* | BackboneElement | Concept in target system for element cmd-1: If the map is narrower or inexact, there SHALL be some comments | |
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| codeSystem | 0..1 | uri | System of the target (if necessary) | ||
| code | 0..1 | code | Code that identifies the target element | ||
| equivalence | ?! S | 1..1 | code | equivalent | equal | wider | subsumes | narrower | specializes | inexact | unmatched | disjoint Binding: ConceptMapEquivalence (required ) | |
| comments | I | 0..1 | string | Description of status/issues in mapping | |
| dependsOn | 0..* | BackboneElement | Other elements required for this mapping (from context) | ||
| extension | 0..* | Extension | Additional Content defined by implementations | ||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | |
| element | 1..1 | uri | Reference to element/field/ValueSet mapping depends on | ||
| codeSystem | 1..1 | uri | Code System (if necessary) | ||
| code | 1..1 | string | Value of the referenced element | ||
 product | 0..* | Other concepts that this mapping also produces | |||