Mappings

Most of real-world healthcare applications are integrated with 3rd-party systems to ingest data from them. Using the Mapping resource, you can describe how 3rd-party data is being converted to the FHIR format. Mappings are written using the JUTE language.
The Mapping is an Aidbox resource, so all CRUD operations are applicable to it. The Mapping's schema is pretty straightforward:
1
resourceType: Mapping
2
id: mapping-id-here
3
body:
4
  # Executable part of the mapping written in the JUTE language (required)
5
scopeSchema:
6
  # A JSON schema for the incoming data (optional)
Copied!
If the scopeSchema attribute is provided, incoming mapping data (also called a scope) will be validated against it first. Then, a JUTE template from the body will be executed. Mapping should return a valid Transaction Bundle, so when applied, it will be able to operate with multiple resources not just single one.
Example
Let's do a simple mapping which will create a Patient resource from the following data structure:
1
firstName: John
2
lastName: Smith
3
birthDate: 2000-01-02
Copied!
The following request will create a mapping resource:
If you're not familiar with JUTE, please check out JUTE Tutorial to understand basic concepts.
1
PUT /Mapping/example
2
Content-Type: text/yaml
3
​
4
resourceType: Mapping
5
id: example
6
scopeSchema:
7
  # JSON schema describing incoming data structure
8
  type: object
9
  required: ["firstName", "lastName", "birthDate"]
10
  properties:
11
    firstName:
12
      type: string 
13
    lastName:
14
      type: string
15
    birthDate:
16
      type: string
17
      pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}quot;
18
​
19
body:
20
  # JUTE template which transforms incoming data to Transaction Bundle
21
  resourceType: Bundle
22
  type: transaction
23
  entry:
24
    - request:
25
        url: /fhir/Patient
26
        method: POST
27
      resource:
28
        resourceType: Patient
29
        birthDate: $ birthDate
30
        name:
31
          - given: ["$ firstName"]
32
            family: $ lastName
33
​
Copied!
When a template is created, you can invoke the $apply operation on it to generate a Patient resource and save it into the database:
1
POST /Mapping/example/$apply
2
Content-Type: text/yaml
3
​
4
firstName: John
5
lastName: Smith
6
birthDate: '2010-12-12'
Copied!
$apply Endpoint
To execute Mapping and store its result to the Aidbox database, do a POST request to the $apply endpoint. Request's body will be passed to a JUTE as an incoming data (scope):
1
POST /Mapping/<mapping-id>/$apply
2
Content-Type: application/json
3
​
4
{ "foo": 42, "bar": "hello" }
Copied!
Make sure that your Mapping returns a Transaction Bundle, otherwise its result won't be persisted to a database.
$debug Endpoint
To check Mapping's result without actual persisting, you can do a POST request to the $debug endpoint:
1
POST /Mapping/<mapping-id>/$debug
2
Content-Type: text/yaml
3
​
4
foo: 42
5
bar: hello
Copied!
Response will contain a mapping result or an error if evaluation failed for some reason.
Global $debug Endpoint
There is a way to check a mapping result without persisting it as a resource:
1
POST /Mapping/$debug
2
Content-Type: text/yaml
3
​
4
mapping:
5
  body:
6
    mul: $ 2 * foo
7
    str: $ "hello, " + name
8
    
9
  scopeSchema:
10
    type: object
11
    required: ["foo", "name"]
12
    properties:
13
      foo:
14
        type: integer
15
      name:
16
        type: string
17
    
18
scope:
19
  foo: 4
20
  name: "Bob"
Copied!
You pass both Mapping and incoming data (scope) in a request body. Request response will contain the mapping result or an error information.
Including Mapping inside other Mapping
In Aidbox, there is the $include directive which allows you to include a Mapping within another one:
1
PUT /Mapping/index
2
Content-Type: text/yaml
3
​
4
resourceType: Mapping
5
id: index
6
body:
7
  $switch: $ type
8
  patient:
9
    $include: "patient"
10
  practitioner:
11
    $include: "practitioner"
12
  $default: null
Copied!
This template will pass execution to either /Mapping/patient or /Mapping/practitioner depending on the value of the type key. Current evaluation scope will be passed to the included Mapping.
Because potentially there is a way to create an infinite recursion using the$include directive, there is an inclusion depth limit which equals to 5 for now.
Mapping Editor in the Aidbox UI
Mapping Editor UI
There is a Mapping Editor in the Aidbox UI with a built-in syntax checker and Debug capabilities. Search for the "Mappings" item in the left navigation menu.

Integrations - Previous

Authentication

Next - Tools

Aidbox SDK

Last modified 1yr ago

Copy link

Contents

Example

$apply Endpoint

$debug Endpoint

Global $debug Endpoint

Including Mapping inside other Mapping

Mapping Editor in the Aidbox UI