Live Objects - complete developer guide

Creation

When creating a campaign, the user must provide the following information:

name: A short name to identify the campaign
description: (optional) Detailed description of the campaign
options: (optional) Set of campaign options.
planning: The scheduling configuration including the start date and the end date for the campaign
targets: Devices targeted: either idList or filterQuery (exclusively). cf. Campaign targets
operations: A sequence of operations that will be executed on each device of the campaign.

Campaigns are created from the REST API by providing a campaign definition with properties described previously.

Campaigns management are available for all types of devices (MQTT, LoRa®, SMS, LwM2M and External connector), for all connectivity, however you must take into consideration the capabilities and the conformity of the configurations, commands and resource that you push in your campaigns. Make sure that the devices support the requests that you send through connectors and through the networks. For normal use, only one connectivity is targeted by the filters or by the list of device id’s.

Options

Campaign options section could be empty or omitted.

Example of campaign options:

"options": {
    "dynamicallyAddEligibleDevice": true
  }

Options are:

dynamicallyAddEligibleDevice (default: false).
- Set this option to true to dynamically enroll devices to the campaign. During the campaign planning, new or updated devices could be dynamically enrolled if they match the filterQuery.
- This option requires a filterQuery target definition.
- A campaign with dynamicallyAddEligibleDevice option will always be in running state until end date,

whereas others (non-dynamics) campaigns could end as soon as all devices operations ended or end date reached.

Operations

A campaign includes one or more operations:

Operation type is directly related to device capabilities.
Operation types are Config, Command, Resource, Twin operations, Twin observations

For each device, operations are executed one after the other, each operation waits for the success of the previous operation.

All operations definitions (except TWIN operations) could embed an optional maxRetry attribute:

default is 0, and max is 5.
In case of operation failure, operation will be retried in the limit of maxRetry.

If an operation fails after maxRetry attempts (or is canceled) for a device, the remaining operations are not executed for this device and the sequence ends in failure (or in canceled status).

Config operation

Example of config operation definition:

  {
     "action":"configure",
     "definition":{
        "assetParameters":{
           "param1":{
              "type":"INT32",
              "valueInt32":1234
           }
        },
        "maxRetry": 1
     }
  }

action

configure action will send to the device one or many "parameters" to update.

definition

assetParameters has the same format as the corresponding unitary device management operation: Device configuration.
maxRetry (optional) defines how many retries should be executed in case of failure of the current operation.

The following table shows how the config operation statuses are converted into sequence statuses

Config operation status

Resulting status in the sequence

PENDING

if it is the first operation: PENDING, if not: IN_PROGRESS

SENT

IN_PROGRESS

CANCELED

if it is the last operation: SUCCESS, if not: PENDING and the sequence moves onto the next operation

FAILED

FAILURE

Command operation

Example of command version 1 operation definition:

  {
    "action":"command",
    "version":1,
    "definition":{
      "request": {
        "connector": "mqtt",
        "value": {
          "req": "rebootV1",
          "arg": {
             "delay": 1000
          }
        }
      },
      "policy": {
        "expirationInSeconds": 120,
        "ackMode": "APPLICATIVE"
      },
      "maxRetry": 0
    }
  }

action

command action will register (and send) a command to the device.

definition

this section uses the same format as the corresponding unitary device management operation: Commands.
maxRetry (optional) defines how many retries should be executed in case of failure of the current operation.

The following table shows how the command operation statuses are converted into sequence statuses

Command operation status

Resulting status in the sequence

PENDING

if it is the first operation: PENDING, if not: IN_PROGRESS

PROCESSING

IN_PROGRESS

PROCESSED

if it is the last operation: SUCCESS, if not: PENDING and the sequence moves onto the next operation

CANCELED

ERROR

FAILURE

EXPIRED

FAILURE

UNKNOWN

FAILURE

Resource update operations

Campaign supports both resource update operations:

Resource operation setting a target version

Example of resource operation definition:

