# Your First Golden Resource

MDM (Master Data Management) lets Smile CDR automatically detect when two patient records in the repository represent the same real-world person. When a match is found, MDM creates a **Golden Resource** — a single canonical Patient that acts as the permanent identifier for that person — and records **links** between the Golden Resource and each matching source record.

Golden Resource linking is one of several MDM strategies supported by Smile CDR; this tutorial demonstrates the [Probabilistic MDM](/content/docs/mdm/mdm.html#probabilistic-mdm/index.html) strategy. If you are not sure this is the right approach for your environment, start with [Selecting a deduplication strategy](/content/docs/mdm/mdm.html#selecting-a-deduplication-strategy/index.html).

This tutorial is for administrators with no prior MDM experience. It walks through every step from a fresh Smile CDR installation:

1. Enabling and configuring the MDM module with a simple set of match rules
2. Ingesting two Patient records that satisfy those rules
3. Querying the MDM links that were created automatically
4. Retrieving and reading the Golden Resource

By the end you will have seen the complete MDM lifecycle for a single matched pair.

MDM is a Premium Solution and requires a separately purchased license. Contact [sales@smiledigitalhealth.com](mailto:sales@smiledigitalhealth.com) if you need to enable this feature.

# Prerequisites

- A running Smile CDR installation. See the [Quick Start Guide](/content/docs/quickstart/smile_quickstart.html) if you need to install one.
- Access to the Web Admin Console at `http://localhost:9100` using the default `admin` credentials.
- A tool for making HTTP requests such as curl, Postman, or the [FHIRWeb Console](/content/docs/fhir_repository/fhirweb_console.html) built into Smile CDR.
- The FHIR base URL for your instance. The default is `http://localhost:8000`.

# Step 1: Create a User for This Tutorial

MDM operations require specific permissions. Create a dedicated user rather than using the built-in admin account.

**Open the User Manager**

In the Web Admin Console, go to **Users & Authorization → User Management** and click **Add User**.

**Set credentials and permissions**

Name the user `mdm-tutorial` and choose a password. Grant the following permissions:

| Permission | Why it is needed |
| --- | --- |
| `FHIR_WRITE_ALL_OF_TYPE` (`Patient`) | Create Patient resources |
| `FHIR_READ_ALL_OF_TYPE` (`Patient`) | Read Patient resources and Golden Resources |
| `FHIR_MDM_ADMIN` | Execute MDM FHIR operations such as `$mdm-query-links` |
| `MDM_ADMIN` | Access MDM administrative functions |

Save the user.

# Step 2: Enable MDM on the FHIR Storage Module

MDM uses Smile CDR's subscription infrastructure to process resources in the background. Two settings must be enabled on the FHIR Storage module before any other MDM configuration will work.

**Open the FHIR Storage module**

In the Web Admin Console, go to **Configuration → Module Config** and open your FHIR Storage module.

**Enable subscriptions and MDM**

Locate and set the following properties:

| Property | Value |
| --- | --- |
| [MDM Mode Enabled](/content/docs/configuration_categories/fhir_mdm.html#property-mdm-mode-enabled-experimental/index.html) | `true` |
| [Subscription Message Enabled](/content/docs/configuration_categories/fhir_subscription_persistence.html#subscription.message.enabled) | `true` |

**Save and restart the module**

Click **Save**, then restart the FHIR Storage module for the changes to take effect.

# Step 3: Add and Configure the MDM Module

**Create the module**

Go to **Configuration → Module Config → Add Module** and choose **MDM**. Set the **Consumer Thread Count** to `1` for this tutorial.

**Set the subscription dependency**

Under **Module Dependencies**, select the default Subscription Matching module.

**Enter the MDM Rule Definition Script**

The MDM Rule Definition Script is a JSON document that controls how MDM finds candidates and decides whether two resources represent the same person. Paste the following JSON into the **MDM Rule Definition Script** field:

```json
{
  "version": "tutorial-v1",
  "mdmTypes": ["Patient"],
  "candidateSearchParams": [\
    {\
      "resourceType": "Patient",\
      "searchParams": ["birthdate"]\
    }\
  ],
  "candidateFilterSearchParams": [],
  "matchFields": [\
    {\
      "name": "family-name",\
      "resourceType": "Patient",\
      "resourcePath": "name.family",\
      "matcher": {\
        "algorithm": "METAPHONE"\
      }\
    },\
    {\
      "name": "given-name",\
      "resourceType": "Patient",\
      "resourcePath": "name.given",\
      "matcher": {\
        "algorithm": "METAPHONE"\
      }\
    }\
  ],
  "matchResultMap": {
    "family-name,given-name": "MATCH"
  }
}
```

Copy

Here is what each section does:

- **`mdmTypes`** — MDM will only process `Patient` resources. Other resource types are ignored.
- **`candidateSearchParams`** — Before running any comparisons, MDM searches the repository for existing Patients that share the same `birthdate` as the incoming resource. Only those candidates are passed to the next phase. Birth date is a good candidate search parameter because it is specific enough to return a small number of candidates without being so specific that typos cause candidates to be missed.
- **`matchFields`** — The family name and given name are compared against each candidate. `METAPHONE` encodes each name phonetically before comparing, so alternate spellings that sound the same — for example `John` and `Jon` — are treated as equal.
- **`matchResultMap`** — When both field comparisons pass, the result is `MATCH`. MDM automatically creates a link with no manual review required.

**Save and start the MDM module.**

# Step 4: Create the First Patient

Send the following HTTP request to create the first Patient record. Replace `mdm-tutorial:password` with the credentials you created in Step 1.

```http
POST http://localhost:8000/Patient

{
  "resourceType": "Patient",
  "name": [\
    {\
      "family": "Smith",\
      "given": ["John"]\
    }\
  ],
  "birthDate": "1985-03-15",
  "gender": "male"
}
```

Copy

The server responds with `201 Created` and a `Location` header containing the assigned ID:

```none
Location: http://localhost:8000/Patient/101/_history/1
```

Copy

Note this patient's ID — `101` in this example. Your server will assign a different value.

In the background, MDM immediately processes this resource. Because no other Patient with the same birth date exists yet, MDM creates a new Golden Resource and a link from that Golden Resource to `Patient/101`.

# Step 5: Create the Second Patient

Create a second Patient. The given name is `Jon` rather than `John`. Under the Metaphone algorithm both spellings encode to the same phonetic key (`JN`), so this difference will not prevent a match.

```http
POST http://localhost:8000/Patient

{
  "resourceType": "Patient",
  "name": [\
    {\
      "family": "Smith",\
      "given": ["Jon"]\
    }\
  ],
  "birthDate": "1985-03-15",
  "gender": "male"
}
```

Copy

Note this patient's ID as well — `102` in this example.

After a brief moment, MDM processes the second patient asynchronously:

1. It searches for existing Patients with `birthdate = 1985-03-15` and finds `Patient/101`.
2. It compares the two records using the configured match fields. Both family names encode to the same Metaphone key (`SM0`). Both given names encode to the same Metaphone key (`JN`). Both comparisons pass.
3. It creates a `MATCH` link between the existing Golden Resource and `Patient/102`.

Both source records are now linked to the same Golden Resource.

# Step 6: Inspect the MDM Links

Query `$mdm-query-links` to see the links that were created:

```http
GET http://localhost:8000/$mdm-query-links?resourceType=Patient
```

Copy

The response is a `Parameters` resource. You should see two `link` entries — one for each source Patient — both pointing to the same `goldenResourceId`. The actual IDs on your server will differ from this example:

```json
{
  "resourceType": "Parameters",
  "parameter": [\
    {\
      "name": "total",\
      "valueDecimal": 2\
    },\
    {\
      "name": "self",\
      "valueUri": "http://localhost:8000/$mdm-query-links?resourceType=Patient&_offset=0&_count=20"\
    },\
    {\
      "name": "link",\
      "part": [\
        { "name": "goldenResourceId",    "valueString": "Patient/100" },\
        { "name": "sourceResourceId",    "valueString": "Patient/101" },\
        { "name": "matchResult",         "valueString": "MATCH" },\
        { "name": "linkSource",          "valueString": "AUTO" },\
        { "name": "hadToCreateNewResource", "valueBoolean": true },\
        { "name": "score",               "valueDecimal": 1.0 }\
      ]\
    },\
    {\
      "name": "link",\
      "part": [\
        { "name": "goldenResourceId",    "valueString": "Patient/100" },\
        { "name": "sourceResourceId",    "valueString": "Patient/102" },\
        { "name": "matchResult",         "valueString": "MATCH" },\
        { "name": "linkSource",          "valueString": "AUTO" },\
        { "name": "hadToCreateNewResource", "valueBoolean": false },\
        { "name": "score",               "valueDecimal": 1.0 }\
      ]\
    }\
  ]
}
```

Copy

Key fields to note:

- Both links share the same `goldenResourceId` (`Patient/100` in this example). MDM created this Golden Resource automatically when the first patient arrived and reused it when the second patient matched.
- `matchResult: MATCH` means MDM was confident enough to link automatically, with no manual review needed.
- `linkSource: AUTO` means the link was created by MDM processing, as opposed to a data steward creating it manually.
- The first link has `hadToCreateNewResource: true` because there was no existing Golden Resource for this person yet. The second link has `false` because it reused the existing one.

Make a note of the `goldenResourceId` value. You will use it in the next step.

# Step 7: Read the Golden Resource

Retrieve the Golden Resource by ID (using the value from the previous step in place of `100`):

```http
GET http://localhost:8000/Patient/100
```

Copy

The response is a Patient resource that MDM created and manages. It looks like an ordinary Patient, but its `meta.tag` contains an entry that identifies it as a Golden Resource:

```json
{
  "resourceType": "Patient",
  "id": "100",
  "meta": {
    "tag": [\
      {\
        "system": "http://hapifhir.io/fhir/NamingSystem/mdm-record-status",\
        "code": "GOLDEN_RECORD"\
      }\
    ]
  },
  "identifier": [\
    {\
      "system": "http://hapifhir.io/fhir/NamingSystem/mdm-golden-resource-enterprise-id",\
      "value": "c0a9be58-1aa5-4b76-89b6-20c1b0f3fe11"\
    }\
  ]
}
```

Copy

Note that there is no demographic data on the Golden Resource. This is because no survivorship rules were configured in this tutorial. Survivorship rules control which source record's data is applied when multiple records are linked — see [MDM Survivorship](/content/docs/mdm/mdm_survivorship.html) for details.

You can also search for all Golden Patient resources in the repository using the `_tag` search parameter:

```http
GET http://localhost:8000/Patient?_tag=http://hapifhir.io/fhir/NamingSystem/mdm-record-status|GOLDEN_RECORD
```

Copy

# What You've Accomplished

In this tutorial you:

1. Configured a simple MDM rule set that narrows candidates by birthdate and confirms matches using phonetic name comparison.
2. Ingested two Patient records whose given names are spelled differently but sound the same under the Metaphone algorithm.
3. Observed that MDM automatically linked both source records to a single Golden Resource with a `MATCH` result.
4. Retrieved and read the resulting links using `$mdm-query-links` and fetched the Golden Resource directly by ID.

# Next Steps

- **Reviewing possible matches**: Rules can be tuned to produce `POSSIBLE_MATCH` links for cases that need human review. The [MDM User Interface](/content/docs/guide_tutorials/tutorial_mdm_ui.html) provides a data stewardship workflow for resolving these.
- **Survivorship rules**: Control which source record's field values are promoted to the Golden Resource using [MDM Survivorship](/content/docs/mdm/mdm_survivorship.html).
- **More match algorithms**: The full set of phonetic, string, date, and similarity algorithms available for `matchFields` is documented in [Supported Match Algorithms](/content/docs/mdm/supported_match_algorithms.html).
- **Enterprise identifiers**: When records share a known enterprise identifier, EID-based matching can significantly speed up and simplify your rule set — see [Using EIDs in MDM Rule Definition](/content/docs/mdm/mdm_rule_definition_eid.html).
- **Iterating on rules**: See how to measure false positive and false negative rates and refine your rules iteratively in the [MDM Tutorial](/content/docs/guide_tutorials/tutorial_mdm.html).

[MDM UI Tutorial](/content/docs/guide_tutorials/tutorial_mdm_ui.html)

MDM First Golden Resource Tutorial

Tutorials

[Introduction](/content/docs/guide_tutorials/tutorial_intro.html)
[Integration Testing Tutorial](/content/docs/guide_tutorials/tutorial_integration_test.html)
[Custom Operations Tutorial](/content/docs/guide_tutorials/tutorial_custom_operations.html)
[HL7 v2.x Ingestion Tutorial](/content/docs/guide_tutorials/tutorial_processing_hl7_v2x_feeds.html)
[Federated OAuth2/OIDC Tutorial](/content/docs/guide_tutorials/tutorial_federated_oauth2.html)
[MDM Tutorial](/content/docs/guide_tutorials/tutorial_mdm.html)
[MDM UI Tutorial](/content/docs/guide_tutorials/tutorial_mdm_ui.html)
[MDM First Golden Resource Tutorial](/content/docs/guide_tutorials/first_golden_resource.html)
[MDM Advanced Rule Authoring Tutorial](/content/docs/guide_tutorials/advanced_rule_authoring.html)
[MDM Web UI Admin Setup Tutorial](/content/docs/guide_tutorials/mdm_web_ui_admin_setup.html)
[CDA Import Tutorial](/content/docs/guide_tutorials/tutorial_cda_import.html)
[CDA Export Tutorial](/content/docs/guide_tutorials/tutorial_cda_export.html)
[CDA Export - Custom Narrative Generation Tutorial](/content/docs/guide_tutorials/tutorial_cda_export_narrative_generation.html)
[CDA Import JSON example](/content/docs/guide_tutorials/tutorial_cda_import_json.html)
[CDA Export Template JSON example](/content/docs/guide_tutorials/tutorial_cda_export_json.html)
[Consent Tutorial](/content/docs/guide_tutorials/tutorial_consent.html)
[CMS-0057-F IG Setup Tutorial](/content/docs/guide_tutorials/tutorial_terminology_cms57f.html)

[MDM Advanced Rule Authoring Tutorial](/content/docs/guide_tutorials/advanced_rule_authoring.html)