9.x

ConceptMap

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:

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": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></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"
            }
          ]
        }
      ]
    }
  ]
}

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):

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": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></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)

Concept maps are currently limited to a single source and target code system and version (group) they can use to map concepts.

delete (instance)

A DELETE request removes an existing concept map:

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.

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": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></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://<host>/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:

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
}

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.

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:

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"
        }
      ]
    }
  ]
}

Last updated