{
  "action": "resource",
  "definition": {
    "resourceId": "X11_firmware",
    "targetVersion": "2.1",
    "maxRetry": 4,
    "metadata" : {
        "secured" : true
    }
  }
}

action

resource action will set a device resource requested version (an update request is sent to the device when the device become capable).

definition

resourceId identifies the resource to update.
targetVersion is the new version of the resource to download and install. Aliases can also be used but the resolution of the version will be made for each operations when sent to the Device Manager. In other words, modifications on an alias that is used in a running campaign can affect the target version of the campaign.
maxRetry (optional) defines how many retries should be executed in case of failure of the current operation.
metadata (optional) is the metadata associated with this resource update request.

Resource operation creating an update

Example of resource-update operation definition:

{
  "action":"resource-update",
  "definition": {
    "resourceId": "F500 Dev FirmwareLWM2M",
    "requestedVersion": "v2",
    "connector": "lwm2m-updater",
    "maxRetry": 4,
    "metadata" : {
        "color" : "blue"
    }
  }
}

action

resource-update action will create a resource update of to the device.

definition

resourceId identifies the resource to update.
requestedVersion is the new version of the resource to download and install.
connector (optional) is the Updater to use for the resource update. When not set, the resource related updater is used, else the default updater is used.
maxRetry (optional) defines how many retries should be executed in case of failure of the current operation.
metadata (optional) is the metadata associated with this resource update request.

Resource operations statuses

The following table shows how the resource operation statuses are converted into sequence statuses

Resource operation status

Resulting status in the sequence

PENDING

if it is the first operation: PENDING, if not: IN_PROGRESS

PREPARING_CONNECTOR

if it is the first operation: PENDING, if not: IN_PROGRESS

PREPARING_ASSET

IN_PROGRESS

WAITING_TRANSFER_INFO

IN_PROGRESS

TRANSFER_PENDING

IN_PROGRESS

TRANSFER_IN_PROGRESS

IN_PROGRESS

TRANSFER_SUCCESS

IN_PROGRESS

DONE

if it is the last operation: SUCCESS, if not: PENDING and the sequence moves onto the next operation

ERROR

FAILURE

CANCELED

LwM2M Twin operations

Campaign supports all Twin operations.

LwM2M Twin READ operation

Example of twin read operation definition:

  {
    "action": "twin-operation",
    "definition": {
      "type": "READ",
      "paths": [
        "/5"
      ],
      "policy": {"attempts" : 2}
    }
  }

action

twin-operation action will send a TWIN operation request to the device.

definition

type READ : order the device to report some attributes.
paths Target paths of related device objects or attributes.
policy.attempts (optional) defines the maximal number of attempts until the operation is successfully completed

LwM2M Twin EXECUTE operation

Example of twin execute operation definition:

  {
    "action": "twin-operation",
    "definition": {
      "type": "EXECUTE",
      "paths": [
        "/1/0/8"
      ],
      "policy": {"attempts" : 1}
    }
  }

action

twin-operation action will send a TWIN operation request to the device.

definition

type EXECUTE : execute some attributes.
paths Target paths of related device objects or attributes.
policy.attempts (optional) defines the maximal number of attempts until the operation is successfully completed

LwM2M Twin WRITE operation

Example of twin write operation definition:

  {
    "action": "twin-operation",
    "definition": {
      "type": "WRITE",
      "writeMode": "REPLACE",
      "paths": [
        "/1/0"
      ],
      "values": [
        {
          "path": "/1/0/7",
          "value": "sampleD"
        },
        {
          "path": "/1/0/11/2",
          "value": "sampleE"
        },
        {
          "path": "/1/0/11/0",
          "value": "sampleF"
        }
      ],
      "policy": {"attempts" : 3}
    }
  }

action

twin-operation action will send a TWIN operation request to the device.

definition

type WRITE : update or replace some object attributes values.
paths Target paths of related device objects or attributes.
options Options of Twin Operation, cf. Operation options section.
values Values to set.
policy.attempts (optional) defines the maximal number of attempts until the operation is successfully completed

