Searching...

Matching results

    Cloud Connectors Format

    This document describes the available connectors and specify the format of the Message Notification mechanism available on AirVantage.

    Initializing Table Of Contents...

    Message Format

    AirVantage generates constantly different kind events. This section presents the existing events and points out how binding can be done to be notified as soon as an event is raised.

    All events messages are formatted in JSON. They are composed by their binding name and the date time when they where raised. The content tag holds the event’s payload. This content varies depending on the event type.

     {
   "name" : "events.binding.name",
   "date" : 1403793930523,
   "content" : {
      ...
   }
}

    Overview

    ‘Event’ is a readOnly entity that describes public events of AirVantage.

    There are 6 different server events. Take a look to the next sections to see the structure send for each event:

    • Operation Events: Sent on every operation state change. Its type name is event.operation.state.change
    • Operation Task Events: Sent on every operation task state change. Its type name is event.operation.task.state.change
    • Alert Events: Sent every time an alert rule condition is verified. Its type name is event.alert.rule.triggered
    • System Usage Record Events: Sent every time a usage record is imported. Its type name is event.system.usage.record.
    • SMS MO Events: Sent every time an SMS Mobile Originated message is recieved from the device. Its type name is event.sms.mo.
    • SMS MT Result Events: Sent every time an SMS Mobile Terminated message is completed. Its type name is event.sms.mt.result.

    Field Description Type
    name Events type name. There are four kind of events send by AirVantage. string
    date Date time when the event was raised. long
    contents A map with detailed information about the event. Common information than can be detailed here is the system id, the rule id, the operation id, the data sent by the system, etc. object

    Operation State Change

    During its execution, an operation goes through different states. Every time a new state is reached an event is raised. An operation is composed of one or several tasks, which will in turn follow different steps. In addition to the new operation state, this event shows the number of tasks in their different steps. All events of this kind are identified by its name: event.operation.state.change

    Its structure looks like the following:

    {
   "name" : "event.operation.state.change",
   "date" : 1403793930523,
   "content" : {
      "operation.uid" : "f89476adad3b4cad97b1ac0a8fe1bf44",
      "operation.state.old" : "IN_PROGRESS",
      "operation.state.new" : "FINISHED",
      "operation.counters" : {
         "init" : 0,
         "pending" : 0,
         "in.progress" : 0,
         "being.cancelled" : 0,
         "cancelled" : 2,
         "failure" : 2,
         "success" : 15
      }
   }
}

    Content Description

    Name Description
    operation.uid Unique identifier of the operation
    operation.state.old Previous operation state
    operation.state.new The new state
    operation.counters

    Number of tasks on each state

    • init : number of task initializing
    • pending : number of tasks waiting to be executed
    • being.cancelled : number of tasks being cancelled
    • cancelled : number of tasks cancelled
    • failure : number of tasks finished with errors
    • success : number of successful tasks

    Operation Task State Change

    An operation is composed of one or several tasks. Each task is linked to an entity (a system, a subscription, …). During its execution, a task goes through different states. For each task, an event is raised when the execution is started and finished. All events of this kind are identified by its name: event.operation.task.state.change

    Its structure looks like the following:

    {
   "name" : "event.operation.task.state.change",
   "date" : 1403793930523,
   "content" : {
      "operation.uid" : "f89476adad3b4cad97b1ac0a8fe1bf44",
      "operation.type" : "SYSTEM_SEND_COMMAND",
      "task.uid" : "1aa6ef12bcfc423fb6fa6ae120af1beb",
      "target.uid" : "259255f88d3a320385ab5cc610d7f3b5",
      "state" : "SUCCESS"
   }
}

    Content Description

    Name Description
    operation.uid Unique identifier of the operation
    operation.type Type of the operation
    task.uid Unique identifier of the task
    target.uid Unique identifier of the entity linked to the task
    state The state of the task. Possible values are: STARTED, SUCCESS, FAILED, CANCELLED

    Alert Triggered

    This is the new format for the alert message which comes with a new logic. You can still have a look to The Old alert message (deprecated)

    The Old alert message (deprecated)

    1) The temperature changes across the time.

    2) The device reads the sensor and sends the data regurlarly.

    3) Two alert rules are configured:

    • Alert rule 1 is raised when the value received changes.
    • Alert rule 2 is raised when the temperature value is greater than 15 (and cleared when below 15). In other words, this alert stays raised while temperature is greater than 15.

    4) The alert message for Alert rule 2 is sent through the cloud connector when the condition is met.

    AirVantage features a mechanism to be alerted each time a specific rule is confirmed.

    All events of this kind are identified by its name: event.alert.rule.triggered

    Its structure looks like the following:

    {
   "name" : "event.alert.rule.triggered",
   "date" : 1403793930523,
   "content" : {
      "alert.uid" : "f89476adad3b4cad97b1ac0a8fe1bf44",
      "rule.uid" : "3355fd07d0314e8792015192271895e4",
      "target.uid" : "597320612062696e6172797472696e67"
   }
}

    Content description

    Name Description
    alert.uid The unique identifier of the alert raised
    rule.uid The unique identifier of the rule having triggered the alert
    target.uid The unique identifier of the entity matching the conditions of the rule leading to the this alert. Most of the times it is the system’s uid

    Every time rule conditions are met, an alert’s message is pushed in the stream for the stateles rules.

    For the stateful rules, a message is sent only when the alert’s state changes. As a consequence, no message will be sent if the conditions are met but the state doesn’t change.

    1) The temperature changes across the time.

    2) The device reads the sensor and sends the data regurlarly.

    3) Two alert rules are configured:

    • Alert rule 1 is raised when the value received changes.
    • Alert rule 2 is raised when the temperature value is greater than 15 (and cleared when below 15). In other words, this alert stays raised while temperature is greater than 15.

    4) The alert message for Alert rule 2 is sent through the cloud connector when the condition is met.

    The following format is used for stateful and stateless alert events.

    {
   "name" : "event.alert.rule.triggered",
   "date" : 1403793930523,
   "content" : {
      "rule.uid" : "3355fd07d0314e8792015192271895e4",
      "target.uid" : "597320612062696e6172797472696e67",
      "state" : "true|false|null",
      "attributes": [{
            "id": {
                "name": "DATA.room.temp"
            },
            "value": {
                "valueNum": 45
            },
            "refTime": 1466859976000
        }]
   }
}

    Content description

    Name Description
    rule.uid The unique identifier of the rule having triggered the alert
    target.uid The unique identifier of the entity matching the conditions of the rule leading to the this alert. Most of the times it is the system’s uid
    state

    This defines the alert state: * true if the alert is raised * false if the alert is cleaned * null if the alert has no state
    attributes lists the parameters and the values used in the condition.

    Usage Record Imported

    This event is raised every time a usage record is imported to the server. This event exposes the information about each communication of a system.

    All events of this kind are identified by its name: event.system.usage.record

    Provided content depends on the type of usage ( DATA, VOICE, SMS, USSD MSU ):

    {
   "name" : "event.system.usage.record",
   "date" : 1403793930523,
   "content" : {
      "system.id" : "f89476adad3b4cad97b1ac0a8fe1bf44",
      "system.name" : "My System",
      "system.iccid" : "89240180000088709",
      "system.labels" : ["Label1", "Label2"],
      "usage.record.id" : "2c12547b613740adb686271bdc8f0978",
      "usage.type" : "DATA",
      ...
   }
}

    Content description

    Usage Type Name Description
    All system.id Unique identifier of the system responsible for the communication.
    All system.name The name of the communicating system.
    All system.iccid The unique identifier of the SIM binded to the communicating system.
    All system.labels The current labels name of the communicating system.
    All system.offer.id The unique identifier of the system offer.
    All system.offer.name The name of the system offer.
    All usage.record.id The unique identifier of the record. Record id shall be constant for a given session (same for all interim records).
    All usage.type The type of the usage : DATA, VOICE_IN, VOICE_OUT, SMS_SENT, SMS_RECEIVED, MSU.
    All usage.start.ts The start date of the communication session. It’s a timestamp in milliseconds.
    DATA, VOICE usage.end.ts The end date of the communication session. This date is equal to the start date if it’s an interim record. It’s a timestamp in milliseconds.
    DATA usage.partial Partial is true if it’s an interim record, false when the session has ended.
    All usage.serving.network.identity The visited mobile network operator.
    All usage.serving.network.country The visited mobile network operator country.
    All usage.serving.network.mnc The Mobile Network Code.
    All usage.serving.network.mcc The Mobile Country Code.
    All usage.served.imsi The IMSI of the device to which the record is attached.
    All usage.served.imei The IMEI of the subscriber.
    All usage.served.msisdn The MSISDN of the subscriber.
    DATA usage.data.volume.uplink The volume of data sent by the system in bytes.
    DATA usage.data.volume.downlink The volume of data received by the system in bytes.
    DATA usage.data.volume.total The total volume of data in bytes for the communication session.
    DATA usage.rounded.data.volume.total The total volume of data in bytes exchanged during the communication session, to which billing increments are applied.
    DATA usage.apn The access point name.
    DATA usage.pdp.address The PDP context IP address.
    DATA usage.rat.type The Radio Access Technology (RAT) at the session start.
    SMS, VOICE usage.peer.msisdn The MSISDN of the peer entity involved in the communication. For a call/SMS initiated by the subscriber (MO), the peer entitee will be the callee, for a call/SMS received by the subscriber (MT), the peer entity will be the caller.
    VOICE usage.rounded.call.duration The duration of the call to which the billing increments are applied.

    SMS MO

    An SMS MO (Mobile-Originated) message is a message that is initiated from the device to the server. The ‘message’ field is encoded in BASE-64 format.

    All events of this kind are identified by its name: event.sms.mo

    Its structure looks like the following:

    {
  "name": "event.sms.mo",
  "date": 1576211024000,
  "content": {
    "source": "882350810180584",
    "company.id": "ab79046811b748ada6bbd1390970c830",
    "encoding": "EightBitASCII",
    "message": "4D4F2054657374203120546875204576656E696E67",
    "destination": "0000000000",
    "system.id": "0c8d4e97ba7b403aa7d1af92d31132ff"
  }
}

    Content Description

    Name Description
    source MSISDN of the device that sent the message
    company.id Company ID to which the device belongs
    encoding Encoding of the message. Can be ‘SevenBitPlain’, ‘SevenBitGSM’, ‘EightBitASCII’, or ‘PlainText’
    message BASE-64 encoded payload
    destination Will always be ‘0000000000’
    system.id AirVantage identifier for the device

    SMS MT Result

    The SMS MT (Mobile Terminated) Result is a message that has the result of a previously-sent MT message from the AirVantage website or the AirVantage API to a device.

    All events of this kind are identified by its name: event.sms.mt.result

    Its structure looks like the following:

    {
  "name": "event.sms.mt.result",
  "date": 1576210918000,
  "content": {
    "message.extid": "67d87978e6274e0fa722c4271f604e2d",
    "source": "0000000000",
    "result.code": 0,
    "company.id": "ab79046811b748ada6bbd1390970c830",
    "source.transaction.id": "none",
    "message": "4D4F2054657374203120546875204576656E696E67",
    "destination": "882350810180584",
    "system.id": "0c8d4e97ba7b403aa7d1af92d31132ff"
  }
}

    Content Description

    Name Description
    message.extid The server-generated unique identifier for the message
    source Will always be “0000000000”
    result.code Conveys the result of the MT operation. A zero indicates success. See table below for possible error codes.
    company.id Company ID to which the device belongs
    source.transaction.id An optional identifier that can be supplied when the MT message is submitted. It is reflected back in this field to allow the original message to be tied to this response.
    message BASE-64 encoded message text
    system.id AirVantage identifier for the device
    destination MSISDN of the device that received the message

    MT Result Codes

    Code Description
    0 Message successfully delivered to the device
    1 UNKNOWN_SUBSCRIBER - the system does not have any information about the device
    5 UNIDENTIFIED_SUBSCRIBER - provisioning issue with the device on the HLR
    6 ABSENT_SUBSCRIBER_SM - HLR indicated device was at a given MSC, but that MSC does not know about the device
    11 TELESERVICE_NOT_PROVISIONED - device is not provisioned for SMS service
    27 ABSENT_SUBSCRIBER - device is either powered off or out of service
    31 SUBSCRIBER_BUSY_FOR_SMS - device may have been sending an MO when message delivery was attempted
    34 SYSTEM_FAILURE - problem within the network trying to deliver the message
    51 RESOURCE_LIMITATION - network issue/congestion
    502 NO_RESPONSE - message was sent, but no response was received from the network

    Binding

    When requesting binding, remote services will be notified for every single event described above. However, it is possible to filter out those events using one of the following properties.

    Property Description
    name Event’s name. When a name is specified, clients are bound only to this event, otherwise any type of event will be received.
    entity Filter events for a given entity. An entity can be an rule uid, an operation uid, or a data path/id.
    system Filter events for a specific system.

    Important: once the binding done, it is not possible to filter events. A new binding has to be requested.

    Depending on the chosen protocol, the binding request is done differently. See the protocol section for more information.

    Data types

    The message contains elements which can be of different types. The two most used ones are INT and STRING.

    Each element either get a static type (i.e.: the “date” is an INT) or a dynamic type.

    Types

    • INT
    • LONG
    • DOUBLE
    • STRING
    • BINARY (base64 encoded)
    • BOOLEAN
    • DATE

    Typing

    Most elements are statically typed, that is the JSON type is directly use (e.g. a String value will be a JSON String). For data send through communications, elements are typed depending the Application Model used by the current system.

    TOP