Data map API Spec: Difference between revisions
ErgoSoftUK (talk | contribs) No edit summary |
ErgoSoftUK (talk | contribs) No edit summary |
||
Line 94: | Line 94: | ||
==== Node details ==== | ==== Node details ==== | ||
The mapping node is the effecive starting point for the maps. It represents a | The mapping node is the effecive starting point for the maps. It represents a set of codes or values within a specific context scenario. The node has associated with it its own identifier for convenience and a concept representing the data model property of that node.<syntaxhighlight lang="mysql"> | ||
CREATE TABLE map_node ( | CREATE TABLE map_node ( | ||
id INT AUTO_INCREMENT, | id INT AUTO_INCREMENT, | ||
Line 114: | Line 114: | ||
==== Node mappings ==== | ==== Node mappings ==== | ||
For each node, a number of mappings exist, from either a code or a term, to an Information Model concept.<syntaxhighlight lang="mysql"> | For each node, a number of mappings exist, from either a code or a term within that node context, to an Information Model concept.<syntaxhighlight lang="mysql"> | ||
CREATE TABLE map_node_value ( | CREATE TABLE map_node_value ( | ||
id INT AUTO_INCREMENT, | id INT AUTO_INCREMENT, | ||
Line 149: | Line 149: | ||
=== Functional implementation === | === Functional implementation === | ||
<br /> | A single general mapping api will be exposed which can be called with any of the standard Map????Request structures. The existing IM client wrapper library will be extended to include mapping api calls for simplified internal use. | ||
==== Node identification ==== | |||
Fore property concept lookups, a distinct node search is performed on the map_context table, matching on all available columns. If multiple matches are found (for example where provider is not supplied but 2 provider rows exist and point to different nodes) then an exception is thrown. | |||
If no match is found then a new (draft) map_context row is inserted along with corresponding map_node and concept entries, using all available data. | |||
Once the node is identified (or created), the associated property concept can be retrieved. | |||
==== Node mappings ==== | |||
For value mappings, an additional search is performed on the map_node_value table, based on the node id and the code/term. Again if no match is found, a new (draft) concept is created and added to the mapping list.<br /> |
Latest revision as of 15:57, 1 July 2020
Overview
The API should take a JSON which is conforms to one of the following Information Model Schema Structures.
- MapRequest
- MapColumnRequest
- MapColumnValueRequest
The request will contain the mapping source, provided as either
- A full context string only
- A partial context string and supplimentary identifiers
- Identifiers only
Database Implementation
Node identification
Note: Contexts are given below in a path notation for clarity. They could just as easily be UUID's, concept IRI's or hash values, and therefore not computable. Database table data examples may also contain names or Iris in place of numeric identifiers, for clarity.
The first step of the mapping process is to identify the correct mapping node and for that, a mapping context is required. A given mapping context can be provided in a number of different ways, for example, for a Barts Cerner CDS Emergency Department type map, it could be given as a full context string...
{
"Context": "/BRTS/CRNR/CDS/EMGCY/department_type"
}
...a set of identifiers...
{
"Provider": ":CM_Organisation_Barts",
"System" : ":CM_System_Cerner",
"Schema" : "CDS",
"Table" : "emergency",
"Column" : "department_type"
}
...or a combinaton of a partial context string with supplimentary identifiers...
{
"Context": "/BRTS/CRNR",
"Schema" : "CDS",
"Table" : "emergency",
"Column" : "department_type"
}
It should also be possible to map multiple contexts to a single mapping node in the event of a common map. In the above example, because the CDS Emergency department type data is an NHS Data Dictionary value set (rather than local code set), then they are organisation agnostic therefore a context of "/HMRTN/CRNR/CDS/EMGCY/department_type" should point to the same node. Indeed, if the client knows the data to be organisation agnostic, they could indeed provide only a partial set of identifier, omitting both context and provider. A map_context table is therefore required identify a node given any combination of the above.
CREATE TABLE map_context (
`id` INT AUTO_INCREMENT,
`context` VARCHAR(200) NOT NULL,
`provider` INT,
`system` INT,
`schema` VARCHAR(50),
`table` VARCHAR(100),
`column` VARCHAR(250),
`node` INT,
`draft` BOOLEAN NOT NULL DEFAULT TRUE,
);
Table entries for the examples above, all pointing to the same map node, would be as follows
Context | Provider | System | Schema | Table | Column | Node |
---|---|---|---|---|---|---|
/BRTS/CRNR/CDS/EMGCY/department_type | /CDS/EMGCY/department_type | |||||
:CM_Organisation_Barts | :CM_System_Cerner | CDS | emergency | department_type | /CDS/EMGCY/department_type | |
/BRTS/CRNR | CDS | emergency | department_type | /CDS/EMGCY/department_type | ||
/HMRTN/CRNR/EMGNCY/department_type | /CDS/EMGCY/department_type |
Node details
The mapping node is the effecive starting point for the maps. It represents a set of codes or values within a specific context scenario. The node has associated with it its own identifier for convenience and a concept representing the data model property of that node.
CREATE TABLE map_node (
id INT AUTO_INCREMENT,
node VARCHAR(200),
concept INT NOT NULL,
draft BOOLEAN NOT NULL DEFAULT TRUE,
PRIMARY KEY map_node_pk (id),
UNIQUE INDEX map_node_uq (node)
);
Continuing the example above, an entry for the (organisation agnostic) CDS emergency department type mapping node would be
Node | Concept |
---|---|
/CDS/EMGCY/department_type | :DM_aAndEDepartmentType |
Node mappings
For each node, a number of mappings exist, from either a code or a term within that node context, to an Information Model concept.
CREATE TABLE map_node_value (
id INT AUTO_INCREMENT,
node INT NOT NULL,
value VARCHAR(250),
concept INT NOT NULL,
draft BOOLEAN NOT NULL DEFAULT TRUE,
PRIMARY KEY map_node_value_pk (id),
UNIQUE INDEX map_node_value_uq (node, value)
);
Entries for the emergency department type would be as follows
Node | Value | Concept |
---|---|---|
/CDS/EMGCY/department_type | 01 | :CM_AEDepType1 |
/CDS/EMGCY/department_type | 02 | :CM_AEDepType2 |
/CDS/EMGCY/department_type | 03 | :CM_AEDepType3 |
/CDS/EMGCY/department_type | 04 | :CM_AEDepType4 |
Functional implementation
A single general mapping api will be exposed which can be called with any of the standard Map????Request structures. The existing IM client wrapper library will be extended to include mapping api calls for simplified internal use.
Node identification
Fore property concept lookups, a distinct node search is performed on the map_context table, matching on all available columns. If multiple matches are found (for example where provider is not supplied but 2 provider rows exist and point to different nodes) then an exception is thrown.
If no match is found then a new (draft) map_context row is inserted along with corresponding map_node and concept entries, using all available data.
Once the node is identified (or created), the associated property concept can be retrieved.
Node mappings
For value mappings, an additional search is performed on the map_node_value table, based on the node id and the code/term. Again if no match is found, a new (draft) concept is created and added to the mapping list.