LwM2M Twin WRITE METADATA operation

Example of twin write metadata operation definition:

  {
    "action": "twin-operation",
    "definition": {
      "type": "WRITE-METADATA",
      "values": [
        {
          "path": "/1/0/7",
          "metadata": [
            {
              "name": "pmin",
              "value": "20"
            },
            {
              "name": "gt",
              "value": "50"
            },
            {
              "name": "lt"
            }
          ]
        }
      ],
      "policy": {"attempts" : 5}
    }
  }

action

twin-operation action will send a TWIN operation request to the device.

definition

type WRITE-METADATA : update metadata (set, update, reset).
values Values to set.
policy.attempts (optional) defines the maximal number of attempts until the operation is successfully completed

LwM2M Twin operation statuses

The following table shows how the twin operation statuses are converted into sequence statuses

Twin operation status

Resulting status in the sequence

PENDING

if it is the first operation: PENDING, if not: IN_PROGRESS

SENT

IN_PROGRESS

RETRYING

IN_PROGRESS

CANCELED

EXPIRED

FAILURE

FAILED

FAILURE

if it is the last operation: SUCCESS, if not: PENDING and the sequence moves onto the next operation

LwM2M Twin observations

LwM2M Twin add observation

Example of twin add observation definition:

  {
    "action": "twin-add-observation",
    "definition": {
      "paths": [
        "/1",
        "/3/0",
        "/3442/0/110",
        "/3442/0/1110/0"
      ],
      "name": "myObservation"
    }
  }

action

twin-add-observation action will send a TWIN add observation request to the device.

definition

paths Paths of attribute, attribute instance, object instance or all the object instances of an object to observe.
name customized name for the observation

The following table shows how the Twin add observation statuses are converted into sequence statuses

Twin observation status

Resulting status in the sequence

PENDING

if it is the first operation: PENDING, if not: IN_PROGRESS

FAILED

FAILURE

OBSERVING

if it is the last operation: SUCCESS, if not: PENDING and the sequence moves onto the next operation

LwM2M Twin clear observations

Example of twin clear observations definition:

  {
    "action": "twin-clear-observations"
  }

action

twin-clear-observations action will send a TWIN clear observation request to the device.

Campaign target (idList)

Campaign devices targets: either idList or filterQuery (exclusively).

idList is a flat list of devices identifiers.

Devices are identified using a URN identifier.

The format of this identifier must be urn:lo:nsid:{ns}:{id} with

ns the target device identifier namespace
id the target device identifier

idList is not compatible with dynamicallyAddEligibleDevice option.

Below is an example of campaign targets definition using idList:

   "targets":{
      "idList":[
         "urn:lo:nsid:namespace:device1",
         "urn:lo:nsid:namespace:device2"
      ]
   }

Campaign target (filterQuery RSQL)

filterQuery: Device filter expression to target devices using RSQL notation. Supported device properties are tags, properties, groupId,groupPath, connector . Supported RSQL operators are ==, !=, =in=, =out=, =lt=, =le=, =gt=, =ge=, and, or.

Below is an example of campaign targets definition using filterQuery:

  "targets": {"filterQuery": "groupPath==/"}

Table 1. RSQL Semantic Table
desc	syntax
Logical AND	; or and
Logical OR	, or or
Equal to	==
Not equal to	!=
Less than	=lt= or <
Less than or equal to	=le= or ⇐
Greater than operator	=gt= or >
Greater than or equal to	=ge= or >=
In	=in=
Not in	=out=

Below are example of filterQuery values.

Filter using tags

tags=in=(FUT,TEST1)

For example, devices with at least tags "FUT" and "TEST1" whatever the order or additional tags

Filter on properties

properties.mykey=in=(enum1, enum3)
properties.mykey==toto

Filter on groups

groupId=in=(1224,1234)
groupId==1234
groupPath=in=(/FR, /EN)

Filter on connector

connector==lwm2m

Filter with and and or conditions :

