Searching...

Matching results

    Alert


    With AirVantage Alert features, you can monitor all your systems by defining rules.

    These rules are made up of conditions which check attributes of your systems.

    A condition is built with an operator and a list of operands. Details can be found here.

    Attributes are information related to your systems:

    • system attributes like the name, the communication status, the gateway serial number, etc.
    • system data coming from the device communications,
    • and usage data coming from the operator.
    The complete list of attributes are available here

    When all the conditions of a rule are met for a specific system:

    • If the rule is stateless, an alert is generated. It is accessible from the Find history API.
    • If the rule is stateful and the state changed, an alert state is created/updated. It gives you the current state (true or false) of a system against a rule. It is accessible from Find current API. You can also access the state history with Find history API.


    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": "",
        "active": ,
        "emails": [""],
        "notifMode": "",
        "conditions": [{
            "operator": "",
            "operands": [{
                "attributeId": {
                    "targetId": ""
                    "name": ""
                },
                "function": "",
                "functionParam": "",
                "valueStr": "",  
                "valueNum": ,
                "valuesStr": [""]
            }]
        }]
    }

    Field Description Type
    targetType The type of target for which the rule applies: SYSTEM | COMPANY 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.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

    Usage data:

    • 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
    • AGG.DATA_SESSION/{timeScale}
    • AGG.DATA_DURATION/{timeScale}
    • AGG.DATA_BYTES_SENT/{timeScale}
    • AGG.DATA_BYTES_RECEIVED/{timeScale}
    • AGG.DATA_BYTES_TOTAL/{timeScale}
    • AGG.DATA_ROUNDED_BYTES_TOTAL/{timeScale}
    • AGG.VOICE_* attributes, only available for monthly timescale because voice usages are received from carriers few days after consumption.
      • AGG.VOICE_IN_SESSION/M
      • AGG.VOICE_IN_DURATION/M
      • AGG.VOICE_IN_ROUNDED_DURATION/M
      • AGG.VOICE_OUT_SESSION/M
      • AGG.VOICE_OUT_DURATION/M
      • AGG.VOICE_OUT_ROUNDED_DURATION/M
    • AGG.SMS_SENT/{timeScale}
    • AGG.SMS_RECEIVED/{timeScale}
    • AGG.MSU/{timeScale}

    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

    1The 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 | COMPANY 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

    /api/v2/alertrules

    Creates a new alert rule

    Request

    POST https://na.airvantage.net/api/v2/alertrules?company=74e52f0379ec3b4e75f91b4750824c22
    Content-Type: application/json
    ...
    {
        "targetType": "SYSTEM",
        "name": "Daily usage exceeded",
        "message": "Daily usage exceeded",
        "active": true,
        "emails": ["machin@truc.com"],
        "conditions": [{
            "operator": "GREATER_THAN",
            "operands": [
                {
                    "attributeId":
                    {
                        "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                    },
                    "function": "SUM"
                },
                {
                    "valueNum": 1024
                }
            ]
        }]
    }

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    ...
    {
        "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "targetType": "SYSTEM",
        "name": "Daily usage exceeded",
        "message": "Daily usage exceeded",
        "active": true,
        "emails": ["machin@truc.com"],
        "conditions": [{
            "operator": "GREATER_THAN",
            "operands": [
                {
                    "attributeId":
                    {
                        "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                    },
                    "function": "SUM"
                },
                {
                    "valueNum": 1024
                }
            ]
        }]
    }
    Name Description Use Default Type
    company Set the context company. optional caller's company uid
    Name Description
    alert.rule.missing.operator A condition must have an operator
    alert.rule.multiple.operand.type An operand can only be one of attributeId/valueStr/valueNum/valuesStr
    alert.rule.invalid.number.of.operands Wrong number of operands for the chosen operator
    alert.rule.invalid.operand.type An operand is not using the proper value for the chosen operator
    alert.rule.geo.invalid.wkt The given WKT is not valid
    alert.rule.geo.bad.attribute.id The geofencing rule is not using the right attributeId (DATA._LON_LAT)
    alert.rule.invalid.function The given function is not available
    alert.rule.missing.attr.operand First operand must be an attributeId
    alert.rule.too.many The number of rules per company is greater than 50
    alert.rule.condition.too.many The number of conditions per rule is greather than 10
    alert.rule.incorrect.target.type The target type is missing or invalid
    alert.rule.bad.voice.agg.usage AGG.VOICE_* attributes can only be used with monthly timescale
    HTTP Method POST
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.rule.create.edit.delete

    /api/v2/alertrules

    Retrieves all rules of your company sorted by name.

    Request

    GET https://na.airvantage.net/api/v2/alertrules?company=74e52f0379ec3b4e75f91b4750824c22

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    ...
    [
        {
            "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
            "targetType": "SYSTEM",
            "name": "Daily usage exceeded",
            "message": "Daily usage exceeded",
            "active": true,
            "emails": ["machin@truc.com"],
            "conditions": [{
                "operator": "GREATER_THAN",
                "operands": [
                    {
                        "attributeId":
                        {
                            "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                        },
                        "function": "SUM"
                    },
                    {
                        "valueNum": 1024
                    }
                ]
            }]
        },
        ...
    ]
    Name Description Use Default Type
    company Set the context company. optional caller's company uid
    HTTP Method GET
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.rule.view

    /api/v2/alertrules/{uid}

    Returns detailed information about the specified rule.

    Request

    GET https://na.airvantage.net/api/v2/alertrules/0f3919fd1ac0403ab9e70ae2c3729a21?company=74e52f0379ec3b4e75f91b4750824c22

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    ...
    {
        "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "targetType": "SYSTEM",
        "name": "Daily usage exceeded",
        "message": "Daily usage exceeded",
        "active": true,
        "emails": ["machin@truc.com"],
        "conditions": [{
            "operator": "GREATER_THAN",
            "operands": [
                {
                    "attributeId":
                    {
                        "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                    },
                    "function": "SUM"
                },
                {
                    "valueNum": 1024
                }
            ]
        }]
    }
    Name Description Use Default Type
    company Set the context company. optional caller's company uid
    HTTP Method GET
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.rule.view

    /api/v2/alertrules/{uid}

    Updates the specified alert rule. All alert rule fields are exepected in the body, not only the ones you want to modify.

    Request

    PUT https://na.airvantage.net/api/v2/alertrules/0f3919fd1ac0403ab9e70ae2c3729a21?company=74e52f0379ec3b4e75f91b4750824c22
    Content-Type: application/json
    ...
    {
        "targetType": "SYSTEM",
        "name": "Temperature exceeded",
        "message": "Temperature exceeded",
        "active": true,
        "emails": ["machin@truc.com"],
        "conditions": [{
            "operator": "GREATER_THAN",
            "operands": [
                {
                    "attributeId":
                    {
                        "name": "DATA.room.temp"
                    }
                },
                {
                    "valueNum": 38
                }
            ]
        }]
    }

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    ...
    {
        "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "targetType": "SYSTEM",
        "name": "Temperature exceeded",
        "message": "Temperature exceeded",
        "active": true,
        "emails": ["machin@truc.com"],
        "conditions": [{
            "operator": "GREATER_THAN",
            "operands": [
                {
                    "attributeId":
                    {
                        "name": "DATA.room.temp"
                    }
                },
                {
                    "valueNum": 38
                }
            ]
        }]
    }
    Name Description Use Default Type
    company Set the context company. optional caller's company uid
    Name Description
    alert.rule.missing.id A rule id must be specified.
    alert.rule.unknown.id The specified rule is unknown.
    alert.rule.missing.operator A condition must have an operator
    alert.rule.multiple.operand.type An operand can only be one of attributeId/valueStr/valueNum/valuesStr
    alert.rule.invalid.number.of.operands Wrong number of operands for the chosen operator
    alert.rule.invalid.operand.type An operand is not using the proper value for the chosen operator
    alert.rule.geo.invalid.wkt The given WKT is not valid
    alert.rule.geo.bad.attribute.id The geofencing rule is not using the right attributeId (DATA._LON_LAT)
    alert.rule.invalid.function The given function is not available
    alert.rule.missing.attr.operand First operand must be an attributeId
    alert.rule.too.many The number of rules per company is greater than 50
    alert.rule.condition.too.many The number of conditions per rule is greather than 10
    alert.rule.incorrect.target.type The target type is missing or invalid
    alert.rule.bad.voice.agg.usage AGG.VOICE_* attributes can only be used with monthly timescale
    HTTP Method PUT
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.rule.create.edit.delete

    /api/v2/alertrules/{uid}

    Deletes the specified alert rule

    Request

    DELETE https://na.airvantage.net/api/v2/alertrules/0f3919fd1ac0403ab9e70ae2c3729a21?company=74e52f0379ec3b4e75f91b4750824c22

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    "success"
    Name Description Use Default Type
    company Set the context company. optional caller's company uid
    Name Description
    alert.rule.missing.id A rule id must be specified.
    alert.rule.unknown.id The specified rule is unknown.
    HTTP Method DELETE
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.rule.create.edit.delete

    /api/v3/alerts/current

    Finds current alerts

    Returns a paginated list of alerts sorted by 'stateChangeTs' field.

    It is possible to filter out the result list using criteria parameters. Note that all combinations of criteria are not possible. Here are all the possible combinations:

    • by target: GET /api/v3/alerts/current?company= &targetId= &offset= &size=
    • by target and rule: GET /api/v3/alerts/current?company= &targetId= &ruleId= &offset= &size=
    • by state: GET /api/v3/alerts/current?company= &state= &offset= &size=
    • by state and targetType: GET /api/v3/alerts/current?company= &state= &targetType= &offset= &size=
    • by state, targetType and rule: GET /api/v3/alerts/current?company= &state= &targetType= &ruleId= &offset= &size=

    More information about paging here

    Request

    GET https://na.airvantage.net/api/v3/alerts/current?targetId=91b74e52f04750824c22379ec3b4e75f&offset=0&size=100&company=74e52f0379ec3b4e75f91b4750824c22

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    ...
    {
        "items": [{
            "companyId": "74e52f0379ec3b4e75f91b4750824c22",
            "targetId": "91b74e52f04750824c22379ec3b4e75f",
            "targetType": "SYSTEM",
            "ruleId": "e52237824c29ecf003b4e7745f91b475"
            "state": true,
            "stateChangeTs": 1469446036000,
            "attributes": [{
                "id": {
                    "name": "DATA.room.temp"
                },
                "value": {
                    "valueNum": 45
                },
                "refTime": 1466859976000
            }]
        }],
       "count": 1
    }
    Name Description Use Default Type
    targetId Search alert states by target id. optional null string
    ruleId Search alert states by rule id. Must be used together with targetId or targetType filter. optional null string
    state Search alert states by state. optional null boolean
    targetType Search alert states by target type. Must be used together with state filter. optional null string
    company Set the context company. optional caller's company string
    HTTP Method GET
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.view

    /api/v3/alerts/history

    Finds stateful and stateless alerts between two dates.

    Returns a maxium of 500 alerts sorted by 'ts' field.

    Request

    GET https://na.airvantage.net/api/v3/alerts/history?targetId=91b74e52f04750824c22379ec3b4e75f&to=1469451977000&company=74e52f0379ec3b4e75f91b4750824c22

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Type: application/json
    ...
    {
        "items": [{
            "companyId": "74e52f0379ec3b4e75f91b4750824c22",
            "targetId": "91b74e52f04750824c22379ec3b4e75f",
            "targetType": "SYSTEM",
            "ts": 1466859977000,
            "ruleId": "0f3919fd1ac0403ab9e70ae2c3729a21",
            "state": null, // null because the rule is stateless
            "attributes": [{
                "id": {
                    "name": "DATA.room.door.opened"
                },
                "value": {
                    "valueStr": "true"
                },
                "refTime": 1466859976000
            }]
        },{
            "companyId": "74e52f0379ec3b4e75f91b4750824c22",
            "targetId": "91b74e52f04750824c22379ec3b4e75f",
            "targetType": "SYSTEM",
            "ts": 1466859967000,
            "ruleId": "04e70a0fb9ace2c3729a3919fd103a21",
            "state": true, // not null because the rule is stateful (can be true or false)
            "attributes": [{
                "id": {
                    "name": "DATA.room.temp"
                },
                "value": {
                    "valueNum": 45
                },
                "refTime": 1466859966000
            }]
        }
        ]
    }
                    
    Name Description Use Default Type
    targetId Search alerts for the specified target id. optional string
    ruleIds Search alerts for the specified rule ids. optional string (ruleId separated by ",")
    from/to Search alerts whose timestamp is between 'from' and 'to'.
    • if asc is true: ----from-[--------to-[----->
    • if asc is false: ----from-]--------to-]----->
    optional to: now, from: now - 90 days timestamp
    asc If true, sort alert by ts in ascending order, otherwise in descending order. optional false boolean
    size Page size optional 100 number
    company Set the context company. mandatory string
    Name Description
    missing.company 'company' parameter is mandatory.
    system.invalid.timerange 'from' paramter needs to be lower than 'to' parameter.
    HTTP Method GET
    Requires Authentication Yes
    Rate Limited Yes
    Headers None
    Permissions entities.alerts.view

    /api/v1/alerts/rules/{uid}/hooks

    Configures notification hooks when the alert rule is triggered.
    When a rule get trigged, a callback is invoked with the content described in Subscriber API tab below

    Request

    POST https://na.airvantage.net/api/v1/alerts/rules/edcda0dce0fb47948d03fbec5350c18e/hooks
    Content-Type: application/json
    ...
    {
        "callback" :  "http://www.mysite.com/callback"
    }
            

    Response
    200 OK

    {
    "uid" : "48d03fbec5350c18eedcda0dce0fb479"
    "callback" :  "http://www.mysite.com/callback"
    }
    Field Description Use Default Type
    callback The url that will be called when the alert rule get triggerd. The url has the following pattern : http(s)://(user:password@)www.yourhost.com/your_rest_service mandatory - string
    The callback endpoint will be requested with a POST method. Its content body is like the content below (JSON format):

    Request

    POST http://www.yoursite.com/your_callback
    Content-Type: application/json
    ...
    {
        "name":"event.alert.rule.triggered",
        "date":1385718100163,
        "content": {
            "alert.uid":"f04a77e306de463e919ec39c387fa016",
            "rule.uid":"7316ee643b17473381b61b8ac0afa824",
            "target.uid":"da687e2c39d54bc391633fa9c8d4c0da"
        }
    }
                                        

    Response

    The response will not be parsed interpreted. If the http status is different from 2xx or 3xx, or if the callback takes more that 10 seconds to answer, the endpoint might be disactivated.
    Name Description
    alert.rule.unknown The specified uid does not match with any alert rule.
    notification.endpoint.missing.uri The callback url was missing.
    notification.endpoint.invalid.uri The callback url format isn't well formed or invalid.
    notification.endpoint.unsupported.protocol Only HTTP protocols are supported.
    HTTP Method POST
    Requires Authentication Yes
    Rate Limited Yes
    Headers Content-type: application/json
    Permissions entities.alerts.rule.subscribe

    /api/v1/alerts/rules/{uid}/hooks

    Gets the list of all notification hooks configured for a specific alert rule.

    Request

    GET https://na.airvantage.net/api/v1/alerts/rules/edcda0dce0fb47948d03fbec5350c18e/hooks
        

    Response
    200 OK

    HTTP/1.1 200 OK
    [
    {
        "callback" : "http://www.mysite.com/callback",
        "uid" : "b88c03b43db74cacaab266e5c4481559"
    },
    {
        "callback" : "http://www.myothersite.com/callback",
        "uid" : "68c2bf58c6ee4484a92927c7afa9aaf5"
    },
    ...
    ]
                                    
    Name Description
    alert.rule.unknown The specified uid does not match with any alert rule.
    HTTP Method GET
    Requires Authentication Yes
    Rate Limited Yes
    Headers Content-type: application/json
    Permissions entities.alerts.rule.subscribe

    /api/v1/alerts/rules/{uid}/hooks/{uid}

    Removes a specific notification hook for an operation.

    Request

    DELETE https://na.airvantage.net/api/v1/alerts/rules/edcda0dce0fb47948d03fbec5350c18e/hooks/4693044f8abc4b078d9fd65a9a3e45d9
            

    Response
    200 OK

    HTTP/1.1 200 OK
    Content-Length: 0
    
    Name Description
    alert.rule.unknown The specified uid does not match with any alert rule.
    HTTP Method DELETE
    Requires Authentication Yes
    Rate Limited Yes
    Headers Content-type: application/json
    Permissions entities.alerts.rule.subscribe
    TOP