Cloud Connectors

HTTP Callback

Many public APIs use callbacks to notify API consumers of specific events. For example, when your devices communicate with AirVantage, an HTTP request is sent to a specified URL to pass information about the status of that communication.

This is a stateless procedure and messages are sent in JSON format with the content-type “application/json”. Messages sent to an unreachable endpoint will be lost.

To receive messages throughout HTTP callbacks, you can contact our support team or use the APIs likely to send messages like:

• alerts by defining a webhook associated to a rule.
• operations when creating an operation like Data export

Google Pub/Sub Connector

The Google Pub sub mechanism is a publish-subscribe connector for applications hosted on the Google Cloud Platform.

AirVantage publishes the new operations status, the alerts and the new raw data in your topic using the fully-documented JSON format below. No password is stored on Sierra Wireless’ side: AirVantage uses IAM authentication. Messages are sent using https. Optimized to handle a high volume of messages (retry mechanism, bulk send). You can easily operate and scale your application. You maintain control over your topic: you can stop or unauthorize Sierra Wireless’s access to your topic at any time using Google Cloud Platform, as explained here .

AWS Kinesis Connector

The AWS Kinesis mechanism is a publish-subscribe connector for applications hosted on the Amazon Web Services Cloud.

AirVantage publishes the new operations status, the alerts and the new raw data in your stream using the fully-documented JSON format below. No password is stored on Sierra Wireless’ side: AirVantage uses IAM authentication.

Messages are sent using https. Optimized to handle a high volume of messages (retry mechanism, bulk send). You can easily operate and scale your application. You maintain control over your topic: you can stop or unauthorize Sierra Wireless’s access to your topic at any time using AWS.

This connector uses a random partition key to evenly spread the load across destination shards.

Why to use Kinesis connector?

Kinesis supplies several great features if you have a huge amount of data to send but on the other hand, it can be complex to implement. Here some tips to help you to make your choice. Select kinesis if:

• High Pace of data: you have a high pace of messages to receive and to process (counting, aggregating and filtering) on the fly as a FIFO. You can have multiple producers and multiple consumers, each one can process the same data for its own use: storing, dashbording, … Each application can re read the messages within 24 hours.
• Data processing: you want to process your data or a subset of data to generate analytics. Kinesis allows you to store your data on a single machine according to a criteria to filter them: these data will be fully available and your processing will be more efficient.
• Acknowledgement: Your application will acknowledge a set of messages. If no acknowledgement has been done, all the messages from the previous acknowledgement will be sent again, your application may received some messages twice and so deal with them.

Using Firehose connector, you can send event to some third party tool like QLikview, Splunk, …

Configuration

Go to the Kinesis Howto for a full description about how to configure the Kinesis Stream connector.

Go to the Firehose Howto for a full description about how to configure the Kinesis Firehose connector.

Resources

• We supply tutorial to help you to configure and use these connectors here
• Have a look to this getting started to start with Kinesis.
• This connector supplied by AWS will help you to consume your data easily and store it (for example in S3 data storage). You may want to use Amazon Firehose as well.

Microsoft Azure EventHub Connector

The Mircosoft Azure EventHub stream is a producer-consumer connector for applications hosted on the Microsoft Azure Services Cloud.

AirVantage publishes the new operations status, the alerts and the new raw data in your stream using the fully-documented JSON format . No password is stored on Sierra Wireless’ side: AirVantage uses a connection string you have to generate in the Microsoft Azure Console in order to give access to AirVantage.

Messages are sent using https. Optimized to handle a high volume of messages (retry mechanism, bulk send), you can easily operate and scale your application, you maintain control over your stream: you can stop or unauthorize Sierra Wireless’s access to your topic at any time using the Microsoft Azure Administration console.

EventHub is limited to event lesser than 256k (see this page , section Batch event send operations). So you may avoid to push over-sized data.

Other limitations can be applied according to the selected offer (see Event Hubs Pricing page).

Configuration

Have a look to the Azure EventHub Howto for a full description about how to configure this connector.

Resources

