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

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 7 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 Incoming Events: Sent every time a system communicates. Its type name is event.system.incoming.communication.
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

Incoming Communication

This event is raised every time a system communicates with the server. This event exposes the data sent by the system during this communication.

All events of this kind are identified by its name: event.system.incoming.communication

Data content may look different depending on the timestamps sent through the communication. Some protocols sent their data timestamped values. In this case the structure will look like the following:

{
   "name" : "event.system.incoming.communication",
   "date" : 1403793930523,
   "content" : {
      "system.id" : "f89476adad3b4cad97b1ac0a8fe1bf44",
      "communication.id" : "CA6598741255",
      "message.id" :"3355fd07d0314e8792015192271895e4",
      "14037939309874" : {"int.variable.path" : 984, "double.variable.path" : 985.32},
      "14037939654125" : {"string.variable.path" : "value"},
      "14037939965217" : {"boolean.variable.path" : true, "binary.variable.path" : "NTQ2ODY5NzMyMDYxMjA2MjY5NmU2MTcyNzkyMDczNzQ3MjY5NmU2Nw=="}
   }
}

Other protocols just sent path/values couples without a timestamp. In that case the structure is like :

{
   "name" : "event.system.incoming.communication",
   "date" : 1403793930523,
   "content" : {
      "system.id" : "f89476adad3b4cad97b1ac0a8fe1bf44",
      "communication.id" : "CA6598741255",
      "message.id" :"3355fd07d0314e8792015192271895e4",     
      "int.variable.path" : 984,
      "double.variable.path" : 985.32,
      "string.variable.path" : "value",
      "boolean.variable.path" : true,
      "binary.variable.path" : "NTQ2ODY5NzMyMDYxMjA2MjY5NmU2MTcyNzkyMDczNzQ3MjY5NmU2Nw=="
   }
}

Content description

Name	Description
system.id	Unique identifier of the communicating system. It always comes first within the content payload.
communication.id	Next to the system identifier you will have the communication identifier used by the system to connect with AirVantage.
message.id	You also will have the communication message unique identifier.
variable paths/ids	Finally we find as much as Key/Value pairs of variables sent through this communication. Keys are the variable paths/ids. Notice that values inside the JSON structure keep dataTypes. Only binary values are shown as a Base64 string.

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

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

Matching results

Overview

Incoming Communication

Operation State Change

Operation Task State Change

Alert Triggered

Usage Record Imported

SMS MO

SMS MT Result

Binding

Data types

Types

Typing