# Pub/Sub Manager

The Pub/Sub manager allows administrators to control the [publish-subscribe-architecture](https://help.santesuite.org/santedb/software-architecture/publish-subscribe-architecture "mention")subscriptions registered in the iCDR instance. 

## Subscription List

The publish/subscribe manager shows a list of all registered subscriptions. This view allows administrators to quickly enable or disable outbound subscriptions from the iCDR or dCDR instance.

![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2F7styUdsK1qrmx8bbiaT3%2Fimage.png?alt=media\&token=01607c42-82df-42ee-8b34-58f98696bf61)

The commands on this screen:

* Create - Allows administrators to create new subscription definitions with the related endpoint information.
* Edit - Change the settings of an already registered subscription definition.
* Enable / Disable - When a subscription is active, it is sending data out to the configured endpoints, when the subscription is inactive the subscription is registered, but will not send notifications. The enable/disable button permits the administrator to change this setting.
* Delete / Un-Delete - Allows an administrator to remove a subscription, and to restore it.

### Re-Processing Subscriptions

The pub/sub infrastructure in SanteDB relies on real-time monitoring of the dispatcher queue setup for the subscription. 

There are occasions where data may not have been dispatched from the CDR to the subscriber such as:

* The subscription has been disabled by an administrator for a period of time
* The subscription was created after data already existed in the CDR
* The subscription criteria has changed

In this case, there may be a need to re-process the subscription. When re-processing the subscription, the subscription criteria for the specified filter will be applied against all objects in the CDR and placed into the outbound dispatcher queue for the subscription.

## Creating/Editing a Subscription

When creating a subscription the administrator will be prompted to enter settings related to the subscription which is being created.

### Subscription Metadata

Subscription metadata is used to describe the subscription to other administrators using the iCDR solution.

![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2F3XnXhEpSZZbolluXz6qM%2Fimage.png?alt=media\&token=4df0d629-d92e-483f-af22-86729c9bc831)

* Name - A unique named identifier for the subscription which appear in logs
* Description - A short description of the subscription, its purpose, why it exists.
* Support Contact - The person who should be contact when/if the subscription fails.

### Subscription Filter

Next, administrators should specify the criteria under which the notification is triggered. 

![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2F5DyX3CgyIEKuybfw69Re%2Fimage.png?alt=media\&token=8d2fa660-1fe9-4b57-9da6-49b497e3bdfd)

* Applies To - The resource which this subscription applies to
* Event(s) - The persistence events when the recipient should be notified
* When Criteria - The filters for new events which should be applied when new data is received. These dictate when the recipient will be notified.

#### Preventing Bouncing

Sometimes when a SanteDB product notifies an external party of a registration of an event, the notified party will respond back with updates it would like to perform. In this scenario, we do not want the SanteDB server to re-send the object back to the system which made the change. 

To prevent this behavior, filter the subscription based on the principal/application that last created the version of the object. For example, if the API key of the object which is the target of the notification is `APP_THAT_SENDS_STUFF`we can instruct the pub/sub layer to prevent sending any updates received by `APP_THAT_SENDS_STUFF`to the application:

<figure><img src="https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FU5X9OA1FbXaGQO2XreHe%2Fimage.png?alt=media&#x26;token=ddf2feec-54d2-4c4f-a6ad-738060703935" alt=""><figcaption></figcaption></figure>

### Endpoint Settings

The endpoint settings are used to control how and when the messages are sent to the remote endpoint.&#x20;

![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FFKaRoOscrUCb0FRu2BTG%2Fimage.png?alt=media\&token=5260d9f3-9911-474b-aece-329e1485dc7a)

* Not Before - The date/time when the endpoint should start receiving messages from the iCDR
* Not After - The date/time when the endpoint should stop receiving messages from the iCDR
* Endpoint - The remote endpoint (url) where the notification dispatches should be sent
* Dispatcher - The dispatching class to be used for formatting messages and authentication with the remote endpoint.
* Custom Settings - Key/value pairs which are passed to the dispatcher to control settings related to authentication, message formatting, etc.

#### Dispatchers

| fhir-message                    | Send messages using FHIR messaging (a message bundle with content)                                     | <ul><li>Content-Type - Controls the format with <code>application/fhir+xml</code> sending XML format messages and <code>application/fhir+json</code> sending JSON</li><li>MessageId - Controls the message identifier sent in the FHIR message</li></ul> |                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| fhir-rest-hook                  | Send messages using FHIR REST operations such as POST, PUT, DELETE.                                    | <ul><li>Content-Type - Controls the format with <code>application/fhir+xml</code> sending XML format messages and <code>application/fhir+json</code> sending JSON</li></ul>                                                                              |                                                                                                                                                                                      |
| hl7-pat-id-source (SanteDB 3.x) | Sends LLP messages to a remote HL7v2 receiver using ADT^A01 , ADT^A08 and ADT^A40 (optionally ADT^A38) | <ul><li>MSH8 - The MSH8 security setting to be used</li><li>Transport - <code>sllp</code> to use secure LLP and <code>llp</code> to use unsecure llp</li><li>MSH34 - The MSH3                                                                            | MSH4 to send (default is the SanteDB server's)</li><li>SendAs - <code>Client</code> if sending ADT^A01, ADT^A08, ADT^A40 messages, or <code>Server</code> if using ADT^A38</li></ul> |

## Authenticator Flows

The HL7 FHIR integrators can leverage a dispatch authenticator implementing a `IFhirClientAuthenticator`implementation. By default, SanteDB ships with an OAUTH authenticator which allows the FHIR dispatcher to reach out to an OAUTH service to obtain a token prior to issuing the FHIR message request. To enable this, add the following properties to your channel configuration

| Setting                   | Value                             | Description                                                                                                                                       |
| ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$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-configuration`file 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                            | When using a password grant, the username to authenticate as.                                                                                     |
| `$oauth.password`         | String                            | When using a password grant, the password to authenticate as.                                                                                     |
| `$oauth.scope`            | String                            | The scope names which the SanteDB server should request when sending data to the server.                                                          |
| `$oauth.novalidate`       | True or False                     | When set to True the issuing SanteDB server will not attempt to validate the token passed back from the issuing server.                           |

## Additional Subscription Settings

<table><thead><tr><th width="226">Setting</th><th width="119">Value</th><th width="155">Dispatcher</th><th>Description</th></tr></thead><tbody><tr><td><code>notify.local</code></td><td>Boolean</td><td>fhir-message<br>fhir-rest-hook</td><td>When true, instructs a SanteDB server to call the data management pattern to dispatch a local copy of the record in question rather than the golden or master record.</td></tr><tr><td><code>notify.bundle</code></td><td>Boolean</td><td>fhir-rest-hook</td><td>When true, indicates that the rest hook should send the notifications as a FHIR transaction bundle including sending data which is related to the focus object in the bundle.</td></tr><tr><td><code>notify.includeMetaData</code></td><td>Boolean</td><td>fhir-rest-hook</td><td>When true, instructs the rest hook to include all CDR metadata (MDM info, system tags, etc.) in the message. By default SanteDB will not send this information to the remote service.</td></tr><tr><td><code>linkAsMerge</code></td><td>Boolean</td><td>fhir-message<br>fhir-rest-hook</td><td>When true, whenever a link/unlink of data is perform (i.e. replaces in the case of MDM) the notification is sent as a merge trigger.</td></tr></tbody></table>

## Related Topics

{% content-ref url="../../../../developers/service-apis/hl7-fhir/santedb-fhir-implementation/publish-subscribe" %}
[publish-subscribe](https://help.santesuite.org/developers/service-apis/hl7-fhir/santedb-fhir-implementation/publish-subscribe)
{% endcontent-ref %}

{% content-ref url="dispatcher-queue" %}
[dispatcher-queue](https://help.santesuite.org/operations/cdr-administration/santedb-administration-panel/system-administration/dispatcher-queue)
{% endcontent-ref %}