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

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

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

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

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