# Pub/Sub

## Overview

The Pub/Sub framework enables messages about various events to flow from your Verato instance to downstream systems. One MDM Cloud instance can send messages to one or more downstream systems, and that message stream can be filtered on one or more criteria, and formatted with one or more Smart Views. The Pub/Sub framework is designed to be flexible and extensible, so that it can support a wide variety of use cases.

There are two categories of events, each with their own message format, that can be sent over Pub/Sub:

1. Identity Events - updates to Identities that occur due to API calls.
2. Notifications - updates to records caused by API requests and other identity-changing activity, such as data stewardship. They use the same message format returned by the [`searchNotifications` API](/apis/person.openapi/other/post_searchnotifications)


## Architecture

The architecture diagram below shows the end-to-end Pub/Sub flow:

- API calls to the Verato MDM Cloud are events that generate messages that are sent to the Pub/Sub system.
- The Pub/Sub services handle filtering and delivery of messages to customer's downstream systems.
- Messages are sent to downstream systems via HTTP POST, and the message is sent as a JSON payload in the body of the request.


```mermaid
flowchart LR
    UP["<b>Customer<br/>Upstream<br/>System</b>"]
    MDM["<b>Verato</b><br/>MDM Cloud"]
    PS["<b>Pub/Sub</b>"]
    FILTER{{"filter"}}
    DOWN["<b>Customer<br/>Downstream<br/>Systems</b><br/><small>Salesforce, TIBCO, etc.</small>"]

    UP -- HTTP --> MDM
    MDM ---> PS
    PS --> FILTER
    FILTER -- HTTP --> DOWN

    classDef endpoint fill:#B5379E,stroke:none,color:#fff
    classDef verato fill:#0F2043,stroke:none,color:#fff
    classDef neutral fill:#fff,stroke:#0F2043,stroke-width:2px,color:#0F2043
    classDef filt fill:#4CBB87,stroke:none,color:#0F2043

    class UP,DOWN endpoint
    class MDM,CP,PS verato
    class CONF neutral
    class FILTER filt
```

## Filtering

An entire Pub/Sub messages can be filtered in or out. That is, based on a set of criteria, a message can be included or excluded from delivery. The message itself is not altered.

A filter is made up of one or more criteria, and each criterion is a function (e.g., equals, not equals, contains, etc.) applied to a field in the message (e.g., source name, DOB, City, Zip code, etc.).

Different criteria can be combined using logical operators such as AND and OR to create more complex filters.

Work with your Customer Service representative to set up filters for your Pub/Sub messages.

## Delivery via HTTP

Pub/Sub messages are delivered to downstream systems via HTTP POST. The message is sent as a JSON payload in the body of the request.

### Authorization

There are three supported authorization methods for HTTP delivery:

- OAuth 2.0 Client Credentials flow, with client ID and client secret (preferred)
- HTTP Header Authorization where headers named `client_id` and `client_secret` are set with the client ID and client secret values.
- HTTP Basic Auth


Work with your Customer Service representative to set up the authorization method for your Pub/Sub Configurations.

## Message Formats

There are two mutually exclusive message formats that can be sent over Pub/Sub:

- Identity Events - this format includes demographics information, it can include the so called "trigger identity", the resulting identity or any Smart View projection thereof.
- Notifications - this format includes the source and native ID information, and does not include demographics. This message format is the same as returned by the `searchNotifications` service.


### Identity Events

#### Smart Views

The format of the Identity in the message can be controlled by the Smart View that is applied to the Pub/Sub Configuration. Multiple Smart Views can be sent in a single message.

Work with your Customer Service representative to set up Smart Views for your Pub/Sub messages.