• Have a look to this tutorial to start with EventHub
• Getting started with AirVantage & Azure EventHub

MQTT Connector

MQTT is a lightweight publish/subscribe messaging transport protocol.

AirVantage publishes the new operations status, the alerts, the usages and the new messages in your topic using the fully-documented JSON format . Optimized to handle a high volume of messages (retry mechanism). You can easily operate and scale your application. You maintain control over your topic: you can stop or unauthorize Sierra Wireless’s access to your topic at any time using your MQTT broker.

There is no X509 certificate support.

Configuration

Have a look to the MQTT Connector Howto for a full description about how to configure this connector with an MQTT Broker.

Only these information are needed:

• TLS activation
• username and password
• hostname (and port number)
• topic
• the list of data path you want to be sent on this queue: empty if no filtering mechanism or a coma-separated list like car1.engine.sparkplug.state, car1.engine.speed to specify the data (contact your support team if you want to activate this option).

This connector must be used with any MQTT broker with a root certificates signed by a certification authority.

Resources

• Getting started with AirVantage MQTT Cloud Connector

AMQP Connector

The Advanced Message Queuing Protocol (AMQP) is an open standard for passing messages between applications. Visit official AMQP site for further information. Currently the version 0.9.1 of the protocol is used.

To connect to the broker you will need some configuration elements in your remote system:

• the host name or IP address of the AMQP broker
• the connection port. Default value is 5671.
• the virtual host, will isolate “environments” (groups of users, exchanges, queues and so on) to ensure that messages are only visible by the right partner.
• the user name
• the password
• the queue name
• the list of data path you want to be sent on this queue: empty if no filtering mechanism or a coma-separated list like car1.engine.sparkplug.state, car1.engine.speed to specify the data (contact your support team if you want to activate this option).

For security reason, SSL and IP white listing are enabled.

AirVantage can provide an AMQP broker for our partners to consume event messages from our server. Configuration elements are provided by Sierra Wireless. Please contact our support team.

Permissions will be set to “basic.get” and “basic.consume” only.

Once your connection established to your AMQP broker, it will remain alive. All messages put into the queue will be available for a week. After this period the messages will expire if they are not consumed.

The standard operating mode of AMQP message consumption is a “Push” mode. Once the remote system is connected to the broker and bound to a queue, any new message will be received automatically.

During the message consumption by a remote service, the message needs to be acknowledged. Each time a message is acknowledged, it will be removed definitively from the queue. If a message is consumed but not acknowledged, it will be put back in the queue and then available again.

Tip: avoid using the client API “auto acknowledgment” system.

See the sample code with a tutorial and read it carefully to know all the best practices.

Server Sent Events

Server-sent events (SSE) is a standard commonly used to send continuous data streams to a client once an initial connection has been established. An SSE event stream is delivered as a streaming HTTP response: the client initiates a regular HTTP request, the server responds with a custom “text/event-stream” content-type, and then streams the UTF-8 encoded event data.

Event payload is the value of one or more adjacent data fields. Event boundaries are marked by newlines.

data: a message payload
data: part of the same message

data: a new message payload after a newline

AirVantage defines an API below for opening an HTTP connection for receiving notification. You can find more information about SSE here .

API

/v1/events/stream

Uses Server Sent Events technology to send AirVantage Events through one single stream. As long as the socket is not closed, the server will stream events as they are raised.

Parameters

Name	Description	Use	Default	Type	Operand
name	The events unique name. Only events of this type will be received.	optional		string	=
entity	Filter events for a given entity. An entity can be an AlertRule uid, an Operation Uid, or a system data path/id.	optional		uid string	=
system	Filter events for a specific system.	optional		uid string	=
company	The context company.	optional	user’s company	uid string	=

Additional Information

Parameter	Description
HTTP Method	GET
Requires Authentication	Yes
Rate Limited	Yes
Headers	None
Permissions	server.notifications

Example

• Request

GET https://eu.airvantage.net/api/v1/events/stream

• Response

200 OK

HTTP/1.1 200 OK
Content-Type: text/event-stream