11 Alerts

11.1 General Usage

In cases where certain events in steaming data are of interest to the user, IQML can generate alerts of these events as they arrive from IQFeed. The user can define the event data type, the trigger condition, and the type of alert to generate when the condition is met. For example, users may configure an alert on quotes, such that when a symbol’s bid price is higher than some threshold, an email will be sent.

Each alert contains 3 components:

Data type – quote, intervalbar, regional or news

Trigger – a condition (typically a comparison between a field and a value)

Action – what IQML should do when the trigger condition is met

Alerts are created using the 'alert' action. Each new alert is assigned a unique numeric ID. Using this ID, users can query, delete or edit the alert after it was created.

The following parameters affect the alerts. Detailed explanations and usage examples are listed in the following sections.

Note: Alerts are only available in the Professional IQML license.

11.2 Alert Configuration

Alerts can be configured by the user using the 'alert' action, using the properties in the table above. Users can configure the data type, event trigger, maximal number of alert reports, and the type of alert to generate (email, pop-up message, etc.). For email alerts, users can also specify the recipients and the sender email account.

The Trigger parameter is the most important input, and is unique to the 'alert' action. It is a string describing the alert trigger event, so it is very important that it be composed properly. The Trigger string has 4 elements:

Data type ('quote', 'intervalbar', 'news' or 'regional')

Trigger field: case-insensitive name of a field in the latestData struct of the source data specified by the Data type (see §6.1, §6.3). For example: 'bid', 'ask', 'total_volume', 'Most_Recent_Trade', 'intervalVolume', 'text', etc.

Trigger operator ('>', '>=', '<', '<=', '=', or 'contains').177

'>', '<', '>=', '<=' are only relevant for non-news alerts (but not for news)

'=' and 'contains' are relevant for all alert types (including news)

Trigger value: either a scalar number (for a '>', '>=', '<', '<=', or '=' operator) or a string (for a '=' or 'contains' operator).

For example:

alertId = IQML('alert', 'Symbol','IBM', 'Trigger','quote ask < 145.70', ...);

alertId = IQML('alert', 'Symbol','IBM', 'Trigger','quote Total_Volume >= 10', ...);

alertId = IQML('alert', 'Symbol','IBM', 'Trigger','news text contains IPO', ...);

By default, alerts are only triggered and reported once. This can be changed by setting the NumOfEvents parameter to an integer value. For example, the following alert will be reported up to 5 times, and will then be deleted from the list of alerts:

alertId = IQML('alert', 'Symbol','IBM', ..., 'NumOfEvents',5);

IQML does NOT automatically start streaming data when alerts are defined. This enables users to start and stop streaming data at will, and the alerts will only be evaluated when streaming data messages arrive from IQFeed.

Note: if you use a Data type of 'quote', then depending on the setting of the Fields parameter in your latest quotes query (§4.1), the requested alert Trigger field might not exist in the streaming quotes, causing the alert to become ineffective. IQML does not automatically update Fields with the requested Trigger field. When such a case is detected, a warning message will be presented:

Warning: Field 'VWAP' is not currently included in your quotes Fields parameter, making the requested alert useless

It is sometimes convenient to start streaming immediately when the alert is created. This can be done by setting the StartStream parameter (default: false). Setting a value of true starts the streaming for the corresponding data type (e.g., streaming quotes for a symbol) automatically, unless the streaming is already active.

Note that with StartStream=true, the streaming is started automatically, using the default parameters. If you wish to control the streaming parameters (for example, NumOfEvents or DataType), leave StartStream in its default false value, and start the streaming in a separate IQML command.

The AlertAction defines the action to be performed when a triggering event is detected (i.e., when the trigger condition is met). There are 4 possible AlertAction values: 'popup', 'display', 'email', and callback (note the performance discussion in §3.6, §10.2):

'Popup' announces the triggered event in a pop-up a message-box:

alertId = IQML('alert', 'Symbol','@VX#', 'Trigger','quote bid > 14.75', ...
'AlertAction','popup');

'Display' announces the event in Matlab’s console (Command Window):

alertId = IQML('alert', 'Symbol','@VX#', 'Trigger','quote bid > 14.75', ...
'AlertAction','display');

04:50:11.099000 IQML alert: @VX# bid (14.8) > 14.75

Or, as another example of regional update alert:

alertId = IQML('alert', 'Symbol','IBM', 'AlertAction','display', ...
'Trigger', 'regional regionalbid > 140');

20180524 16:57:13.689 IQML alert: IBM regionalbid (143.75) > 140

'Email' – an email with the alert event’s details will be sent to the specified EmailRecipients, a mandatory parameter for email alerts. EmailRecipients must be set as a comma/semi-colon/colon delimited string, or a cell array of email addresses; it cannot be left empty.

For example, the following alert will send an email to two email recipients:

alertId = IQML('alert', 'Symbol','@VX#', 'Trigger','quote bid > 14.75', ...
'AlertAction','email', ...
'EmailRecipients',{'john@a.com','jane@b.com'});

which results in an email similar to this:

From: iqml.alerts@gmail.com

Subject: IQML alert: @VX# bid (14.8) > 14.75

Body:

Symbol: '@VX#'
Most_Recent_Trade: 14.82
Most_Recent_Trade_Size: 10
Most_Recent_Trade_Time: '08:40:02.926510'
Most_Recent_Trade_Market_Center: 32
Total_Volume: 6890
Bid: 14.8
...

or similarly, in the case of a news alert:

From: iqml.alerts@gmail.com

Subject: IQML alert: United Technologies Plans To Hire 35,000 People, Make $15 B... (RTB)

