> For the complete documentation index, see [llms.txt](https://docs.b2ihealthcare.com/snow-owl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2ihealthcare.com/snow-owl/rest-apis/fhir/conceptmaps.md). # ConceptMap ## Introduction ![](/files/wU5m8qF0gosyYubs3Uvp) The paid version of Snow Owl TS supports interactions and operations that target concept map resources. ## Interactions ### read (instance) GET requests that include the identifier of the concept map return the resource's current state: ```http GET /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2 [Response headers] Content-Type: application/fhir+json { "resourceType": "ConceptMap", "id": "69YWt6qc1ydgwARjh8XNw2", "meta": { "lastUpdated": "2023-11-30T16:36:31.653Z" }, "language": "en", "text": { "status": "empty", "div": "
" }, "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map", "name": "69YWt6qc1ydgwARjh8XNw2", "title": "Example Concept Map", "status": "draft", "description": "# Example Concept Map", "group": [ { "source": "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/2023-10-01", "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1", "element": [ { "code": "103015000", "display": "Thoracic nerve root pain", "target": [ { "code": "C00", "display": "Root concept", "relationship": "equivalent" } ] } ] } ] } ``` Just as with CodeSystem or ValueSet `read` interactions, query parameters `_format`, `_summary`, `_elements` and `_pretty` are applicable. [FHIR API](/snow-owl/rest-apis/fhir.md#common-request-parameters) expands on these settings. ### update (instance) PUT requests that include a resource identifier will update an existing resource (or create a new one if it didn't exist earlier): ```http PUT /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2 [Request headers] X-Author: user@host.domain Content-Type: application/fhir+json [Request body] { "resourceType": "ConceptMap", "id": "69YWt6qc1ydgwARjh8XNw2", "meta": { "lastUpdated": "2023-11-30T16:36:31.653Z" }, "language": "en", "text": { "status": "empty", "div": "
" }, "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map", "name": "69YWt6qc1ydgwARjh8XNw2", "title": "Example Concept Map", "status": "draft", "description": "# Example Concept Map", "group": [ { "source": "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/2023-10-01", "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1", "element": [ { "code": "103015000", "display": "Thoracic nerve root pain", "target": [ { "code": "C00", "display": "Root concept", "relationship": "equivalent" } ] }, // Added mapping { "code": "102506008", "display": "Well child (finding)", "target": [ { "code": "C00-1", "display": "Child concept", "relationship": "equivalent" } ] } ] } ] } ``` The response code is `201 Created` if the resource did not exist previously, and the URL is included in the `Location` response header. Existing concept maps (like in the example above) are updated and a `200 OK` response is returned instead. If an error occurs during the update, a `400 Bad Request` response with an `OperationOutcome` resource as the response body is emitted instead. The following non-standard request headers can be used to control certain aspects of the commit process:
NameDescription
X-Effective-DateThe effective date to use if a version identifier is present in the resource without a corresponding date element
X-AuthorSets the user identifier that the commit should be attributed to (defaults to the authenticated user)
X-OwnerSets the owner of the resource, for access control purposes in external systems (defaults to the author or the authenticated user if the former is not set)
X-Owner-ProfileSets the human-readable name of the owner of the resource, for presentation purposes in external systems
X-Bundle-IdSpecifies the parent bundle's resource identifier (defaults to the root bundle if not set)
{% hint style="warning" %} Concept maps are currently limited to a single source and target code system and version (group) they can use to map concepts. {% endhint %} ### delete (instance) A DELETE request removes an existing concept map: ```http DELETE /snowowl/fhir/ConceptMap/69YWt6qc1ydgwARjh8XNw2 [Request headers] X-Author: user@host.domain [Response] 204 No Content ``` Successful removal of a resource results in a `204 No Content` response. Concept maps that have already been versioned can not be removed without adding the `force=true` query parameter to signal a forced deletion (this option is only available to administrators however). ### create (type) In `create` interactions a POST request is sent to the path corresponding to the resource type. Any identifier included in the request body is ignored and a new, random one is generated from scratch. ```http POST /snowowl/fhir/ConceptMap [Request headers] X-Effective-Date: 2023-11-29 X-Author: user@host.domain X-Owner: owner@host.domain X-Owner-Profile-Name: Resource Owner X-Bundle-Id: parent-bundle-id Content-Type: application/fhir+json [Request body] { "resourceType": "ConceptMap", // "id": "..." is not used by the server "text": { "status": "empty", "div": "
" }, "url": "https://b2ihealthcare.com/conceptmaps/example-concept-map-2", "title": "Example Concept Map", "status": "draft", "group": [ { "source": "http://snomed.info/sct|http://snomed.info/sct/900000000000207008/version/2023-10-01", "target": "https://b2ihealthcare.com/codesystems/example-lcs-1|v1", "element": [ { "code": "103015000", "display": "Thoracic nerve root pain (finding)", "target": [ { "code": "C00", "display": "Root concept", "relationship": "equivalent" } ] } ] } ] } [Response] 201 Created [Response headers] Location: http:///snowowl/fhir/ConceptMap/cndkDE31kfeXw8 ``` The response code is `201 Created` if the interaction is successful. The request URL that can be used in eg. follow-up `read` interactions is included in the response header named `Location`. ### search (type) GET requests with a request path that points to the resource type returns all concept maps that satisfy the specified search criteria, in the form of query parameters. The following example uses the `count` summary mode to determine the number of active concept maps in the system, without returning any of the matches: ```http GET /snowowl/fhir/ConceptMap?status=active&_summary=count [Response headers] Content-Type: application/fhir+json { "resourceType": "Bundle", "id": "conceptmaps", "meta": { "lastUpdated": "2023-11-30T16:52:08.443803Z" }, "type": "searchset", "total": 22 } ``` {% hint style="danger" %} Just as with code system and value set resources, POST requests for `search` interactions are unsupported in Snow Owl and will result in a `405 Method Not Allowed` response. {% endhint %} The following search parameters are supported:
NameDescription
_id Matches concept maps by logical identifier
name Matches concept maps by name (in Snow Owl this is set to the logical identifier)
titleMatches concept maps by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)
urlMatches concept maps by their assigned url value
version Matches concept maps by their version value
status Matches concept maps by resource status (e.g. draft, active, etc.)
## Operations ### $translate Snow Owl TS uses the path parameter (and optionally, `conceptMapVersion`) to identify the concept map used for the operation. Supplying a concept map resource "inline" as input parameter `conceptMap` is not supported. Parameters `sourceScope` and `targetScope` are also ignored. The presence of a `source*` parameter (code, coding or codeable concept) implies that the translation needs to find "forward" (target) matches, while `target*` codes, codings or codeable concepts will run the translation in reverse. An example translation request can be seen below: ```http GET /snowowl/fhir/ConceptMap/cndkDE31kfeXw8/$translate?system=http://snomed.info/sct&code=103015000 [Query parametes (repeated for clarity)] system: http://snomed.info/sct code: 103015000 [Response headers] Content-Type: application/fhir+json { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "message", "valueString": "1 member(s) from concept map: cndkDE31kfeXw8" }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "codesystems/example-lcs-1", "code": "C00", "display": "Root concept" } }, { "name": "originMap", "valueUri": "cndkDE31kfeXw8" } ] } ] } ```