Alert Service

Overview

The Alert Service is a tool which provides a possibility to be aware about critical changes in the value of the pre-defined indicator for a user-selected instrument.

Use cases

Name	Main Scenario
Alert activation	After a user sends the message to activate the alert: The Alert Service performs the basic validations: Structure check Authentication check The Alert Service checks that validations passed successfully in the following order: Limit Business validation If all validations passed successfully, then the Alert Service: Sets up all required trigger checks (see the section below) for the alert. Sends the notification about the successful alert set-up to the user. Else (at least one validation failed), then the Alert Service returns the error message.
Alert trigger and deactivation	If the Alert Service identifies the successful trigger check, then the Alert Service: Sends notification to the user about an alert trigger via WS Deactivates the alert Else (trigger action is not executed), then the Alert Service continues monitoring.
Alert deactivation by user request	After a user sends a message to deactivate the earlier activated alert, then the Alert Service: Performs the basic authentication validation. Checks if the alert is not deactivated yet. If all validation checks passed, then the Alert Service: Deactivates the alert Sends the response to the user that alert is deactivated Else (some validation failed), then the Alert Service returns the error message.

Alert status transition

Validation name	Validation Failure Criterion	Event Code	Error Code	Error Description
Parsing a request	The user’s request can’t be parsed by the system: The structure of the request is not expected Values in the request have unexpected data types	-	PARSING_ISSUE	The request structure is not valid or the provided values have unexpected data type
Not valid client key	The received request has an invalid client key (it does not match any key in the DB)	-	AUTH_ISSUE	The provided client key is invalid
The client performs the action with an invalid dxFeed ID	The alert with the dxFeed ID in the client’s request either does not exist or was set up by a different client	-	AUTH_ISSUE	The client tries to perform an action with the alert that does not belong to this client
Alert is already deactivated	The alert has a status deactivated or rejected	VALIDATION_ALERT_WAS_DEACTIVATED_EARLIER	VALIDATION_FAILED	Alert was already deactivated before
Limit	The number of active alerts per the client including this new alert exceeds the allowed number of requests per the client	VALIDATION_EXCEED_LIMIT_NUMBER_ACTIVE_ALERTS	VALIDATION_FAILED	Too many active alerts
dxSymbol	dxSymbol provided in the alert is NOT available in the instrument list of the Alert Service	VALIDATION_INVALID_SYMBOL	VALIDATION_FAILED	Symbol is not valid
Predicate format	Predicate provided in the alert is NOT in the list: >, <, >=, >=	VALIDATION_INVALID_PREDICATE	VALIDATION_FAILED	Predicate is not valid
Datapoint validity	Datapoint provided in the alert is NOT in the list of supported data points	VALIDATION_INVALID_DATAPOINT	VALIDATION_FAILED	Datapoint is not valid
Expiration is in the past	Expiration date is less than the current date/time	VALIDATION_PAST_EXPIRATION_DATE	VALIDATION_FAILED	Expiration date is in the past
Alert expiration date	Number of days between activation and expiration dates of the alert exceeds 90 days	VALIDATION_EXCEED_LIMIT_EXPIRATION_DATE	VALIDATION_FAILED	Expiration time of the alert is expected in less than 90 days

Alert triggers

Trigger Name	Trigger category	Trigger Activation criterion	Event Code	Trigger Description	Frequency
Financial check	Business	The Alert Service checks every market event happened after the alert is activated that can change the value of the datapoint under alert. If the value of the datapoint matches with the user defined criterion, then the alert is triggered.	TRIGGER_MARKET_EVENT	The user-defined alert is triggered	Every datapoint update for the symbol
Corporate Action check	Business	The Alert Service checks corporate actions for the dxSymbol under alert. If at the current day either the symbol change, a spin-off or an instrument split happened, then the alert is triggered.	TRIGGER_CORPORATE_ACTION		At the end of the post-market (regular if the instrument is not traded in post-market) trading day for the instrument under alert
Option expiration	Business	If the current date equals to the expiration date of the instrument, then the alert is triggered	TRIGGER_OPTION_EXPIRED	The option under alert expired	At the end of the post-market (regular if the instrument is not traded in post-market) trading day for the instrument under alert
Alert expiration	Technical	At midnight UTC alert service checks: If current date/time `≥` Trigger Expiration Time, then alert is triggered.	TRIGGER_ALERT_EXPIRED	Alert is expired	Daily - midnight UTC
Symbol in reference data	Technical	If dxSymbol under alert is NOT available in the reference data, then alert is triggered	TRIGGER_SYMBOL_REMOVED	The instrument universe of the service does not include the symbol of the alert	Hourly

API notes

Basic API entities

All dxFeed API responses are constructed based on 3 main structures:

alert: the latest state of the alert in the dxFeed system including its static information

{
    "status": "ACTIVATED",
    "lastEventTime": "string",
    "dxFeedId": "string",
    "externalId": "string",
    "dxSymbol": "string",
    "datapoint": "string",
    "predicate": ">",
    "value": "number",
    "expirationTime": "string",
    "creationTime": "string"
}

