Searching...

Matching results

Alert

A rule defines the conditions under which a target becomes in alert or not.

This is a complete representation of an AlertRule.

{
    "targetType": "",
    "name": "",
    "message": "",
    "stateful": true|false,
    "active": true|false,
    "emails": [""],
    "notifMode": "",
    "conditions": [{
        "operator": "",
        "operands": [{
            "attributeId": {
                "targetId": "",
                "name": "",
                "filter": { "": }
            },
            "function": "",
            "functionParam": "",
            "valueStr": "",  
            "valueNum": ,
            "valuesStr": [""]
        }]
    }]
}

Field	Description	Type
targetType	The type of target for which the rule applies: SYSTEM | OFFER	string
name	The name of the rule	string
message	The message used in the Alert event in case of alert.	string
stateful	Indicates if the rule is stateful (ie. generates and maintains states) or not (ie. only generates events): true | false. Default value to true.	boolean
active	Indicates if the rule is enabled or not: true | false	boolean
emails	The list of emails to send notifications to.	string array
notifMode	EVERY_TIME: every time an alert is generated. WHEN_STATE_CHANGES: default, only when the state of an AlertState changes. WHEN_STATE_TRUE: only when the state of an AlertState changes from false to true. WHEN_STATE_FALSE: only when the state of an AlertState changes from true to false. IN_ALL_CASES: either when an alert is generated or when the state changes.	string
conditions	The list of conditions to be checked.	array of conditions
conditions.operator	The operator.	string
conditions.operands	Functions of the chosen operator, you have to define one or more operands.	array of operands
conditions.operands.attributeId	An attributeId is composed of a targetId and an attribute name.	attributeId
conditions.operands.attributeId.targetId	The id of the target: systemId, companyId or null to consider the current target (the one responsible for the rule evaluation)	string
conditions.operands.attributeId.name	The name of the attribute to consider	string
conditions.operands.attributeId.filter	The criteria to filter the data for aggregation. Criteria to select a sub-set of usage records: "inOfferZone": if true only the usages occured in the offer zone will be selected, false means outside the offer zone, otherwise (null value) no filter on zone will be applied. "partial": if true only the partial usage sessions will be selected, false means only the complete usage sessions will be selected, otherwise (null value) all usages sessions will be selected.	map
conditions.operands.function	The aggregation function to use in case of an aggregated attributeId (for instance AGG.room.temp/D) MIN MAX MEAN SUM CNT	string
conditions.operands.valueStr	A string value to compare with the attribute value functions of the selected operator.	string
conditions.operands.valueNum	A numeric value to compare with the attribute value functions of the selected operator.	number
conditions.operands.valuesStr	An array of strings to compare with the attribute value functions of the selected operator.	array of strings

Here is a picture explaining how the notification mode works.

An attributeId is made up of a name and an optional targetId. If targetId is set, the condition only apply on the corresponding target, if not, the conditions applies on all targets of the company.

"attributeId": {
    "targetId": "",
    "name": ""
}

Here is the list of all attribute names available when creating alert rules. Some names are dynamic and use the following parameters:

• {dataId}: the id of the data sent by the system or a data generated by the platform.
• {timeScale}: for aggregated data, H (hourly), D (daily), M (monthly)

System attributes:

• system.id
• system.name
• system.labels
• system.state
• system.activityState
• system.lifeCycleState
• system.commStatus
• system.commStatus.changeDate
• system.lastCommDate
• system.heartbeat.state
• system.heartbeat.period
• system.heartbeat.errorSLA
• system.heartbeat.warningSLA
• system.offerId
• system.defaultStatusReportState
• system.defaultStatusReportPeriod
• gateway.id
• gateway.imei
• gateway.mac.address
• gateway.serial.number
• subscription.id

System communication:

• system.comm.protocol
• DATA.{dataId}: raw data, for instance DATA.room.temp
• DATA._LON_LAT: the GPS position of the system, used by geofencing operators
• AGG.{dataId}/{timeScale}: aggregated data, for instance AGG.data.room.temp/D

Offer attributes:

• offer.id
• offer.poolBytesLimit: the pool size limit of the offer. It is updated every month according to the current number of active systems.
• offer.poolWarnLimit: 80% of the offer pool size limit by default.

