Create or extend Semantic Mapping Templates

Background and Strategy

The Ursa Health Core Data Model comes pre-loaded with a number of Semantic Mapping Templates, which cover all the fields in each of the Natural objects. For example, the Institutional Claim Header Fields Semantic Mapping Template contains the fields expected by the Institutional Claim Headers Natural object. There are also a handful of templates – for example, Claims Transaction Fields – not associated with any natural object, but which cover fields commonly needed for integrating source data.

However, most integrations will require mapping at least some fields for which there is no preexisting Semantic Mapping Template field. In these scenarios, the user must add fields to existing Semantic Mapping Templates, or perhaps create entire new Semantic Mapping Templates.

For each source data field not already represented in a Semantic Mapping Template, there are three broad scenarios that will dictate the appropriate approach to extending or creating Semantic Mapping Templates:

1. The source data field is needed for integration logic only.

Examples of this scenario include foreign keys used to join highly normalized dimension tables in a source system but not needed after those joins have been performed. (See the “one-to-zero” identifier cenario described in Determine the mappings for identifier fields.)

The recommended approach for adding these new fields is to create a single new Semantic Mapping Template for each source system, and simply add new fields needed to integrate data from that source to this dedicated template. That one template can then be invoked by any Semantic Mapping object involved in the integration of data from that source system, acting as a one-stop-shop superset of needed fields.

2. The source data field is needed for downstream analytics, but is a feature of a concept already represented as a Natural object.

An example of this scenario might be a patient feature unique to the organization, such as a region or service line category; the appropriate landing spot for which would be the Patients Natural object.

The recommended approach for this scenario is to simply add the new fields to the Semantic Mapping Template assocatiated with the appropriate Natural object. (Later, it will also be necessary to augment the Natural object itself to incorporate the new fields; see Update Natural objects to accommodate new source data fields.)

3. The source data field is needed for downstream analytics, and is a feature of a new concept not already represented as a Natural object.

An example of this scenario might be the features needed to describe a claim transaction, a professional fee schedule, or a medical device (none of which have an associated Natural object).

The recommended approach for this scenario is to create a new Semantic Mapping Template for fields on this object. (Later, it will also be necessary to create the new Natural object itself; see Create new Natural objects as needed.)

Detailed Implementation Guidance

1. Semantic Mapping Templates can be found and created in the Metadata Manager zone.
2. The filter at the top of the Semantic Mapping Templates page can be used to identify templates by name, and to identify templates that contain a field containing the filter string. The filter is a useful tool to check whether a desired field already exists in a template.
3. Use a consistent naming convention for Semantic Mapping Templates; e.g., "Source [Source ID] Additional Fields" for the templates needed to handle scenario 1; or "[Natural object name] Fields" for the templates needed to handle scenario 3.
4. Like most assets in Ursa Studio, Semantic Mapping Templates may be cloned, which may be an attractive option for the creation of templates for new Natural objects described in scenario 3.
5. Remember when working on Semantic Mapping Templates that there is no expectation that all the fields on a template will be used by any single Semantic Mapping object that invokes it. Semantic Mapping Templates are meant to cover the superset of fields associated with a particular concept that could theoretically appear in any kind of source data; it’s not uncommon for fewer than, say, 20% of available template fields to receive a mapped source data value in a particular Semantic Mapping object.
6. Note that it is not possible to map a source data field to a new destination field "on the fly" in a Semantic Mapping object without first setting up that field in a Semantic Mapping Template. (Forcing Ursa Studio users to pre-define fields in Semantic Mapping Templates was a conscious design decision intended to support better data governance and impose a degree of standardization on the semantic mapping process. The use of templates ensures that field names and data types are letter-perfect, which avoids bugs and facilitates the use of some other Ursa Studio tooling, such as automated term matching and the automatic mapping of fields into Integrator object Input Field Mapping panel.)

Examples

Example 1: "One-to-zero" identifier (scenario 1)

The source data system (Source ID = "DS1") has a dimension table for diagnoses:

Entries in the diagnosis dimension table are referenced in a medical claims diagnosis table (grain size = one record per diagnosis code associated with a medical claim):

To ensure the fields are able to be mapped, we create a new Semantic Mapping Template, "Source DS1 Additional Fields", and add a field for Source Local Diagnosis ID (data type = string). When mapping both the tables above, the "Source DS1 Additional Fields" template can be invoked, providing a template field for Source Local Diagnosis ID.