I’ve said before that off-the-shelf FHIR servers are not production ready.
For real-world use they require customization, often by way of $operations that perform specific business logic.
How do you make it easy for consuming apps to talk to and understand your $operations?
You define input and output Parameters and you document them in detail the same way you document a Profile.
In a CapabilityStatement and in an Implementation Guide.
Start by defining the operation in an OperationDefinition resource. Then define and document the Parameters to be passed to the operation.
FHIR’s Parameters resource is a non-persisted resource (not saved to the FHIR server). It stores a list of key / value pairs and can accept any FHIR elements or resource types as values.
Let’s say you want to expose a service that changes a Patient’s name. You decide to build a FHIR operation as there’s a lot of custom logic to apply before you accept and process the name change.
You define a parameter list:
- patientIdentifier (Identifier)
- currentName (HumanName)
- newName (HumanName)
- reasonForChange (CodeableConcept)
- source (Provenance)
Here’s what this looks like for a sample patient:
https://server.fire.ly/Parameters/10d82c99-7e09-46a1-ac45-ebb3a13ce707?_format=json
A lot of information, but each piece has a role to play in how you might process the name change.
- You can clearly identify the patient via an MRN
- You can verify the current name
- You can verify that the new name is sufficiently complete
- You can see and document the reason for the change
- And You know who is sending the request
Based on this your code runs some FHIR queries and verifies that the patient exists and that the name change meets your criteria.
You then make the change, persist the information captured in the Provenance resource, and return a success code to the app making the request.
If required, you could define a set of output Parameters to return. Or you might choose to return an OperationOutcome or the updated Patient resource.
I’ve over simplified here, but you get the picture.
It’s your $operation, you define the inputs and the outputs.
As long as your operation is well documented there should be no ambiguity or uncertainty.
---