groupPath==/France;tags==demo;connector==lwm2m or (connector==x-connector)

For example, devices having /France as path and demo in tags, and (lwm2m or x-connector) as connector

Campaign creation examples

Below are examples of campaign definition:

Set parameter "param1" to value 1234 on two devices

POST /api/v0/deviceMgt/campaigns

{
   "name":"campaign1",
   "description":"A campaign that configures parameters",
   "planning":{
      "startDate":"2017-07-01T00:00:00Z",
      "endDate":"2017-07-23T23:59:59Z"
   },
   "targets":{
      "idList":[
         "urn:lo:nsid:namespace:device1",
         "urn:lo:nsid:namespace:device2"
      ]
   },
   "operations":[
      {
         "action":"configure",
         "definition":{
            "assetParameters":{
               "param1":{
                  "type":"INT32",
                  "valueInt32":1234
               }
            }
         }
      }
   ]
}

Send a reset command with a delay parameter for devices with foo tag

POST /api/v0/deviceMgt/campaigns

{
   "name":"campaign2",
   "description":"A campaign that sends a command",
   "planning":{
      "startDate":"2017-07-01T00:00:00Z",
      "endDate":"2017-07-23T23:59:59Z"
   },
   "options": {
    "dynamicallyAddEligibleDevice": true
   },
   "targets": {"filterQuery": "tags=in=(foo)"},
   "operations":[
      {
         "action":"command",
         "definition":{
            "event":"reset",
            "data":{
               "delay":"5000"
            }
         }
      }
   ]
}

Update the resource firmware.bin to version 1.1 (with 2 retries max)

POST /api/v0/deviceMgt/campaigns

{
   "name":"campaign3",
   "description":"A campaign that updates a resource",
   "planning":{
      "startDate":"2017-07-01T00:00:00Z",
      "endDate":"2017-07-23T23:59:59Z"
   },
   "targets":{
      "idList":[
         "urn:lo:nsid:namespace:device1",
         "urn:lo:nsid:namespace:device2"
      ]
   },
   "operations":[
      {
         "action":"resource",
         "definition":{
            "resourceId":"firmware.bin",
            "targetVersion":"1.1",
            "maxRetry": 2,
            "metadata" : {
                 "secured" : true
            }
         }
      }
   ]
}

Campaign reporting

Once a campaign is created, a fleet manager can monitor the state of a campaign.

A campaign can have one of the statuses described below:

SCHEDULED: The campaign has not yet started
RUNNING: The campaign is in progress
COMPLETE: The campaign is finished and all devices ended their sequence in success
INCOMPLETE: The campaign is finished but some devices could not be configured
SERVER_ERROR: An internal error occurred in the platform and the campaign could not be completed
CANCELING: The campaign is waiting for running sequences to end, sequences that have not started yet will not start
CANCELED: The campaign was canceled and some devices might not have been configured

The possible statuses for a device are presented below:

notStarted: No operation executed on the device
pending: The operation is recorded and waiting to be process by the device (soft cancel is still possible)
inProgress: The operation is being processed by the device (soft cancel is no more possible)
success: All operations were successfully executed on the device
failure: One operation of the sequence failed, so the remaining operations (if any) were not executed
canceled: The sequence was canceled before the end of all operations

Campaign cancelation

A campaign can be canceled with the following REST API endpoint:

PUT /api/v0/deviceMgt/campaigns/{campaignId}/cancel

If the campaign is already running, canceling it will set its state to CANCELING and the campaign will cancel pending sequences and wait for in progress sequences to end. Then the campaign state will switch to CANCELED.

To abort in progress sequences, the force flag can be used.

PUT /api/v0/deviceMgt/campaigns/{campaignId}/cancel
force = true

Campaign deletion

A campaign can be deleted with the following REST API endpoint:

DELETE /api/v0/deviceMgt/campaigns/{campaignId}

If the campaign is in RUNNING or CANCELING state, it cannot be deleted. In this case the force flag can be used to execute a forced cancelation and automatically delete the campaign once it is in CANCELED state.

