Notifications¶

Whenever an entity in the CAS system is created, updated or deleted, a notification event is produced so that interested parties can react to this event. Currently these events are available over a web-socket connection, but future releases will provide the ability to receive notifications via guaranteed delivery mechanisms.

Websocket Gateway¶

The websocket gateway provides an endpoint to open a persistent websocket connection between the CAS system and the consumer. You can then subscribe to one or more channels that will route different event types so that you can subscribe to only the notifications that you require.

It is important to note that you will only ever receive notifications for entities that you have read access to, and conversely no other consumers will receive notifications about your data unless you have explicitly shared it. See Data Storage and Access for further details.

Urls¶

The websocket gateway URLs for the UAT and Production environments are shown below:

UAT	wss://gateway.staging.sockets.ipreo.com/connect?authType=CAS&authEnv=UAT
Production	wss://gateway.sockets.ipreo.com/connect?authType=CAS&authEnv=PROD

Authentication¶

The websocket endpoints are protected using the same bearer tokens as discussed in Authentication. In order to connect to a websocket notification channel you should create a bearer token just the same as when calling a REST api endpoint, but instead of passing it as a header, it will be passed in as a querystring parameter called token.

For example, a fully authenticated call to the UAT websocket gateway could look like:

wss://gateway.staging.sockets.ipreo.com/connect?authType=CAS&authEnv=UAT&token=qwe234252fsdf23f24f43i6IkpXVCJ.ey9JjiaXByZW8tYWxlasdnRzIiwic3ViIjoicG9sYXJpcy1kZW1vQGlwcmVvLmNvbSP-TndQDECj8

In order to access notification events, it is required to have the sockets-read scope in the access token.

Subscribing¶

Once successfully connected to the websocket gateway you can subscribe to any of the available channels that you are interested in. In order to do this, you should send a json subscription request over the websocket connection in the following format, replacing <channel-name> with the actual channel name.

{
    "action": "subscribe",
    "channelName": "<channel-name>"
}

If successful you will receive a response as follows, and you will then start receiving events as changes occur.

{
    "event": "subscribed",
    "payload": {
        "statusCode": 200,
        "channelName": "<channel-name>",
        "message": "You are now subscribed"
    }
}

If the subscription fails for some reason, you will receive an error message similar to the following example, and no events will be received. If this occurs, please contact your IHS Markit support contact quoting the connection and request ids in your response.

{
    "message": "Internal server error",
    "connectionId": "ZaXnaf88joEAcWg=",
    "requestId": "ZaYrYEx9joEFwjw="
}

Channels¶

The following tables shows the available channels that can be connected to, and the environment that they are available in.

Environment	Channel Name	Description
UAT	uat-cas-notification-muni-deal-updates	Municipal Deals
UAT	uat-cas-notification-fi	Fixed Income Deals and Orders (excluding Municipal)
UAT	uat-cas-notification-fi-bydealDealId:{DealId}	Fixed Income Deals and Orders published using CAS Id (excluding Municipal)
UAT	uat-cas-notification-eq	Equity Deals and Orders
UAT	uat-cas-notification-eq-bydealDealId:{DealId}	Equity Deals and Orders published using CAS Id
PROD	cas-notification-muni-deal-updates	Municipal Deals
PROD	cas-notification-fi	Fixed Income Deals and Orders (excluding Municipal)
PROD	cas-notification-fi-bydealDealId:{DealId}	Fixed Income Deals and Orders published using CAS Id (excluding Municipal)
PROD	cas-notification-eq	Equity Deals and Orders
PROD	cas-notification-eq-bydealDealId:{DealId}	Equity Deals and Orders published using CAS Id

Notification Messages¶

Once subscribed to a channel, any create, update or delete event relevant to that channel will trigger a message to be sent across the websocket gateway. The format of these messages may vary slightly depending on the change source, so exact message formats will be described below, after first looking at the common format.

Common Message Format¶

Below we will look at the common parts of a notification message using the following message as an example:

{
    "event":"message",
    "channelName": "uat-cas-notification-fi",
    "payload": [
        {
            "ChangeData": {
                "<varies-on-change-source>"
            },
            "ChangeSource":"Deal"
        }
    ]
}

event: This field shows the event type, and will always be message.
channelName: This field shows the channel that the message is produced from. This allows consumers to subscribe to multiple channels and know which channel a message originated from.
payload: A complex object type that contains the actual content of the notifcation.
payload.ChangeData: A complex object showing how the actual entity has changed. This will vary depedning on the change source so will be covered below iot cover this here, but in detail in each service documentation.
payload.ChangeSource: The name of the service that triggered the notification.

Deal Message¶

An example of the ChangeData for a Deal message is shown below.

{
        "ChangeData": {
                "DealId": "string",
                "EventType": "string",
                "AssetClassType": "string",
                "DealType": "string",
                "Version": "integer",
                "LastModifiedDateTime": "string"
        }
}

DealId: The id of the Deal entity that was changed.
EventType: The type of event that occured. Valid values are Create, Update, Cancelled or Delete.
AssetClassType: The asset class type of the deal. See Deals for full details.
DealType: The deal type of the deal. See Deals for full details.
Version: The version of the deal. See Deals for full details.
LastModifiedDateTime: The time this Deal entity was last changed.

Order Message¶

An example of the ChangeData for an Order message is shown below.

{
    "ChangeData": {
        "FirmId": "string",
        "DealId": "string",
        "TrancheId ": "string",
        "InvestorAccountId": "string",
        "IndicationId": "string",
        "LastModifiedDateTime": "string",
        "RequestOriginator": "string",
        "IsDeleted": false,
        "Resource": "string",
        "IndicationType": "string",
        "RowVersion": 1,
        "EventType": "string",
        "HedgeId": "string",
        "AllocationId": "string",
        "AssetClassType": "string"
    }
}

FirmId: The company ID that the order notification is for.
DealId: The id of the Deal the order is for.
TrancheId: The id of the tranche the order is for.
InvestorAccountId: The id of the investor on the order.
IndicationId: The id of the order.
IsDeleted: A boolean value indicating if the order is deleted.
Resource: A value that indicates the type of order resource. Valid values are Indication, Hedge or Allocation.
IndicationType: The type of indication. Valid values are Indication or IndicationGroup.
RowVersion: The row of the order being changed in the Database.
EventType: The event type of the notification. Valid values are Create, Update, Delete or Cancelled.
HedgeId: The id of the hedge, if one exists.
AllocationId: The id of the allocation, if one exists.
AssetClassType: The asset class type of the deal. See Deals for full details.

Access Control Message¶

An example of the ChangeData for an Access Control message is shown below.

{
    "ChangeData": {
        "EventType": "string",
        "FirmId": "string",
        "DealId": "string",
        "TrancheId ": "string",
        "Resource": "string",
        "RowVersion": 0,
        "AssetClassType": "string",
    }
}

EventType: The event type of the notification. Valid values are Create, Update, Delete or Cancelled.
FirmId: The company ID that the Access Control notification is for.
DealId: The id of the Deal the Access Control is for.
TrancheId: The id of the tranche the Access Control is for, if it exists.
Resource: A value that indicates the type of Access Control changed. Valid values are Tranche or Deal.
RowVersion: The row of the order being changed in the Database.
AssetClassType: The asset class type of the deal. See Deals for full details.