By: Amos (Kippi) Bordowitz
Let us imagine a patient who visits a hospital outpatient clinic. Said patient is then handed a prescription for an expensive medicine. For the medicine to be supplied by another medical body, they must get a reference for the practitioner who wrote the prescription. A classic Reference in FHIR requires a URL which includes the server-specific logical-ID of the resource. The problem is that the resource’s ID on the target server is not always known to the client.
The classical solution is to run a search on the target server in order to find the practitioner’s resource according to, for example, a business identifier. Once we have that we can then go on to and create a Reference.
If the query returns a matching resource we can use it for the Reference, otherwise, a new Practitioner resource must be created.
In order to prevent this complicated route, is there a way to do all the above in a single transaction?
The answer is yes, using Conditional-create and Conditional-reference
Conditional create –
Can be used in two variations:
- When one wishes to perform an atomic POST. In order to achieve this, you must use the header “If-None-Exist”. The parameter just contains the search parameters (what would be in the URL following the “?”).
According to the specs: “When the server processes this create, it performs a search as specified using its standard search facilities for the resource type. The action it takes depends on how many matches are found:
- No matches: The server processes the create as above
- One Match: The server ignores the post and returns 200OK
- Multiple matches: The server returns a 412 Precondition Failed error indicating the client’s criteria were not selective enough”
Example: The practitioner’s id is 123 so we will enter into the header: identifier=https://outburn.health/PractitionerID|123
- As part of a transaction Bundle. Each entry in the “request” field has its own “ifNoneExist” field, in which one enters the same thing we showed in the header example. If the resource exists it will return 200 OK, otherwise it will create the resource and return 201 created.
If we don’t use the “ifNoneExist” field, the server might create the same resource repeatedly, creating duplications. If the server enforces duplication prevention, the entire transaction will fail.
Conditional Reference –
Now we need a way to point to the Practitioner resource from within the transaction Bundle, without knowing the actual Reference. This is where the Conditional Reference comes in handy.
In the Reference we enter something very close to what we saw in the previous section, the only difference is that here we prefix the query with the Resource type and the “?”. In our case:
Practitioner/?identifier=https://outburn.health/PractitionerID|123
Important – this will only work if the query produces a single result, otherwise the process will fail. Assuming everything worked correctly, we will see in the created resource that it is now pointing at the resource which was either found or created during the transaction.
Disclaimer:
Both of these features are currently designated as “Trial use” so not all servers will support them.