On this page:

6.3Delivery Options

 

This page outlines various options that can be used to control how notification delivery works.

6.3.1Payload Search Result Mode

 
This feature applies to REST HOOK subscriptions only.

By default, the REST HOOK Subscription delivery involves performing an HTTP PUT (FHIR update) operation where the payload is the individual resource that triggered the subscription (i.e. the resource will be of the type that was identified by the Subscription criteria).

Some scenarios require the delivery of a collection of resources as a Bundle to the target server. When Payload Search Result Mode is used, the REST HOOK delivery module will perform a search using user-defined criteria and then delivers the results of the search as a FHIR Transaction operation.

To enable Payload Search Result Mode, an extension is added to the Subscription resource with the following URL:

NameURLTypeDescription
Payload Search Criteria string The value to this extension is a string containing a FHIR search expression (i.e. a URL fragment without the base URL portion, as shown in the example below). It may contain the following substitutions:
  • ${matched_resource_id} – Will be replaced with the relative ID of the resource that matched the subscription.

The example below shows a sample Subscription configured to use Payload Search Result Mode. This subscription has a criteria of Observation?, meaning it will match all Observations.

{
  "resourceType": "Subscription",
  "extension": [ {
    "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-payload-search-criteria",
    "valueString": "Observation?_id=${matched_resource_id}&_include=*"
  } ],
  "status": "requested",
  "criteria": "Observation?",
  "channel": {
    "type": "rest-hook",
    "endpoint": "http://example.com/baseR4",
    "payload": "application/fhir+json"
  }
}

When using this mode, a transaction bundle resembling the following example will be POSTed to the base URL of the FHIR server (ie. the endpoint configured in the Subscription resource) per the FHIR transaction operation semantics.

{
  "resourceType": "Bundle",
  "id": "6a5be3a8-04d0-4c9a-b179-161fced75ab7",
  "type": "transaction",
  "entry": [ {
    "fullUrl": "Observation/3/_history/1",
    "resource": {
      "resourceType": "Observation",
      "id": "3",
      "meta": {
        "versionId": "1",
        "lastUpdated": "2020-06-29T18:08:18.729-04:00",
      },
      "subject": {
        "reference": "Patient/2"
      }
    },
    "request": {
      "method": "PUT",
      "url": "Observation/3"
    }
  }, {
    "fullUrl": "Patient/2/_history/1",
    "resource": {
      "resourceType": "Patient",
      "id": "2",
      "meta": {
        "versionId": "1",
        "lastUpdated": "2020-06-29T18:08:18.701-04:00",
      },
      "active": true
    },
    "request": {
      "method": "PUT",
      "url": "Patient/2"
    }
  } ]
}

6.3.2Replication Mode

 
This feature applies to REST HOOK subscriptions only.

In replication mode, Smile CDR assumes that it is replicating all matching resources from one Smile CDR instance to another Smile CDR instance. This allows the server to make assumptions about how operations may be batched and sequenced. The following Subscription example shows a replication subscription:

{
  "resourceType": "Subscription",
  "status": "active",
  "reason": "Monitor new neonatal function (note, age will be determined by the monitor)",
  "criteria": "Observation?code=SNOMED-CT|1000000050",
  "channel": {
    "extension": [
      {
        "url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-replicate-mode",
        "valueBoolean": true
      },
      {
        "url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-replicate-id-prefix",
        "valueString": "CDR1-"
      }
    ],
    "type": "rest-hook",
    "endpoint": "http://localhost:40243/fhir/context",
    "payload": "application/json"
  }
}

When running in replication mode, the following extensions may be used.

NameURLTypeDescription
Enable Replication Mode boolean If set to true, this subscription will be delivered in replication mode.
Add ID Prefixes string If specified, all resource IDs (or a specific set of resource IDs if the selector property below is also set) will be prefixed with the given prefix (both in IDs, and in references to those IDs from other resources). This is useful in situations where you want to be able to replicate data from several source CDR instances to one target CDR instance, or in cases where the source CDR instance is using numeric IDs (since Smile CDR will not allow client-provided numeric IDs).
Add ID Prefixes - Selector string If specified, only resource IDs matching the given pattern will have a prefix appended. The format of the pattern is a regular expresion and the pattern must match the entire string including the resource type and the ID part. For example, the following pattern will match all purely numeric IDs but will not prefix any IDs with non-numeric characters in them: `[a-zA-Z]+/[0-9]+`
Strip ID Prefixes string If specified, all resource IDs will have the specified prefix removed from any resource IDs and references that are found within resources being delivered. This is helpful when subscriptions need to be delivered from a server that uses prefixes to a server that does not. For example, this could be used when delivering resources from a server that was populated by a subscription that uses the Add ID Prefixes on its own Subscription.
Strip ID Base URLs string If specified, all references containing this base URL will have the base URL removed prior to delivery.

If the replication is being sent to a second Smile CDR instance, you may wish to enable the dao_config.auto_create_placeholder_reference_targets.enabled configuration property on the replication target persistence module. This means that if payloads are received out-of-order by the receiving system, no payload will be rejected simply because it contains a reference to a resource that has not yet been received.

