On this page:

5.15Creating Data

 

This section contains information about methods for creating data in the CDR.

5.15.1Auto Creating Reference Targets

 

Often when batch processing data from multiple sources, you will have data from one source that has references to data from other sources.

For example, a collection of Observation resources could be imported from a lab system data source at the same time that a collection of Patient resources is created from a patient administration data source. The Observation resources would have references to the Patient resources. Under ideal conditions, the Patient resource would process first and be present for the Observation to link to. In the real world however, often it is hard to control the order that transactions occur, and so it might be possible for an Observation to be processed before its Patient. By default this would cause an error since the Observation would have an invalid reference, and nothing would be stored. This section describes several strategies for solving this issue.

Transaction With Conditional Create

A common solution to this issue is to use a FHIR Transaction operation containing a conditional create. This involves creating a Transaction Bundle with the following properties:

  • One or more entries containing an Observation resource with a request.method value of POST. This means that the server should create the new Observation resources, and automatically assign them new IDs.

  • An entry containing a Patient resource with:

    • A request.method value of POST

    • A fullUrl value containing a temporary UUID. This is used as the target for references to this resource from other resources.

    • A request.ifNoneExist value containing a search URL that could be used to find this resource (in the example below, a search for the Patient by identifier). This indicates to the server that this resource should only be created if no existing resource already matches the given search criteria.

  • The Observation resources contain a reference where the target is the fullUrl UUID for the Patient entry. If the Patient target was created (because it did not already exist) the reference will automatically be replaced with a reference to the newly created resource. If the Patient target was not created (because it already existed), the reference will automatically be replaced with a reference to the pre-existing Patient resource.

An example Transaction Bundle is shown below. It should be POSTed to the root of the FHIR Endpoint module server.

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [ {

    "request": {
      "method": "POST",
      "url": "Observation"
    },
    "resource": {
      "resourceType": "Observation",
      "status": "final",
      "code": {
        "coding": [ {
          "system": "http://loinc.org",
          "code": "789-8",
          "display": "Erythrocytes [#/volume] in Blood by Automated count"
        } ]
      },
      "subject": {
        "reference": "urn:uuid:3bc44de3-069d-442d-829b-f3ef68cae371"
      },
      "valueQuantity": {
        "value": 4.12,
        "unit": "10 trillion/L",
        "system": "http://unitsofmeasure.org",
        "code": "10*12/L"
      }
    }

  },{

    "fullUrl": "urn:uuid:3bc44de3-069d-442d-829b-f3ef68cae371",
    "request": {
      "method": "POST",
      "url": "Patient",
      "ifNoneExist": "identifier=http://acme.org/mrns|12345"
    },
    "resource": {
      "resourceType": "Patient",
      "identifier": [ {
        "system": "http://acme.org/mrns",
        "value": "12345"
      } ],
      "name": [ {
        "family": "Jameson",
        "given": [ "J", "Jonah" ]
      } ],
      "gender": "male"
    }

  } ]
}

Auto-Create Placeholder Reference Targets

If the Auto-Create Placeholder Reference Targets setting is enabled in the FHIR Storage module configuration, it is possible to have the server automatically create an empty "Placeholder" resource with a pre-assigned ID.

This technique is somewhat less complex than the example above, since it does not require a transaction bundle to be created. With this technique, the ID (not the identifier) of the target resource must be known. For example, the following payload could be POSTed to [baseUrl]/Observation, and would result in the creation of an empty resource with the ID Patient/ABC if one does not already exist. Note that if you want to be able to use this technique with purely numeric resource IDs you will also need to adjust the Client ID Mode.

{
  "resourceType": "Observation",
  "status": "final",
  "code": {
    "coding": [ {
      "system": "http://loinc.org",
      "code": "789-8"
    } ]
  },
  "subject": {
    "reference": "Patient/ABC"
  },
  "valueQuantity": {
    "value": 4.12,
    "system": "http://unitsofmeasure.org",
    "code": "10*12/L"
  }
}

Auto-Create Placeholder Reference Targets with Identifier

If the Auto-Create Placeholder Reference Targets setting is enabled in the FHIR Storage module configuration (as shown above), and the Allow Inline Match URL References Enabled setting is also enabled, you can refine the behavior shown above further.

In this case, it is possible to use an "Inline Match URL" instead of a hardcoded resource ID, and you can then achieve similar behavior to the Transaction Bundle use case.

Consider the following Observation being POSTed to /Observation.

{
  "resourceType": "Observation",
  "status": "final",
  "code": {
    "coding": [ {
      "system": "http://loinc.org",
      "code": "789-8"
    } ]
  },
  "subject": {
    "reference": "Patient?identifier=http://foo|1234",
    "identifier": {
      "system": "http://foo",
      "value": "1234"
    }
  },
  "valueQuantity": {
    "value": 4.12,
    "system": "http://unitsofmeasure.org",
    "code": "10*12/L"
  }
}

In this case, the reference will be treated as a local search (in this case for a Patient with the identifier shown), and executed as such. If the search finds zero results, a new Patient resource will be created and the Patient.identifier value will be populated with the Reference.identifier value shown. The reference will then be automatically replaced with a reference to this new Patient. If the search finds one result, the reference will then be automatically replaced with a reference to the found Patient.