LiveBundle API
Once LiveBundle rules have been configured and enabled on a FHIR Storage module, all FHIR Endpoints attached to that module will accept LiveBundle Operations.
Each Watchlist has a set of resource ids for which Smile CDR stores LiveBundles. The type of these resource ids is the subscriberType of that Watchlist. A subscriber id is added to a watchlist using the $livebundle-watchlist-add operation on the Composition resource.
For example, to add Patient/123 to http://myorg.org/diabetes_management|PATIENT_WATCHLIST, call:
POST [base]/Composition/$livebundle-watchlist-add
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [ {
"name": "watchlist",
"valueCoding": {
"system": "http://myorg.org/diabetes_management",
"code": "PATIENT_WATCHLIST"
}
}, {
"name": "subscriber",
"valueString": "Patient/123"
} ]
}
Watchlist subscribers can be grouped into Subscriber Groups. You add a subscriber to a subscriber group using the $livebundle-group-add operation. Similarly, subscribers are removed from subscriber groups with the $livebundle-group-remove operation.
A subscriberGroup can be used in place of a list of subscriberIds when requesting a liveBundle.
Here is what a request looks like that adds a subscriber to a subscriberGroup:
POST [base]/Composition/$livebundle-group-add
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [ {
"name": "subscriber",
"valueString": "Patient/123"
}, {
"name": "subscriberGroup",
"valueString": "New mothers"
} ]
}
Here is what a request looks like that removes a subscriber from a subscriberGroup:
POST [base]/Composition/$livebundle-group-delete
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [ {
"name": "subscriber",
"valueString": "Patient/123"
}, {
"name": "subscriberGroup",
"valueString": "New mothers"
} ]
}
A common example for a subscriberGroup is to set the subscriberGroup to an organization id so that bundle data can be pulled for all subscribers from that organization at once.
A Subscriber is removed from the watchlist using the $livebundle-watchlist-delete operation on the Composition resource:
POST [base]/Composition/$livebundle-watchlist-delete
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [ {
"name": "watchlist",
"valueCoding": {
"system": "http://myorg.org/diabetes_management",
"code": "PATIENT_WATCHLIST"
}
}, {
"name": "subscriber",
"valueString": "Patient/123"
} ]
}
When a subscriber is removed from a watchlist, if the subscriber was a part of any subscriberGroups, then when the subscriber is removed from the last watchlist it was a part of, it will be removed from all of its subscriberGroups.
To obtain a list of Subscribers to a Watchlist, use the $livebundle-watchlist command:
GET [base]/Composition/$livebundle-watchlist?watchlist=http://myorg.org/diabetes_management|PATIENT_WATCHLIST
This will return a List resource with references to the Subscribers to that Watchlist.
Alternatively, you can request by subscriberGroup as follows:
GET [base]/Composition/$livebundle-watchlist?subscriberGroup=New+mothers
This will return a List resource with references to the Subscribers in that subscriberGroup.
It is also possible to request by multiple subscriber groups:
GET [base]/Composition/$livebundle-watchlist?subscriberGroup=New+mothers&subscriberGroup=New+father
The $livebundle-watchlist-subscribers operation takes the same parameters as $livebundle-watchlist but instead of returning a List object, it returns a bundle that includes the List object followed by each subscriber resource. E.g. If a watchlist had two Patient subscribers, this bundle would return three resources: a List referencing these two patients followed by two Patient resources.
The $livebundle-watchlist-subscribers supports the _include and _include:recurse parameters. References to included resources are not added to the List (since the list is strictly the list of subscribers). The included resources are added after each subscriber resource it is included from.
The $livebundle-reseed operation removes all bundles for the named rule and reseeds the bundles for that rule for all subscribers on that rule's watchlist. This is often required after a rule definition has changed.
POST [base]/Composition/$livebundle-reseed
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [ {
"name": "rule",
"valueString": "http://myorg.org/diabetes_management|LAST_VISIT"
} ]
}
Once subscribers have been added to a Watchlist, the server will begin aggregating data for all rules that use that Watchlist. Request the aggregated data for a SubscriberId and a Rule by calling the $livebundle operation on the Composition resource.
GET [base]/Composition/$livebundle?rule=http://myorg.org/diabetes_management|LAST_VISIT&subscriberId=Patient/123
Multiple subscriberIds can be requested. In this case, a separate composition will be returned for each subscriberId followed by the resources referred to in those compositions.
GET [base]/Composition/$livebundle?rule=http://myorg.org/diabetes_management|LAST_VISIT&subscriberId=Patient/123,Patient/456
You request a LiveBundle for all subscribers in a subscriberGroup as follows:
GET [base]/Composition/$livebundle?rule=http://myorg.org/diabetes_management|LAST_VISIT&subscriberGroup=New+mothers
You request a LiveBundle for all subscribers in more than one group as follows:
GET [base]/Composition/$livebundle?rule=http://myorg.org/diabetes_management|LAST_VISIT&subscriberGroup=New+mothers&subscriberGroup=New+fathers
The $livebundle operation returns a Bundle of that rule’s aggregated resources for all subscriberId requested. The first entries in the bundle are Compositions for each subscriberId that references resources for that subscriberId. These Composition resources are then followed by the union of all the references in the Compositions.
The _include and _include:recurse parameters are supported on this operation. E.g. if the LAST_VISIT rule stored Encounter resources, you could also include the associated Condition resources by calling:
GET [base]/Composition/$livebundle?rule=http://myorg.org/diabetes_management|LAST_VISIT&subscriberId=Patient/123&_include=Encounter:condition
Two sort parameters are supported for livebundle: _sort=date which sorts results by date from earliest to latest and _sort=-date sorts results from latest to earliest by date. Root resources are sorted based on the keeper pathToOrderDate. Other resources stored in the LiveBundle or added with _include follow the root resources they are associated with.