Versioned Resource References
In most cases, references between resources are versionless.
For example, suppose you have a Patient resource Patient/123, and an Observation resource Observation/456 with a Subject reference to the Patient. There may be many versions of the Patient resource on the server, but the Observation will typically not indicate a specific version.
{
"resourceType" : "Observation",
"id": "456",
"subject": {
"reference": "Patient/123"
}
}
By default, Smile CDR will remove any version information in references when it captures data or serializes it out to a client. This is the default behavior since unversioned references are more common in FHIR than versiones ones.
There are valid reasons to want to preserve versions in references however. For example, if you wish to implement a point-in-time architecture where it is always easy to determine which version of the target resource was current when the source resource was created. In this case, the Observation resource would look like this:
{
"resourceType" : "Observation",
"id": "456",
"subject": {
"reference": "Patient/123/_history/8"
}
}
In order to enable this type of reference, several configuration settings are available in Smile CDR.
A pair of settings controls whether Smile CDR will preserve versioned references:
Observation.subject
CarePlan.activity.detail.goal
When using Smile CDR in Repository Mode by combining a FHIR Storage module with a FHIR Endpoint module, these settings are found on the FHIR Storage module and will apply to any sources of data. This includes HTTP/REST FHIR Endpoints, but also includes ETL modules and other sources.
When using Smile CDR with Hybrid Providers Endpoint or the FHIR Gateway Endpoint, these settings are found on the FHIR Endpoint module.
When using Smile CDR in Repository Mode, it is possible to configure Smile CDR to automatically add a version to specific references. For example, suppose you want any ExplanationOfBenefit resources that are saved in the system to point to the current version of the referenced Patient resource at the time that the ExplanationOfBenefit was created.
The Automatically Version References at Paths setting can be configured with one or more resource paths. When a resource is stored, any references found at the specified paths will have the current version of the target appended, if a version is not already present.
Note that the path here is not a FHIRPath expression and can only include element names after the dots. For example:
Observation.subject
CarePlan.activity.detail.goal
The following example shows Automatically Version Referenced at Paths in action. In this example, we have a system that stores Patient resources and Claim resources. The Claim resource has a reference to the patient. We will use a FHIR transaction to perform an "upsert" on the Patient, along with a "create" for a new Claim resource.
To start we will configure the Automatically Version References at Paths setting with the following value, reflecting the path containg the reference we want to automatically version.
Claim.patient
Next, we will issue the following transaction (note that many required and useful data elements have been removed from these resources to keep the example simple):
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [ {
"fullUrl": "urn:uuid:bff26b84-d486-4671-9f25-d0d666fdc442",
"resource": {
"resourceType": "Patient",
"identifier": [ {
"system": "http://example.com/mrns",
"value": "12345"
} ],
"name": [ {
"family": "Smith",
"given": [ "John" ]
} ]
},
"request": {
"method": "PUT",
"url": "Patient?identifier=http://example.com/mrns|12345"
}
}, {
"resource": {
"resourceType": "Claim",
"identifier": [ {
"system": "http://example.com/claims",
"value": "98765"
} ],
"patient": {
"reference": "urn:uuid:bff26b84-d486-4671-9f25-d0d666fdc442"
}
},
"request": {
"method": "POST",
"url": "Claim"
}
} ]
}
With the example above, the placeholder (UUID) "patient" reference in the Claim resource will be replaced with a versioned reference showing the version ID of the Patient after the update.