# ConceptMap
## Introduction 
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/900000000000207008|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. [#common-request-parameters](https://docs.b2ihealthcare.com/snow-owl/rest-apis/fhir/..#common-request-parameters "mention") 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/900000000000207008|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:
* `X-Effective-Date` -> the effective date to use if a version identifier is present in the resource without a corresponding `date` element
* `X-Author` -> sets the user identifier that the commit should be attributed to (defaults to the authenticated user)
* `X-Owner` -> sets 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-Profile` -> sets the human-readable name of the owner of the resource, for presentation purposes in external systems
* `X-Bundle-Id` -> specifies 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/900000000000207008|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:
* `_id` -> matches concept maps by logical identifier
* `name` -> matches concept maps by name (in Snow Owl this is set to the logical identifier)
* `title` -> matches concept maps by title (Snow Owl uses exact, phrase and prefix matching during its lexical search activities)
* `url` -> matches concept maps by their assigned `url` value
* `version` -> matches concept maps by their `version` value
* `status` -> matches concept maps by resource status (eg. 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/900000000000207008&code=103015000
[Query parametes (repeated for clarity)]
system: http://snomed.info/sct/900000000000207008
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"
}
]
}
]
}
```