DELETE /api/v0/deviceMgt/campaigns/{campaignId}
force = true

Global report

The global report indicates the campaign definition, the current status of a campaign and statistics about the number of devices with a given status.

Get global status of a speficied campaign

GET /api/v0/deviceMgt/campaigns/{campaignId}

{
   "name":"campaign1",
   "description":"A campaign that configures parameters",
   "planning":{
      "startDate":"2017-07-01T00:00:00Z",
      "endDate":"2017-07-23T23:59:59Z"
   },
   "targets":{
      "idList":[
         "urn:lo:nsid:namespace:device1",
         "urn:lo:nsid:namespace:device2"
      ]
   },
   "operations":[
      {
         "action":"configure",
         "definition":{
            "assetParameters":{
               "param1":{
                  "type":"INT32",
                  "valueInt32":1234
               }
            }
         }
      }
   ],
   "numberOfTargets":2,
   "totalTargetsPerStatus":{
      "notStarted":0,
      "pending":0,
      "inProgress":1,
      "failed":0,
      "success":1,
      "canceled":0
   },
   "campaignStatus":"RUNNING",
   "created":"2017-06-01T00:00:00Z",
   "updated":"2017-07-01T00:00:00Z"
}

Detailed report

The detailed report gives the status of each device in a campaign. The status property gives the status for the whole sequence of operations. The detailed report also indicates the status of each operation (operation reports are ordered just like in the campaign definition).

operationStatus

Exact status reported by the device manager (the list of possible values depends on the type of operation). A special value notStarted is used when the operation is not yet started.

operationId

Identifier returned by the device manager when the campaign manager created the operation

started

Date when the operation was started

updated

Last time the operation report was updated

ended

Date when the operation was finished

currentRetry

(Option) Retry attempt count of the latest operation executed.
For example, an operationStatus equals to OK (or DONE) and currentRetry equals to 1 means that operation first failed, but the first retry attempt was a success.

Get global status of a speficied campaign

GET /api/v0/deviceMgt/campaigns/{campaignId}/targets

{
   "page":0,
   "size":10,
   "totalCount":2,
   "data":[
      {
         "device":"urn:lo:nsid:namespace:id1",
         "status":"inProgress",
         "created":"2017-07-01T16:12:21.000Z",
         "updated":"2017-07-01T16:12:21.000Z",
         "operations":[
            {
               "action":"configure",
               "operationStatus":"OK",
               "started":"2017-07-01T16:20:21.000Z",
               "updated":"2017-07-01T16:25:21.000Z",
               "ended":"2017-07-01T16:25:21.000Z"
            },
            {
               "action":"command",
               "operationStatus":"SENT",
               "operationId":"12345",
               "started":"2017-07-01T16:30:21.000Z",
               "updated":"2017-07-01T16:31:21.000Z"
            },
            {
               "action":"resource",
               "operationStatus":"notStarted"
            }
         ]
      },
      {
         "device":"urn:lo:nsid:namespace:id2",
         "status":"success",
         "created":"2017-07-01T16:12:21.000Z",
         "updated":"2017-07-01T16:12:21.000Z",
         "operations":[
            {
               "action":"configure",
               "operationStatus":"OK"
               "started":"2017-07-01T16:20:21.000Z",
               "updated":"2017-07-01T16:25:21.000Z",
               "ended":"2017-07-01T16:25:21.000Z"
            },
            {
               "action":"command",
               "operationStatus":"PROCESSED",
               "operationId":"6789",
               "started":"2017-07-01T16:30:21.000Z",
               "updated":"2017-07-01T16:31:21.000Z"
            },
            {
                "action": "resource",
                "operationStatus": "DONE",
                "operationId": "X11_firmware",
                "started": "2017-07-01T16:30:21.000Z",
                "updated": "2017-07-01T16:38:21.000Z",
                "ended": "2017-07-01T16:38:21.000Z",
                "currentRetry": 1
            }
         ]
      }
   ]
}