Page tree
Skip to end of metadata
Go to start of metadata

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

Create alert

POST v1/subscribers/{client key}/alerts

Expected values:

  1. Predicate: >, <, >=, <=.

  2. Expiration date: maximum 90 calendar days from the set-up date.

  3. Symbol in dxFeed symbol notation.

  4. Value to be checked (alertValue). Percents should be provided as a fraction.

{
    "externalId": "string",
    "dxSymbol": "string",
    "datapoint": "string",
    "predicate": ">",
    "alertValue": "number",
    "expirationTime": "string"
}

If the Alert Service cannot parse an alert or the alert breaches validation, then the Service returns an error:

ERROR (400): Bad Request
{
    "errorCode": "string",
    "errorDescription": "string",
    "alertValidation": {
        "dxFeedId": "string",
        "externalId": "string",
        "eventCode": "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"
}

Deactivate alert

DELETE v1/subscribers/{client key}/alerts/{dxfeedId}

If the user’s request breaches authentication validation, then the error is returned:

ERROR (400): Bad Request
{
    "errorCode": "string",
    "errorDescription": "string",
    "alertValidation": {
        "dxFeedId": "string",
        "externalId": "string",
        "eventCode": "string"
    }
}

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

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.