Body:

ID: 22017029634
Symbols: {'UTX'}
Text: '09:31 Wednesday, May 23, 2018. (RTTNews) - United Technologies Plans To Hire 35,000 People, Make $15 Bln Investment In U.S. Over Next 5 Years For comments and feedback: contact editorial@rttnews.com. Copyright(c) 2018 RTTNews.com. All Rights Reserved'

For news alerts, the full story text is fetched by default. It is possible to skip fetching the full story by setting GetStory to false. This speeds up processing by skipping the news-fetch query, and reports only the headline information:

From: iqml.alerts@gmail.com

Subject: IQML alert: United Technologies Plans To Hire 35,000 People, Make $15 B... (RTB)

Body:

Source: 'RTB'
ID: 22017029634
Symbols: {'UTX'}
Timestamp: '20180523 093143'
Text: 'United Technologies Plans To Hire 35,000 People, Make $15 B...'

As noted, EmailRecipients can be specified in various manners. For example, all the following are equivalent:

'EmailRecipients','john@a.com,jane@b.com'

'EmailRecipients','john@a.com;jane@b.com'

'EmailRecipients',{'john@a.com','jane@b.com'}

Alert emails are sent from an IQML email address (iqml.alerts@gmail.com) by default. To send the alert emails from another sender (for example, a corporate email account), specify the SmtpEmail, SmtpServer and SmtpPassword.178 These parameters are saved in your local machine’s Matlab settings, and will be used by all future IQML email alerts (even after you restart the computer), so you only need to set them once. For example:

alertId = IQML('alert', 'Symbol','GOOG', 'Trigger','quote ask < 1090', ...
'AlertAction','email', 'Recipients','JohnDoe@gmail.com', ...
'SmtpServer','smtp.gmail.com', ...
'SmtpEmail','senderEmail@gmail.com', ...
'SmtpPassword','mypassword123');

On modern smartphones, text (SMS) messages have generally been replaced with email push notifications. Still, for some users text alerts may be useful. Some mobile operators enable users to receive text messages by sending them to a specially-formed email address.179 For example, to send a text message alert to T-Mobile number 123-456-7890 in the USA, simply email the alert to 1234567890@tmomail.net. To receive alerts via such text messages, you just need to determine your mobile carrier’s email gateway for SMS messages, and set EmailRecipients accordingly. Note that carrier charges might apply.

Callback: a personalized callback function for an event can be specified using a Matlab function handle. For example:

alertId = IQML('alert', 'Symbol','GOOG', 'Trigger','…', 'AlertAction',@myFunc);

The callback function (myFunc in this example) should accept two or more inputs, as customary for Matlab callbacks:180

function myFunc(alertObject, eventData)

alertObject – a struct with the alert’s configuration (see §11.3)

eventData – a struct with the triggered event’s local time (in Matlab datenum format) and the trigger data.

For example, for quote data alerts, eventData might look like this:

>> eventData =
triggerTime: 737202.663148947
triggerData: [1×1 struct]

>> eventData.triggerData
ans =
Symbol: 'GOOG'
Most_Recent_Trade: 1083
Most_Recent_Trade_Size: 30
Most_Recent_Trade_Time: '08:54:53.159809'
Most_Recent_Trade_Market_Center: 11
Total_Volume: 1957
...

To specify additional input parameters to your callback function, set AlertAction to a cell array in which the first cell is the function handle and the rest are additional inputs. For example:

callback = {@myFunc, data1, data2};
alertId = IQML('alert', 'Symbol','GOOG', 'Trigger','…', 'AlertAction',callback);

function myFunc(alertObject, eventData, data1, data2)

... % data processing done here

end

11.3 Alerts Query

IQML can be queried for the list of all existing alerts, or just a single specific alert. Alerts are returned in this case as Matlab structs containing the alerts’ specifications.

Specific alerts may be queried by specifying their unique AlertID (which was returned by the command that created the alert), and setting NumOfEvents to -1:

>> alertID = IQML('alert', 'Symbol','IBM', 'Trigger','quote bid > 200',…);

>> alert = IQML('alert', 'AlertID',alertID, 'NumOfEvents',-1)
alert =
struct with fields:
AlertID: 22120136109
isActive: 1
DataType: 'quote'
Trigger: 'bid > 200'
TriggerType: 'bid'
TriggerOp: '>'
TriggerValue: '200'
Symbol: {'IBM'}
AlertAction: 'popup'
EmailRecipients: {}
EventsProcessed: 0
EventsToProcess: 1
LatestValue: []

The AlertID parameter can be an array of alert IDs, resulting in an array of structs.

To retrieve the list of all the existing alerts, simply set NumOfEvents to -1, without specifying the AlertID parameter:

>> allAlerts = IQML('alert', 'NumOfEvents',-1)
allAlerts =
3×1 struct array with fields:
AlertID
isActive
DataType
Trigger
TriggerType
TriggerOp
TriggerValue
Symbol
AlertAction
EmailRecipients
EventsProcessed
EventsToProcess
LatestValue

11.4 Alert Editing or Deletion

An existing alert can be edited or deleted by specifying its AlertID:

To delete an alert, set NumOfEvents to 0 as follows:

IQML('alert', 'AlertID',alertID, 'NumOfEvents',0);

To update/edit an alert, specify AlertID with one or more of the alert configuration parameters: Symbols, Trigger, AlertAction, EmailRecipients, NumOfEvents (>1).

IQML('alert', 'AlertID',alertID, 'AlertAction','email', 'EmailRecipients','john@a.com');

As above, the AlertID input can be an array of IDs, affecting multiple alerts at once.