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.

Parameter

Data type

Default

Description

Symbol or Symbols 149

colon or comma-delimited string or cell-array of strings

(none)

Limits the alert to the specified symbols and meta-tags only. Examples:

'IBM'

'IBM:AAPL:GOOG'

'IBM,AAPL,GOOG'

{'IBM', 'AAPL', 'GOOG'}

Optional parameter for news alerts; mandatory for quote/intervalbar alerts

Trigger

string describing the alert trigger

(none)

must be defined for new alerts!

A string composed of the data type, triggering parameter, trigger operator and triggering value, separated by spaces. Examples:

'quote bid >= 100'

'intervalbar close < 80'

'news text contains IPO'

AlertAction

string, function handle, or callback cell array

(none)

must be defined for new alerts!

Type of alert to generate. Options: 150

'display'

'popup'

'email' (requires specifying the EmailRecipients parameter)

@myCallbackFcn

{@myFcn, data1, data2, …}

NumOfEvents

integer

1

Maximal # of times to be alerted of the defined event. NumOfEvents = -1 returns a list of all existing alerts.

StartStream

logical (true/false)

false

If false (default), data streaming needs to be started by the user in a separate command.

If true and relevant data streaming is not currently active, IQML starts the data streaming automatically (see §11.2).

AlertID

integer (scalar or array)

[]

(empty array)

Unique ID generated and returned by IQML when new alert is defined.

AlertID is relevant (and mandatory) only for querying, editing or deletion of existing alerts. See §11.3, §11.4 below.

GetStory

logical (true/false)

true

If true (default), the full story text is fetched and reported with each news alert via email/callback;
if false, only headline data will be reported.

GetStory is relevant only for news alerts with AlertAction='email' or callback.

EmailRecipients

comma-delimited string or cell-array of strings

''
(empty string)

Email addresses to which email alerts will be sent. This parameter is relevant (and mandatory) only for email alerts. Examples:

'john@doe.com'

'john@doe.com, jane@doe.com'

{'john@doe.com', 'jane@doe.com'}

SmtpEmail

string

'iqml.alerts@gmail.com'

SMTP e-mail address from which alert emails will be sent.

This parameter is relevant only for specifying a non-default email sender.

SmtpEmail only needs to be set once, and is used by all future IQML alert events.

SmtpServer

string

(none)

SMTP server that will send alert emails.

This parameter is relevant only for specifying a non-default email sender.

SmtpServer only needs to be set once, and is used by all future IQML alert events.

SmtpPassword

string

(confidential)

Password of the sender’s e-mail account.

This parameter is relevant only for specifying a non-default email sender.

SmtpPassword only needs to be set once, and is used by all future IQML alert events.

warningNote: 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' or 'news')

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 ('>', '<', '=', '>=', '<=', 'contains').151

'>', '<', '=', '>=', '<=' are relevant for quote/intervalbar alerts

'=' and 'contains' are relevant for news alerts

Trigger value: either numeric (for a >,<,=,>=,<= operator) or string (for a =,contains operator)

For example:

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

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);

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

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.152 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 push notifications of incoming emails. Still, for some users text alerts may be useful. Some mobile operators enable users to receive text messages by sending the messages to a specially-formed email address.153 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.

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:154

function myFunc(alertObject, eventData)

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

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.


149 In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization

150 Note the performance implications that are discussed in §3.6 and §10.2 above

151 Additional trigger operators may be added in future IQML releases.

152 The SMTP port is automatically assumed to be 465

153 https://en.wikipedia.org/wiki/SMS_gateway#Email_clients. Note that carrier charges for these SMS messages might apply.

154 https://www.mathworks.com/help/matlab/creating_plots/callback-definition.html; https://www.mathworks.com/help/matlab/creating_guis/write-callbacks-using-the-programmatic-workflow.html#f16-1001315