event: the latest action that happened with the alert in the dxFeed system and the status of the alert after it happened

{
    "eventCode": "string",
    "eventTime": "string",
    "eventValue": 1.2323,
    "alertStatus": "string"
}

error: an error description when dxFeed system is not able to process a user’s request

{
    "errorCode": "string",
    "errorDescription": "string",
    "alertValidation": {
        "dxFeedId": "string",
        "externalId": "string",
        "eventCode": "string"
    }
}

Time attributes

All time attributes are expected:

Either in UTC timezone according to ISO 8601 standard
or UTC time in seconds

Requests

Message Name	Request	Response (200 OK)	Response (400 Bad Request)
Create alert	`POST v1/subscribers/{client key}/alerts` Expected values: Predicate: >, <, >=, <=. Expiration date: maximum 90 calendar days from the set-up date. Symbol in dxFeed symbol notation. Value to be checked (alertValue). Percents should be provided as a fraction. { "externalId": "string", "dxSymbol": "string", "datapoint": "string", "predicate": ">", "alertValue": "number", "expirationTime": "string" }	If an alert in the request passed validations, then the user receives alert information in dxFeed format: { "status": "ACTIVATED", "lastEventTime": "string", "dxFeedId": "string", "externalId": "string", "dxSymbol": "string", "datapoint": "string", "predicate": ">", "value": "number", "expirationTime": "string", "creationTime": "string" }	If the Alert Service cannot parse an alert or the alert breaches validation, then the Service returns an error: { "errorCode": "string", "errorDescription": "string", "alertValidation": { "dxFeedId": "string", "externalId": "string", "eventCode": "string" } }
Deactivate alert	`DELETE v1/subscribers/{client key}/alerts/{dxfeedId}`	If the user’s request is processed by the system, then the latest alert status and alert static are sent: { "status": "DEACTIVATED", "lastEventTime": "string", "dxFeedId": "string", "externalId": "string", "dxSymbol": "string", "datapoint": "string", "predicate": ">", "value": "number", "expirationTime": "string", "creationTime": "string" }	If the user’s request breaches authentication validation, then the error is returned: { "errorCode": "string", "errorDescription": "string", "alertValidation": { "dxFeedId": "string", "externalId": "string", "eventCode": "string" } }
All alerts with some specific status	`GET v1/subscribers/{client key}/alerts?status={status}&beforeDxFeedID={beforeDxFeedID}&pageSize={limit}` The alerts are ordered by dxFeed ID in the descending order Info The request is paginated. pageSize is 100 by default. Info Filtering of the set. If the `beforeDxFeedId` is not defined, then the last set of events is returned. Else, the set of events with dxFeed ID less than the defined by the user is returned.	If the client key is valid, then: { "snapshotTime": "string", "alerts": [ { "status": "string", "lastEventTime": "string", "dxFeedId": "string", "externalId": "string", "dxSymbol": "string", "datapoint": "string", "predicate": ">", "value": "number", "expirationTime": "string", "creationTime": "string" } ] } If there are no active alerts set by this client, then an empty array is returned
Events related to some specific alert	`GET v1/subscribers/{client key}/alerts/{dxfeedId}/events` The events are ordered by event time in the descending order	{ "events": [ { "eventCode": "string", "eventTime": "string", "eventValue": "1.2323, "alertStatus": "string" } ] }

Notification messages (WS)

Message Name	Trigger Message
Notification	WS endpoint: `v1/ws/subscribers/{client key}/alert-notifications` If a trigger is activated, then the Alert Service sends the details of the happened event and the alert static: { "eventTime": "string", "eventValue": "number", "eventCode": "string", "alertStatus": "string", "alert": { "status": "DEACTIVATED", "lastEventTime": "string", "dxFeedId": "string", "externalId": "string", "dxSymbol": "string", "datapoint": "string", "predicate": ">", "value": "number", "expirationTime": "string", "creationTime": "string" } }

Message Name

Trigger Message

Notification

WS endpoint: v1/ws/subscribers/{client key}/alert-notifications

If a trigger is activated, then the Alert Service sends the details of the happened event and the alert static:

{
    "eventTime": "string",
    "eventValue": "number",
    "eventCode": "string",
    "alertStatus": "string",
    "alert": {
        "status": "DEACTIVATED",
        "lastEventTime": "string",
        "dxFeedId": "string",
        "externalId": "string",
        "dxSymbol": "string",
        "datapoint": "string",
        "predicate": ">",
        "value": "number",
        "expirationTime": "string",
        "creationTime": "string"
    }
}

Error handling scenario for the client

This section presents the minimal set of expected failure handling scenarios which should be implemented by the systems involved in the alerting flow.

In case the answer to the request is not coming in the reasonable amount of time, then the client is encouraged to send the request with the same ID again.
The user should be able to handle messages with dxFeed ID that is unknown to the user. Such messages should be ignored by the client.

In this section: