mappings

❗	Warning: This page is going to be retired and this documentation will be maintained at - https://github.com/OpenConceptLab/ocl-docs/blob/main/docs/source/oclapi/user/mappings.md

Overview

The API exposes a representation of mappings to represent relationships between 2 concepts. The type of relationship is defined by the map_type attribute. Relationships are unidirectional, originating from the from_concept to the to_concept, even if the inverse mapping is equivalent (e.g. "Same As" relationship). Note that the inverse mappings can be retrieved from the "to_concept" by setting the "includeInverseMappings" to true. mappings are also used to store hierarchical relationships (such as parent/child), and OpenMRS-specific relationships such as Question/Answer and Concept Sets.

The from_concept must be a concept within an OCL source, while the to_concept may refer to a concept stored in OCL or to an external code. Regardless, the definition for the source must be in OCL. If the to_concept refers to a concept in OCL, it is referenced using the to_concept_url field. If the to_concept refers to an external concept, it is referenced using the to_source_url, to_concept_code, and (optionally) to_concept_name fields. In other words, there are two types of to_concepts:

Internal - The to_concept is stored in OCL
External - The to_source is defined in OCL (as an "external" source), but the to_concept is not.

Following are the fields that are required for Internal and External mappings:

Field	Type	Notes
`from_concept_url`	1, 2	Required for both types of mappings.
`to_concept_url`	1	Required for internal mappings.
`to_source_url`	2	Required for external mappings. URL in OCL of the `to_concept` source (e.g. /orgs/Regenstrief/sources/LOINC/).
`to_concept_code`	2	Required for external mappings. Identifier for the external `to_concept`.
`to_concept_name`	(2)	Optional for external mappings. The human-readable name for the external `to_concept`.

Editing of mappings is supported, but edits that substantively change the meaning of a mapping is discouraged. For example, instead of changing the "from" or "to" concept of an existing mapping, retire the mapping and create a new one.

mappings are owned by sources, not by their from_concept. Modifications to mappings do not directly effect the concepts to which they are linked. Like concepts, mappings will be saved as part of source versions. Mappings may point to concepts from any source, meaning that neither the "from" or "to" concept needs to be in the source that owns the mapping. This allows sources to be used as containers of a set of mappings.

Versioning of mappings

All changes to mappings are tracked and can be accessed via a mapping's history

Get a single mapping

Get a single mapping

GET /orgs/:org/sources/:source/[:sourceVersion/]mappings/:mapping/
GET /users/:user/sources/:source/[:sourceVersion/]mappings/:mapping/
GET /user/sources/:source/[:sourceVersion/]mappings/:mapping/

Example

GET /orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/

Response

Status: 200 OK

{
    "type": "Mapping",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "external_id": "a9d93ffjjen9dnfekd9",
    "retired": "false",

    "map_type": "Same As",

    "from_source_owner": "Regenstrief",
    "from_source_owner_type": "Organization",
    "from_source_name": "loinc2",
    "from_concept_code": "32700-7",
    "from_concept_name": "Malarial Smear",
    "from_source_url": "/orgs/Regenstrief/sources/loinc2/",
    "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",

    "to_source_owner": "WHO",
    "to_source_owner_type": "Organization",
    "to_source_name": "ICPC-2",
    "to_concept_code": "A73",
    "to_concept_name": "Malaria",
    "to_source_url": "/orgs/WHO/sources/ICPC-2/",

    "source": "loinc2",
    "owner": "Regenstrief",
    "owner_type": "Organization",
    "owner_url": "/orgs/Regenstrief/",

    "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",

    "extras": {},

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-02-18T09:10:16Z",
    "updated_by": "johndoe"
}

List mappings for a concept within a single source

List mappings or inverse mappings for a concept that are contained in the same source as the concept

GET /user/sources/:source/[:sourceVersion/]concepts/:concept/mappings/
GET /users/:user/sources/:source/[:sourceVersion/]concepts/:concept/mappings/
GET /orgs/:org/sources/:source/[:sourceVersion/]concepts/:concept/mappings/

Notes
- Use the /mappings/ endpoint to view mappings across public sources or use /orgs/:org/sources/:source/mappings/ for private sources.
Parameters
- verbose (optional) string - default is false; set to true to return full mapping details instead of the summary
- includeRetired (optional) string - default - "false"; set to "true" to return retired mappings
- includeInverseMappings (optional) string - default is "false"; set to "true" to return inverse mappings

Response

Status: 200 OK