System usage attributes:

• system.usage.status
• system.usage.record.voice.in.phone.number
• system.usage.record.voice.out.phone.number
• system.usage.record.sms.sent.phone.number
• system.usage.record.sms.received.phone.number
• system.usage.record.visited.country
• system.usage.record.imei

Aggregated usage data:

• AGG.{usageDataId}/{timeScale}: see description of the usage data
• AGG.VOICE_* attributes, only available for monthly timescale because voice usages are received from carriers few days after consumption: AGG.VOICE_*/M.

A condition is built with an operator and a list of operands. The first operand of all operators has to define the attribute to check on systems. Details about attributes can be found here

For each operand, one of the following field must be used.

{
    "attributeId": {},
    "valueStr": "",  
    "valueNum": ,
    "valuesStr": [""]
}

Geofencing operators use Well-Known-Text format to define shapes (POLYGON or POINT).

Here is the list of all operators with the operand fields available.

Name	1st operand	2nd operand	3rd operand
CHANGE	attributeId
EQUALS	attributeId	attributeId/valueStr/valueNum
NOT_EQUALS	attributeId	attributeId/valueStr/valueNum
GREATER_THAN	attributeId	attributeId/valueNum
LESS_THAN	attributeId	attributeId/valueNum
EXISTS	attributeId
NOT_EXISTS	attributeId
IN	attributeId	attributeId/valuesStr
NOT_IN	attributeId	attributeId/valuesStr
CONTAINS1	attributeId	attributeId/valueStr
NOT_CONTAINS	attributeId	attributeId/valueStr
STARTS_WITH	attributeId	attributeId/valueStr
ENDS_WITH	attributeId	attributeId/valueStr
GEO_WITHIN	attributeId(name=DATA._LON_LAT)	valueStr: a POLYGON described with WKT format
GEO_NOT_WITHIN	attributeId(name=DATA._LON_LAT)	valueStr: a POLYGON described with WKT format
GEO_DISTANCE_TOO_FAR	attributeId(name=DATA._LON_LAT)	attributeId(name=DATA._LON_LAT) or a valueStr containing a POINT in WKT format	valueNum corresponding to the distance in km
GEO_DISTANCE_TOO_CLOSE	attributeId(name=DATA._LON_LAT)	attributeId(name=DATA._LON_LAT) or a valueStr containing a POINT in WKT format	valueNum corresponding to the distance in km

¹The value of the right operand must be contained in the value of the left operand for the rule to trigger (this is to support cases like the left operand being “systemAttribute: labels” and the right operand being the string value of the label that the rule is checking for). Note: this differs from other containment operators such as IN or GEO_WITHIN where the space/set that must contain the value is specified as a left operand instead.

An alert gathers all the information required to understand what happened on a target for a specific rule.

This is a complete representation of an Alert

{
    "companyId": "",
    "targetId": "",
    "targetType": "",
    "ruleId": ""
    "state": ,
    "stateChangeTs": ,
    "attributes": [{
        "id": {
            "name": "" // the name of the attribute
        },
        "value": { // the value of the attribute
            "valueStr": "",
            "valuesStr": [""],
            "valueNum": ,
            "valueAgg": {
                "min": ,
                "max": ,
                "cnt": ,
                "sum": ,
                "mean":
            }
        },
        "refTime":
    }]
}

Field	Description	Type
companyId	The id of the company the target belongs to	string
targetId	The id of the target	string
targetType	The type of the target: SYSTEM | OFFER	string
ruleId	The id of the rule	string
state	True/False to indicate if the specified target is in alert for the specified sateful rule, or null if the rule is stateless	boolean
stateChangeTs	The timestamp when the state changes	timestamp
attributes	The list of attributes that brought to the current alert state	list of Attribute
attributes.id.name	The name of the checked attribute	string
attributes.value	The value of the attribute that triggered the alert. The value depends on the type. It can be a string, a list of string, a number or an aggregated value. When it is an aggregated value only the function used to generate the value is provided. For instance if the 'min' function has been used then only the 'min' attribute value is returned.	Attribute value