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:

  1. The Alert Service performs the basic validations:

    • Structure check

    • Authentication check

  2. The Alert Service checks that validations passed successfully in the following order:

    • Limit

    • Business validation

  3. If all validations passed successfully, then the Alert Service:

    1. Sets up all required trigger checks (see the section below) for the alert.

    2. Sends the notification about the successful alert set-up to the user.

  4. Else (at least one validation failed), then the Alert Service returns the error message.

Alert trigger and deactivation

  1. 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

  2. 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:

  1. Performs the basic authentication validation.

  2. Checks if the alert is not deactivated yet.

  3. If all validation checks passed, then the Alert Service:

    • Deactivates the alert

    • Sends the response to the user that alert is deactivated

  4. 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

  1. The Alert Service checks every market event happened after the alert is activated that can change the value of the datapoint under alert.

  2. 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

  1. The Alert Service checks corporate actions for the dxSymbol under alert.

  2. 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"
    }
}

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.