Skip to content
This repository has been archived by the owner on Aug 11, 2021. It is now read-only.

mappings

Jump to bottom
Jonathan Payne edited this page Feb 16, 2015 · 39 revisions

Table of Contents

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 defined 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 to_concept_name fields.

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.

New model

Similar to concepts, mappings are owned by sources, rather than by their from_concept. Modifications to mappings do not directly effect the concepts to which it is 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.

However, the from_concept must always be stored in OCL. There are two types of to_concepts:

  1. Internal - The to concept is stored in OCL
  2. External - The from source is defined in OCL, but it is just a placeholder

Following are the fields that are required to be set for each type above:

field type
to_concept_url 1
to_concept_code 2
to_source_url 2

Versioning of mappings

  • Based on the new model in which mappings are saved with source versions, it may be necessary to treat versions of mappings exactly the same as versions of concepts, however until that is decided---
  • Version history is not stored for mappings - edits are in-place and only standard audit information is maintained ("created_on", "created_by", "updated_on", "updated_by")

Get a single mapping

  • Get a single mapping
GET /orgs/:org/sources/:source/mappings/:mapping/
GET /users/:user/sources/:source/mappings/:mapping/
GET /user/sources/:source/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_source_url": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/",
    "from_concept_url": "https://api.openconceptlab.org/v1/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": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICPC-2/",

    "source": "loinc2",
    "owner": "Regenstrief",
    "owner_type": "Organization",

    "url": "https://api.openconceptlab.org/v1/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

  • List mappings or inverse mappings for a concept
GET /user/sources/:source/concepts/:concept/mappings/
GET /users/:user/sources/:source/concepts/:concept/mappings/
GET /orgs/:org/sources/:source/concepts/:concept/mappings/
  • Parameters
    • 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": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "https://api.openconceptlab.org/v1/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": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_code": "A73",
        "to_concept_name": "Malaria",
        "to_source_code": "ICPC-2",
        "url": "https://api.openconceptlab.org/v1/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": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "from_concept_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffdea/",
    }
]

List mappings for a specific source

  • List all mappings for an organization or user's source based on its current state - NOTE: Retired mappings are excluded by default
GET /orgs/:org/sources/:source/mappings/
GET /users/:user/sources/:source/mappings/
GET /user/sources/:source/mappings/
  • List all mappings for a specific version of a source - NOTE: Retired mappings are excluded by default
GET /orgs/:org/sources/:source/:sourceVersion/mappings/
GET /users/:user/sources/:source/:sourceVersion/mappings/
GET /user/sources/:source/:sourceVersion/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 - maptype descriptor, such as "Same As", "Parent", "Child", etc.
    • includeInverseMappings (optional) string - "true" or "false"; default is "false"
    • Sources
      • source (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
      • from_source (optional) string - comma-separated list of sources for the "from" source; can be the "code" for the source (e.g. "SNOMED-CT" or "ICPC-2") or the fully specified URL
      • to_source (optional) string - comma-separated list of sources for the "to" source; can be the "code" for the source (e.g. "SNOMED-CT" or "ICPC-2") or the fully specified URL
    • Concepts
      • concept (optional) string - comma-separated list of concepts for the "from" or "to" concept; can be the "code" for the concept (e.g. A57) or the fully-specified URL
      • from_concept (optional) string - comma-separated list of concepts for the "from" concept; can be the "code" for the concept (e.g. A57) or the fully-specified URL
      • to_concept (optional) string - comma-separated list of concepts for the "to" concept; can be the "code" for the concept (e.g. A57) or the fully-specified URL

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": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/concepts/32700-7/",
        "to_concept_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICPC-2/concepts/A73/",
        "url": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/mappings/8d492ee0-c2cc-11de-8d13-0010c6dffd0f/",
    }
]

List mappings across sources

  • List mappings across all 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.
    • includeInverseMappings (optional) string - "true" or "false"; default is "false"
    • Sources
      • source (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
      • from_source (optional) string - comma-separated list of sources for the "from" source; can be the "code" for the source (e.g. "SNOMED-CT" or "ICPC-2") or the fully specified URL
      • to_source (optional) string - comma-separated list of sources for the "to" source; can be the "code" for the source (e.g. "SNOMED-CT" or "ICPC-2") or the fully specified URL
    • Concepts
      • concept (optional) string - comma-separated list of concepts for the "from" or "to" concept; can be the "code" for the concept (e.g. A57) or the fully-specified URL
      • from_concept (optional) string - comma-separated list of concepts for the "from" concept; can be the "code" for the concept (e.g. A57) or the fully-specified URL
      • to_concept (optional) string - comma-separated list of concepts for the "to" concept; can be the "code" for the concept (e.g. A57) or the fully-specified URL

Response

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

Create a new mapping

  • Create a new mapping originating from the specified concept
POST /user/sources/:source/mappings/
POST /users/:user/sources/:source/mappings/
POST /orgs/:org/sources/:source/mappings/
  • Input
    • Internal Mapping: to_concept is stored in OCL
      • map_type (required) string - map type
      • from_concept_url (required) string - URL of the "from" concept
      • to_concept_url (required) string - fully specified url for the concept
    • External Mapping: to_concept is not stored in OCL
      • map_type (required) string - map type
      • from_concept_url (required) string - URL of the "from" concept
      • to_source_code (required) string - short-code for the external source
      • to_concept_code (required) string - code for the to_concept
      • to_concept_name (optional) string - name of the to_concept

Examples

  • Internal mapping: to_concept is stored in OCL:
{
    "map_type": "Same As",
    "from_concept_url": "https://api.openconceptlab.org/v1/orgs/Columbia/sources/CIEL/concepts/161426/",
    "to_concept_url": "https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/loinc2/concepts/32700-7/"
}
  • External mapping: to_concept is not stored in OCL:
{
    "map_type": "Narrower Than",
    "from_concept_url": "https://api.openconceptlab.org/v1/orgs/Columbia/sources/CIEL/concepts/116125/",
    "to_source_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICPC-2/",
    "to_concept_code": "A73",
    "to_concept_name": "Malaria"
}

Response

Edit a mapping

  • Edit a mapping
POST /user/sources/:source/mappings/:mapping/
POST /users/:user/sources/:source/mappings/:mapping/
POST /orgs/:org/sources/:source/mappings/:mapping/
  • Input
    • Internal Mapping: to_concept is stored in OCL
      • map_type (optional) string - map type
      • from_concept_url (optional) string - URL of the "from" concept
      • to_concept_url (optional) string - fully specified url for the concept
    • External Mapping: to_concept is not stored in OCL
      • map_type (optional) string - map type
      • from_concept_url (optional) string - URL of the "from" concept
      • to_source_url (optional) string - fully specified url for the source - note that the source must be defined in OCL
      • to_concept_code (optional) string - code for the to_concept
      • to_concept_name (optional) string - name of the to_concept

Examples

  • Internal Mapping: to_concept is stored in OCL
{
    "map_type": "Same As",
    "to_concept_url": "https://api.openconceptlab.org/v1/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 mapping - NOTE that this does not delete the mapping; 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 mappings should no longer be used.
DELETE /user/sources/:source/mappings/:mapping/
DELETE /users/:user/sources/:source/mappings/:mapping/
DELETE /orgs/:org/sources/:source/mappings/:mapping/

Response

  • Status: 204 No Content

Issues

  • Confirm URL parameters supported for searching mappings
  • Should add "retire_reason" to indicate why mapping was retired and possibly which mapping to use in its place

Overview

Resources

Import / Export

Troubleshooting & Operations

Other

Clone this wiki locally