Subscription Components
Configuring a Subscription
The Subscription can be configured by following the sections below:
Subscription Metadata
Purpose of Subscription Metadata
🗒️Subscription Metadata is used to describe the subscription to other administrators using the iCDR solution
Subscription Metadata fields
🗒️Subscription Metadata fields are defined below:
Name
Text
- Any Lowercase Characters [a-z] - Uppercase Character [A-Z] - Any Number [0-9] - Hyphen [-] - Underscore [_]
A unique named identifier for the subscription which appear in logs
Description
Text
- Free Text (i.e. any regular or special case characters and numbers) - Limit of 1024 characters max
A short description of the subscription, its purpose, why it exists.
Support Contact
Text
- Free Text (i.e. any regular or special case characters and numbers)
The person who should be contact when/if the subscription fails (telephone, e-mail, etc.) This can be used for diagnosing connectivity
Subscription Filter
Purpose of Subscription Metadata
🗒️Subscription Filters help identify the criteria for what triggers a notification
Subscription Filter Fields
🗒️Subscription Filters fields can be defined below:
Applies To
Select
The resource which this subscription applies to
Event(s)
Checkbox
The persistence events when the recipient should be notified
When Criteria
Combination Fields(Text)
The filters for new events. These filters will be used as the criteria for if and when the recipient will be notified
Event(s) Input
What are Events?
🗒️Events are triggers that happen on data within the system, in reference to the Applies To field.
List of Available Events
🗒️The list of events can be described below:
Create
When new data is created in the system
Update
When existing data is updated within the system
Delete
When existing data is deleted within the system
Note: data is marked as deleted within the system. consider this a soft delete
Merge
When two or more data sets are merged as one within the system
Unmerge
When one data set is separated into two or more data sets within the system.
When Criteria Input
What is the When Criteria?
🗒️When Criteria is a text input that allows input for expressions to evaluate regarding the selected resource (defined in the Applies To field).
1️⃣This field can only take one expression for each input.
Syntax for When Criteria
📝When Criteria follows a particular format of: [Variable][Operator][Value]
Where:
Variableis a camel-case formatted string (e.g. genderConcept, mnemonic).Camel-case is writing style where multiple words are combined into a single word, with the first letter of each subsequent word capitalized, and the first letter of the first word is not be capitalized (e.g.
myNewWord)genderConcept.mnemonicfollows that format, except that every new property (denoted by the.) starts the format from the beginninganother example of this can be illustrated by
myObject.myProperty.myOtherProperty
Operatoris an operation evaluated on that variablee.g.:
=(equals),>(less than),<(greater than),<=(less than or equal),=!(does not equal),=:(variable expression)etc...
Valueis the result used for the evaluatione.g.:
Femaleis the value in thegenderConcept.mnemonic=Female, meaning the criteria for this notification will trigger when aPatientis created and their gender denoted is female
Examples
🏷️A few examples of When Criteria can be:
genderConcept.mnemonic=Femalea patient's gender is evaluated as female
dateOfBirth=:(age)<P10Ya patient's date of birth (in terms of age) is approximately less than 10 years old
Autocomplete in When Critera
🗒️When entering an expression, there is an autocomplete function that is triggered when you begin typing in the input.
⌨️The autocomplete popup will appear after 1 character has been entered by the user.
📝All options populated by the When Criteria input for autocomplete are in reference to the option selected in the Applies To field (i.e. the resource selected).
💼Lets say Patient was selected for the Applies To field. When the autocomplete popup appears, it should look similar to the image below
To illustrate a variable expression autocomplete, ensure that:
=:is providedbegin with a
(to populate the autocomplete popup.
💼In the example below, dateOfBirth=:( was provided as the input
(having Patient selected in the Applies To field):
Adding more expressions to When Critera
🗒️More expressions can be added by clicking the Add button (located in the bottom right hand corner of the control).
#️⃣There isn't a real limit to the amount of expressions added to the When Criteria input.
Deleting one or more expressions from When Critera
🗒️Sometimes, expressions are added and later not needed.
❌To remove and expression, simply click the X button to the right of the expression input
ℹ️Expressions can only be deleted if there are 2 or more expressions.
✅By default, one expression is required to save a Subscription.
Preventing Bouncing in When Critera
🗒️Sometimes the system notifies an external party regarding the registration of an event and the notified party will respond back with updates it would like to perform.
💼In this scenario, we do not want the the the admin portal to re-send the object back to the system which made the change.
ℹ️To prevent this behavior, filter the subscription based upon the principal/application by that last created version of the object.
Example
💼Lets say that we do not want want to receive notifications from an application that has the application name APP_THAT_SENDS_STUFF.
🙉This can help reduce the noise of extra notifications that might be redundant.
📝If the API key of the object has the target of the notification as APP_THAT_SENDS_STUFF, the pub/sub layer can be instructed to prevent sending any updates received by APP_THAT_SENDS_STUFFto the application:
ℹ️In the above example, an extra When Criteria can be added by using createdBy.application.name=!APP_THAT_SENDS_STUFF.
✅This achieves only sending notifications based upon the application name not being APP_THAT_SENDS_STUFF.
Endpoint Settings
What are Endpoint Settings
🗒️The endpoint settings are used to control how and when the messages are sent to the remote endpoint.
Endpoint Setting Fields
🚧The fields for Endpoint Settings can be defined below:
Not Before
DateTime
mm/dd/yyyy hh:mm ss
e.g. 01/31/2025 23:59 00
The date/time when the endpoint should start receiving messages from the iCDR
Not After
DateTime
mm/dd/yyyy hh:mm ss
e.g. 01/31/2025 23:59 00
The date/time when the endpoint should stop receiving messages from the iCDR
Endpoint
URL
[PROTOCOL]://[DOMAIN][URI]
e.g. http://ivd.go.elb/api/hpv-vaccine-cohort/Patient
The remote endpoint (url) where the notification dispatches should be sent
Dispatcher
Select
Option
e.g. fhir-message
The dispatching class to be used for formatting messages and authentication with the remote endpoint
Custom Settings
Key-Value Pair
[Key] [Value]
e.g. Authorization bearer mytoken123
Key/value pairs which are passed to the dispatcher to control settings related to authentication, message formatting, etc.
Available Dispatchers
📃Below is the available Dispatchers available in the system with their associating description and typical Custom Settings.
Dispatcher: fhir-message
fhir-message
Custom Settings
Please see the following table for applicable fhir-message Custom Settings:
Content-Type
application/fhir+xml
sends XML format messages
Content-Type
application/fhir+json
sends JSON format messages
MessageId
[ANY VALUE]
Controls the message identifier sent in the FHIR message
Dispatcher: fhir-rest-hook
fhir-rest-hook
Custom Settings
Please see the following table for applicable fhir-rest-hook Custom Settings:
Content-Type
application/fhir+xml
sends XML format messages
Content-Type
application/fhir+json
sends JSON format messages
Dispatcher: hl7-pat-id-source
hl7-pat-id-source
hl7-pat-id-source
Sends LLP messages to a remote HL7v2 receiver using ADT^A01 , ADT^A08 and ADT^A40 (optionally ADT^A38).
ADT Message Types
The ADT message types can be defined in short below:
ADT^A01→ New visit/admissionUse case: When a patient first comes under care at a facility (inpatient admission, outpatient registration, ER registration).
Example: John Doe arrives at the ER. Let the downstream systems (lab, radiology, billing) know a new visit has started
ADT^A08→ Update demographics/infoUse case: Patient demographics or other non-visit-specific info has changed.
Example: Patient moves to a new address or corrects their date of birth
ADT^A40→ Merge patientsUse case: Two patient records have been found to actually be the same person; one ID becomes the primary and the other is retired.
Example: A patient registered once as John A. Doe (
ID 123) and later as John Doe (ID 456). When hospital staff realize they’re the same person, they mergeID 456intoID 123further consolidating John A. Doe's 2 separate records into one.
ADT^A38→ Cancel pre-admission (optional)Use case: A pre-admission (planned future admission) was scheduled, but is now cancelled.
Example: A patient was scheduled for surgery next week (pre-admitted), but the procedure was cancelled. Clean up the pre-admission.
Custom Settings
Please see the following table for applicable hl7-pat-id-source Custom Settings:
MSH8
String
The MSH8 security setting to be used
Transport
sllp
to use secure LLP
Transport
llp
to use unsecure LLP
MSH34
String
The MSH3 | MSH4 to send (default is the SanteDB server's)
MSH-3: A unique name or code for the sending application/service/device (EHR, LIS, RIS, ADT system, etc.).
MSH-4: A unique name or code for the sending facility/location (hospital name, site ID, clinic code).
SendAs
Client
sends as ADT^A01, ADT^A08, or ADT^A40 messages
SendAs
Server
sends as ADT^A38 messages
Authenticator Flows
Authenticator Flow Custom Settings
This section applies when using HL7 FHIR integrators/dispatchers.
✅To enable this with any of the above FHIR dispatchers, add the following properties to your channel configuration:
$authenticationProvider
oauth
Sets the authentication provider to OAUTH
$oauth.server
URL
The base URL to the OAUTH server.
The provider will use this value and attempt to obtain the .well-known/openid-configurationfile from the path
$oauth.client_id
String
The client identifier to pass in all requests
$oauth.client_secret
String
The client secret to use on the OAUTH server
$oauth.grant_type
password or client_credentials
The grant type to use for the issuing of requests to the server. This is how the sending SanteDB server authenticates itself to the remote
$oauth.username
String
The username to authenticate with.
Note:
Works when $oauth.grant_type is set to password
$oauth.password
String
The password to authenticate with.
Note:
Works when $oauth.grant_type is set to password
$oauth.scope
String
The scope names which the SanteDB server should request when sending data to the server.
$oauth.novalidate
True or False
True: the issuing SanteDB server will not attempt to validate the token passed back from the issuing server. False: the issuing SanteDB server will attempt to validate the token passed back from the issuing server.
Last updated