6.3.3Strip Version IDs

 
This feature applies to REST HOOK subscriptions only.

By default, the resource version ID is included when delivering a resource to the REST HOOK receiving endpoint. This can be disabled using an extension on the REST HOOK channel.

{
  "resourceType": "Subscription",
  "status": "active",
  "reason": "Monitor new neonatal function (note, age will be determined by the monitor)",
  "criteria": "Observation?code=SNOMED-CT|1000000050",
  "channel": {
    "extension": [
      {
        "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-resthook-strip-version-ids",
        "valueBoolean": true
      }
    ],
    "type": "rest-hook",
    "endpoint": "http://localhost:40243/fhir/context",
    "payload": "application/json"
  }
}

Note the following extension:

URLTypeDescription
http://hapifhir.io/fhir/StructureDefinition/subscription-resthook-strip-version-ids boolean If set to true, the deliverer will strip the resource version ID before sending the resource

6.3.4Delivering Latest Version

 
This feature applies to REST HOOK subscriptions only.

By default if a resource is created and then updated in rapid succession, the deliverer will deliver versions 1 and 2 to the REST HOOK target.

This can be adjusted so that if the resource gets updated before the deliverer manages to transmit the resource, only the latest version will be transmitted (and it may be delivered more than once).

{
  "resourceType": "Subscription",
  "status": "active",
  "reason": "Monitor new neonatal function (note, age will be determined by the monitor)",
  "criteria": "Observation?code=SNOMED-CT|1000000050",
  "channel": {
    "extension": [
      {
        "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-resthook-deliver-latest-version",
        "valueBoolean": true
      }
    ],
    "type": "rest-hook",
    "endpoint": "http://localhost:40243/fhir/context",
    "payload": "application/json"
  }
}

Note the following extension:

URLTypeDescription
http://hapifhir.io/fhir/StructureDefinition/subscription-resthook-deliver-latest-version boolean If set to true, the deliverer will attempt to send only the latest version of a resource.

6.3.5Custom Delivery Class

 
This feature applies to REST HOOK subscriptions only.

Users may also supply a custom Java class that will be used to deliver the resource instead of the built-in FHIR client. This is useful in cases where you want to customize the delivery (e.g. by adding special attributes or filters, or by using another protocol altogether instead of FHIR/REST).

The following example shows a subscription that uses a custom delivery class:

{
  "resourceType": "Subscription",
  "id": "1",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2017-08-19T16:52:11.041-04:00"
  },
  "status": "active",
  "reason": "Monitor new neonatal function (note, age will be determined by the monitor)",
  "criteria": "Observation?code=SNOMED-CT|1000000050&_format=xml",
  "channel": {
    "extension": [
      {
        "url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-delivery-class",
        "valueString": "org.example.ExampleDeliverer"
      }
    ],
    "type": "rest-hook",
    "payload": "application/json",
    "header": [
      "Authorization: Bearer 123"
    ]
  }
}

Note the following extension:

URLTypeDescription
https://smilecdr.com/fhir/ns/StructureDefinition/subscription-channel-rest-delivery-class string This is the class name for the Java class that implements the ISubscriptionDeliverer interface.

The following example shows a simple delivery class:

package org.example;

public class ExampleDeliverer implements ISubscriptionDeliverer {

	private Logger ourLog = LoggerFactory.getLogger(ExampleDeliverer.class);

	/**
	 * Deliver the resource
	 *
	 * @param theOperation    The operation triggering this delivery
	 * @param theSubscription The subscription
	 * @param theResource     The resource
	 */
	@Override
	public void deliver(RestOperationTypeEnum theOperation, IBaseResource theSubscription, IBaseResource theResource) {

		// We will just log the resource; however, we would probably send it somewhere in a real scenario
		String id = theResource.getIdElement().getValue();
		ourLog.info("REST delivery type {} for resource {}", theOperation, id);

	}

}

6.3.6Delivery to Site-defined External Queue

 
This feature applies to REST HOOK subscriptions only.

Related to the custom delivery class, users may alternatively choose to have the resource delivered to a queue or topic in the Message Broker defined and managed separately from Smile CDR. This is useful in cases where you want to be able to retrieve resources directly off of a message queue or topic or if you have a custom handler defined in your Message Broker to manage delivery.

The following example shows a subscription that uses a site-defined external topic or queue:

{
  "resourceType": "Subscription",
  "id": "1",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2017-08-19T16:52:11.041-04:00"
  },
  "status": "active",
  "reason": "Monitor new neonatal function (note, age will be determined by the monitor)",
  "criteria": "Observation?code=SNOMED-CT|1000000050&_format=xml",
  "channel": {
    "extension": [
      {
        "url": "https://smilecdr.com/fhir/ns/StructureDefinition/subscription-named-channel-delivery",
        "valueString": "MyQueueName"
      }
    ],
    "type": "rest-hook",
    "endpoint": "http://localhost:40243/fhir/context",
    "payload": "application/json",
    "header": [
      "Authorization: Bearer 123"
    ]
  }
}

Note the following extension:

URLTypeDescription
https://smilecdr.com/fhir/ns/StructureDefinition/subscription-named-channel-delivery string This is the name for the external message queue or topic that resources will be copied to.