How to manage an upgrade campaign with the AirVantage API

An upgrade campaign defines the different steps required to go from a configuration A of a system to a configuration B. There are simple campaigns where only one component needs to be upgraded (custom application or firmware) and complex campaigns appears when both components need to be upgraded. Before starting your campaign, you have to identify all steps and write down a procedure. Upgrade campaigns are usually a repetition of simple steps, it is important to write down a procedure to avoid forgetting steps. To perform an upgrade campaign, you must:

1. Authenticate
2. Select devices you want to upgrade,
3. Create upgrade batches,
4. Perform upgrade and retries,
5. Write a report
6. Clean AirVantage

All these steps are described below.

1 / Basics

2 / Prepare

3 / Upgrade

4 / Report & clean

Basics

IoT Platform System

The central entity in AirVantage is the system. A system is the combination of a firmware (application), connected device (hardware) and a subscription (SIM). All sub-items are optional (a system can just include a subscription or just a gateway).

AirVantage APIs overview

Every feature of AirVantage User Interface is available through APIs.

Before starting with this tutorial, you may have a look to the folowing documentation:

• Getting started with the AirVantage APIs
• AirVantage APIs documentation

In order to be able to use APIs, an API client must be registered in AirVantage which is explained in the How to create a new API client?

Prepare your campaign

First, we prepare the campaign by the authentication and then we identify the list of systems to be upgraded and finally create the batch.

Authentication

Step 1. First get an access token using Resource owner flow:

URL:

> POST https://eu.airvantage.net/api/oauth/token

Header:

Content-type : application/x-www-form-urlencoded

Body:

grant_type=password&username={{username}}&password={{password}}&client_id={{client_id}}&client_secret={{client_secret}}

Response:

{
  "access_token": "o9GLplDRn3AVRyBnZOb1X-EBBvhWDOz4QnwsvSCvhCv9M-5K_yOfVzq5qiE0ACzbgzfNUjM7241MdSFNcb-wjw",
  "expires_in": 86008,
  "token_type": "Bearer",
  "refresh_token": "KQ4kpSSCH7qlNjvrnj3HosmsJ-IuxJ4qTfORp6rv0nK-uULBTzs9G6T5vVyXE5vzlQvndf_yV71D0lPqZUDhLg“
}

Improve the security

Step 2. Then use this access token in all your APIs calls:

URL:

> GET https://eu.airvantage.net/api/v1/applications?name=myApplication

Header:

Authorization: bearer {{accessToken}}

Find your systems to upgrade

Step 1. Find systems with a specific label:

URL:

> GET https://eu.airvantage.net/api/v1/systems?fields=uid,name,gateway&labels={{my_label}}

Header:

Authorization: bearer {{accessToken}}

Step 2. Find systems with an application:

URL:

> GET https://eu.airvantage.net/api/v1/systems?application=name:myApps&fields=uid,name,gateway

Header:

Authorization: bearer {{accessToken}}

Note: When you want to perform a complex campaign, divide it in several simple campaigns, for example you want to upgrade firmware and custom software, perform first the firmware upgrade campaign, and then the custom application upgrade campaign.

Identify your batch

To easily find systems later put a label by selecting all devices (1) and choose the “change label” feature. For such campaign the label’s name can be: tmp_XXXX_YYYY where:

• XXXX is the campaign name and date
• YYYY is the name of the person in charge of the campaign.

URL:

> PUT https://eu.airvantage.net/api/v1/systems/1cc562f8ec1340e79214f2113db751f6 

Header:

Authorization: bearer {{accessToken}}
Content-Type: application/json

Body:

{
  "labels" : ["tmp_fota_me", "working"]
}

Batch Creation

We advise to perform upgrade campaign by batch. A good practice is to create a first batch of 10 devices to test the complete procedure then a batch 50 devices and finally batches of 100 devices. To test your campaign, it’s easier to start with device communicating regularly, so choose devices with a recent “Last Communication Date”. To create a batch, select the X systems you want to upgrade and put a label on them. Use a label tmp_XXXX_YYYY_batchZZZZ where:

• XXXX is the campaign name and date
• YYYY is the name of the person in charge of the campaign.
• ZZZZ is the batch creation date and number

Launch your campain

First, we prepare the campaign by authenticating, identify the list of systems to be upgraded and create a batch.

Create the campaign

Select all devices on the batch you want to upgrade and create an “Upgrade Firmware” or an “Install Application” operation on the whole batch:

Step 1. Get the FW application

URL:

> GET https://eu.airvantage.net/api/v1/application?name=myApps&fields=uid,name 

Header:

Authorization: bearer {{accessToken}}

Body:

{
  "items": [ { 
    "uid": "08fc7db9841945df8ffa647165bb57e6", 
    "name": "ALEOS GX400", 
    "revision": "4.2.5.005", 
    "type": "ALEOS.PROD.12", 
    "category": "FIRMWARE", 
    "state": "RELEASED" }],
  "count": 1, "size": 1, "offset": 0
}

This API returns the application uuid to be used in the next step.

Step 2. Upgrade the systems. Declare the application uuid in the body.

URL:

> POST https://eu.airvantage.net/api/v1/operations/systems/applications/install

Header:

Authorization: bearer {{accessToken}}
Content-Type: application/json

Body:

{ "application" : "08fc7db9841945df8ffa647165bb57e6", "systems": { "label":" tmp_fota_me" } }

Response:

HTTP/1.1 200 OK
Content-Type: application/json
...
{ "operation":"4b89657f63aac4b299c1d46e98a495326" }

This API returns the operation uuid which can be used with other API later.

Note: An operation is created and you can see it in the “Monitoring/Operation” tab in AirVantage.

Get the status of the campaign

This API uses the previous result (operation uuid) to get more information about the operation we have just created.

URL:

> GET https://eu.airvantage.net/api/v1/operations/4b89657f63aac4b299c1d46e98a495326 

Header:

Authorization: bearer {{accessToken}}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
...
{ 
    "uid": "4b89657f63aac4b299c1d46e98a495326", 
    "state": "FINISHED",
    "category": "TASK",
    "entity": "GATEWAY",
    "type": "IMPORT",
    "startDate": 1362489511437,
    "endDate": 1362489512865, 
    "counters": [ { "state": "PENDING", "count": 0 }, { "state": "IN_PROGRESS", "count": 0 }, { "state": "CANCELLED", "count": 0 }, 
    { "state": "FAILURE", "count": 0 }, { "state": "SUCCESS", "count": 2 } ], 
   "total": 2, "target": null, "targetCount": 2, …
}

Retry an operation

If needed, you can retry a previous operation identified with its uuid. A new operation is created with a new uuid in the response (like Operation creation).

URL:

> POST https://eu.airvantage.net/api/v1/operations/4b89657f63aac4b299c1d46e98a495326/retry 

Header:

Authorization: bearer {{accessToken}}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
...
{ "operation":"848d850a92994b089db07b3848faa6d4" }

Report & clean

OK! So now you launch the campign. It is time to have a status and clean it up once the campaign is finalized

Create a report

A report could ease your upgrade campaign. This report will contain:

1. the different steps of your campaign,
2. for each steps the different states of your systems,
3. for each states an action to perform.

Example of an illustrated report, each states and steps can be more described in a document:

Clean

At the end of the campaign you have to:

1. Remove temporary labels linked to the campaign,
2. Delete application not used anymore.