[
    {
        "map_type": "Same As",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
    },
    {
        "map_type": "Narrower Than",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_code": "A73",
        "to_concept_name": "Malaria",
        "to_source_code": "ICPC-2",
        "url": "/orgs/Regenstrief/sources/loinc2/def3fe-c2cc-11de-8d13-asdf9393930/",
    },
    {
        "map_type": "Same As",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "to_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "from_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffdea/",
    }
]

List all mappings within a specific source

List all mappings within an organization or user's source

GET /orgs/:org/sources/:source/[:sourceVersion/]mappings/
GET /users/:user/sources/:source/[:sourceVersion/]mappings/
GET /user/sources/:source/[:sourceVersion/]mappings/

Notes
- Retired mappings are excluded by default
Parameters
- verbose (optional) string - default is false; set to true to return full mapping details instead of the summary
- q (optional) string - ID of the "from" or "to" concept
- includeRetired (optional) string - default is "false"; set to "true" to return retired mappings
- mapType (optional) string - mapType descriptor, such as "Same As", "Parent", "Child", etc.
- Sources
  - conceptSource (optional) string - comma-separated list of sources for the "from" or "to" source; can be the "code" for the source (e.g. "SNOMED-CT" or "ICPC-2") or the fully specified URL
  - fromConceptSource (optional) string - comma-separated list of source IDs for the "from" source (e.g. "SNOMED-CT" or "ICPC-2")
  - toConceptSource (optional) string - comma-separated list of source IDs for the "to" source (e.g. "SNOMED-CT" or "ICPC-2")
- Concepts
  - concept (optional) string - comma-separated list of concept IDs for the "from" or "to" concept (e.g. A57)
  - fromConcept (optional) string - comma-separated list of concept IDs for the "from" concept (e.g. A57)
  - toConcept (optional) string - comma-separated list of concept IDs for the "to" concept (e.g. A57)

Example

GET /orgs/Regenstrief/sources/loinc2/mappings/

Response

Status: 200 OK

[
    {
        "map_type": "Same As",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
    }
]

List mappings across public sources

List mappings across all public sources

GET /mappings/

Parameters
- q (optional) string - ID of the "from" or "to" concept
- includeRetired (optional) string - default is "false"; set to "true" to return retired mappings
- mapType (optional) string - map type descriptor, such as "Same As", "Parent", "Child", etc.
- Sources
  - conceptSource (optional) string - comma-separated list of source IDs for the "from" or "to" source (e.g. "SNOMED-CT" or "ICPC-2")
  - fromConceptSource (optional) string - comma-separated list of source IDs for the "from" source (e.g. "SNOMED-CT" or "ICPC-2")
  - toConceptSource (optional) string - comma-separated list of source IDs for the "to" source (e.g. "SNOMED-CT" or "ICPC-2")
- Concepts
  - concept (optional) string - comma-separated list of concept IDs for the "from" or "to" concept (e.g. A57)
  - fromConcept (optional) string - comma-separated list of concept IDs for the "from" concept (e.g. A57)
  - toConcept (optional) string - comma-separated list of concept IDs for the "to" concept (e.g. A57)

Response

Status: 200 OK

[
    {
        "map_type": "Same As",
        "retired": "false",
        "source": "loinc2",
        "owner": "Regenstrief",
        "owner_type": "Organization",
        "from_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
    }
]

Create a new mapping

Create a new mapping

POST /user/sources/:source/mappings/
POST /users/:user/sources/:source/mappings/
POST /orgs/:org/sources/:source/mappings/

Input
- Internal Mapping: from_concept and to_concept are stored in OCL
  - id (optional) string - ID is auto-generated if not provided
  - map_type (required) string - map type
  - external_id (optional) string - external unique identifier for import/export
  - from_concept_url (required) string - relative URL of the "from" concept
  - to_concept_url (required) string - relative URL for the "to" concept
- External Mapping: from_concept is stored in OCL; to_source is defined in OCL, but to_concept is not
  - id (optional) string - ID is auto-generated if not provided
  - map_type (required) string - map type
  - external_id (optional) string - external unique identifier for import/export
  - from_concept_url (required) string - relative URL of the "from" concept
  - to_source_url (required) string - relative URL of the "to" source (must be stored in OCL)
  - to_concept_code (required) string - code for the external to_concept
  - to_concept_name (optional) string - name of the external to_concept

Examples

Internal mapping: to_concept is stored in OCL:

{
    "map_type": "Same As",
    "from_concept_url": "/orgs/Columbia/sources/CIEL/concepts/161426/",
    "to_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/"
}

External mapping: to_concept is not stored in OCL (but to_source_url is defined in OCL):

{
    "map_type": "Narrower Than",
    "from_concept_url": "/orgs/Columbia/sources/CIEL/concepts/116125/",
    "to_source_url": "/orgs/WHO/sources/ICPC-2/",
    "to_concept_code": "A73",
    "to_concept_name": "Malaria"
}

