Transaction Bundle: an SLS API Interface
- 5 minsAs an essential component in the implementation of a data segmentation for privacy (DS4P) ecosystem, the security labeling service (SLS) provides the capability to identify and mark sensitive data by assigning security labels. The labels can later be used for various purposes like fine-grained access control (e.g., based on a patient consent).
The SLS needs to provide an API interface through which the client can submit the data and receive either the labels or labeled data. There is currently no standard specification for such an API interface, but this is scoped to be part of the upcoming update to the FHIR DS4P Implementation Guide.
I previously wrote about using CDS Hooks as a possible standard but as my implementation revealed (and as the feedback from the community confirmed) that does not seem to be a suitable API interface for communicating with the SLS. Defining a FHIR Operation for this purpose seems to be a more appropriate approach for this use case. This will be included in the next update to the FHIR DS4P IG, I am planning to work on this year.
As part of my work with SHIFT, I separated the SLS capabilities from the LEAP Consent Decision Service into a separate service, LEAP FHIR SLS. The interface is currently a simple API that accepts a FHIR Bundle and returns a Bundle with the same resources but labeled.
This interface suits the use cases where the labeling takes place on the fly within the context of an exchange transaction. The transaction orchestrator, or the access control system, can submit the outgoing response bundle to the SLS, receive the labeled resources in the response bundle, and send it to the recipient —or the next stage of the transaction fulfillment workflow, for example, a redaction service to enforce policies like those expressed in a consent, as shown in a sample architecture below (which also aligns with the model I implemented in the LEAP FHIR Hearth project).
This API interface is, however, not optimal for the use case where the data must be labeled at rest, for example, batch-labeling data in an EHR. In this use case, an orchestrator has to submit a bundle of data (scheduled for labeling based on some event, such as newly-created or or bulk-imported resources) to the SLS. If the orchestrator receives the bundle of labeled data in response, it will have to figure out which resources in the bundle were updated with new labels and then invoke the logic to update those resources in the original data source to incorporate the new labels.
It is much more efficient if the SLS can provide a response that is more readily consumable by the orchestrator in this case. FHIR has specific operations for changing the metadata of a resource, $meta-add and $meta-delete. These operations enable changing the security labels, without having to update the entirety of the resource.
Aside from needing a much smaller payload, these operations also make it possible for the FHIR server to control access to resources in a more granular way, by granting a client access to update the metadata of a resource without necessarily allowing changes to its content.
Using these operations, the SLS can produce a response in the form of a FHIR transaction containing FHIR operations to update the labels. This simplifies the orchestrator logic by enabling the orchestrator to simply relay this transaction to the FHIR server to label the data.
This also leads to a much more concise response from the SLS; for example, if there are 50 resources in the SLS request bundle and only 5 of them are sensitive, the SLS response will only contain 5 update operations. Moreover, the resource contents are not echoed back in the response.
An example of this use case is batch labeling of data at rest shown in the following sample architecture. The batch orchestrator retrieves the data scheduled to be labeled (based on a labeling queue) and submits the bundle to the SLS. The response from the SLS, which is a transaction bundle is then submitted to the FHIR server by the orchestrator.
The labeling queue may be filled based on external events but also based on the events within the FHIR server, such as creating or updating resources. If the FHIR server supports FHIR subscriptions, they can be leveraged to use these events to schedule resources for labeling.
To support both of these use cases, I implemented a new endpoint in the LEAP FHIR SLS to support this mode. The following is a sample response from this endpoint:
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "Observation/1001/$meta-add",
"resource": {
"resourceType": "Parameters",
"parameter": [
{
"name": "meta",
"valueMeta": {
"security": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "SUD",
"display": "substance use disorder information sensitivity"
},
{
"system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code": "R",
"display": "restricted",
"extension": [
{
"url": "http://hl7.org/fhir/uv/security-label-ds4p/StructureDefinition/extension-sec-label-basis",
"valueCoding": {
"code": "42CFRPart2",
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"display": "42 CFR Part2"
}
},
{
"url": "http://hl7.org/fhir/uv/security-label-ds4p/StructureDefinition/extension-sec-label-classifier",
"valueReference": {
"display": "LEAP+ Security Labeling Service"
}
}
]
}
]
}
}
]
},
"request": {
"method": "POST",
"url": "Observation/f204/$meta-add"
}
}
]
}