Response

Status: 201 Created
Location: http://api.openconceptlab.com/orgs/Columbia/sources/CIEL/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/
Returns the JSON representation of the new mapping in the same format as Get a single mapping

Edit a mapping

Edit a mapping

PUT /user/sources/:source/mappings/:mapping/
PUT /users/:user/sources/:source/mappings/:mapping/
PUT /orgs/:org/sources/:source/mappings/:mapping/

Input
- Internal Mapping: to_concept is stored in OCL
  - map_type (optional) string - map type
  - external_id (optional) string - external unique identifier for import/export
  - from_concept_url (optional) string - relative URL of the "from" concept
  - to_concept_url (optional) string - relative URL of the "to" concept
- External Mapping: to_concept is not stored in OCL
  - map_type (optional) string - map type
  - external_id (optional) string - external unique identifier for import/export
  - from_concept_url (optional) string - relative URL of the "from" concept
  - to_source_url (optional) string - relative URL of the "to" source - note that the source must be defined in OCL
  - to_concept_code (optional) string - code for the external to_concept
  - to_concept_name (optional) string - name of the external to_concept

Examples

Internal Mapping: to_concept is stored in OCL

{
    "map_type": "Same As",
    "to_concept_url": "/orgs/Regenstrief/sources/loinc2/concepts/32700-7/"
}

External Mapping: to_concept is not stored in OCL

{
    "map_type": "Narrower Than",
    "to_source_code": "ICPC-2",
    "to_concept_code": "A73",
    "to_concept_name": "Malaria",
}

Response

Status: 200 OK
Returns the updated JSON representation of the mapping in the same format as Get a single mapping

Retire mapping

Retire a mapping

DELETE /user/sources/:source/mappings/:mapping/
DELETE /users/:user/sources/:source/mappings/:mapping/
DELETE /orgs/:org/sources/:source/mappings/:mapping/

Parameters
- purge (optional) string - default is "false"; set to "true" to actually delete the mapping from all source versions
Notes
- DELETE does not actually delete the mapping unless "purge" is set to "true"; rather, it sets its "retired" attribute to "true" so that it does not show up by default in results, and it indicates to users that the mapping should no longer be used.

Response

Status: 204 No Content

Search and Filter Behavior

Text Search (e.g. q=criteria) - NOTE: Number of plus-signs (+) indicates relative relevancy weight of the term
- Note that search criteria should be surrounded by quotes to appropriately handle whitespace, e.g. https://api.openconceptlab.org/mappings/?concept=%22Disorder%20of%20Lymphatic%20System
- mapping.from_concept_code (++++), mapping.to_concept_code (++++), mapping.from_concept_name (++), mapping.to_concept_name (++)
- external_id (+)
Facets
- retired - mapping.retired
- mapType - mapping.map_type
- source - mapping.source
- owner - mapping.owner
- ownerType - mapping.owner_type
- conceptSource - mapping.from_concept.source OR mapping.to_concept.source
- fromConceptSource - mapping.from_concept.source
- toConceptSource - mapping.to_concept.source
- conceptOwner - mapping.from_concept.owner OR mapping.to_concept.owner
- fromConceptOwner - mapping.to_concept.owner
- toConceptOwner - mapping.to_concept.owner
- conceptOnwerType - mapping.from_concept_owner_type OR mapping.to_concept_owner_type
- fromConceptOnwerType - mapping.from_concept_owner_type
- toConceptOnwerType - mapping.to_concept_owner_type
Filters
- concept - mapping.from_concept_code OR mapping.to_concept_code OR mapping.from_concept_name OR mapping.to_concept_name
- fromConcept - mapping.from_concept_code OR mapping.from_concept_name
- toConcept - mapping.to_concept_code OR mapping.to_concept_name
Sort
- bestMatch (default) - see text search fields above
- name (Asc/Desc) - mapping.name
- lastUpdated (Asc/Desc) - mapping.updated_on

Issues and Potential Future Features

Add support for URL parameters for filtering mappings (e.g. "fromConcept=/orgs/CIEL/sources/CIEL/concepts/3/")

Overview

Overview

Resources

Import / Export

Troubleshooting & Operations

Other

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mappings

Table of Contents

Overview

Versioning of mappings

Get a single mapping

Example

Response

List mappings for a concept within a single source

Response

List all mappings within a specific source

Example

Response

List mappings across public sources

Response

Create a new mapping

Examples

Response

Edit a mapping

Examples

Response

Retire mapping

Response

Search and Filter Behavior

Issues and Potential Future Features

Clone this wiki locally