Campaign Management APIs

Create Campaign

Required Permissions: You must have the Create Campaign permission to perform this operation.
API: /api/campaigns

Method

POST

Required Parameters


Name	Description
name `string`	Name of the campaign.

Input Example

{
            "name": "string",
            "description": "string",
            "packages": [
              "string"
            ],
            "campaignSettings": {
              "settings": {
                "additionalProp1": "string",
                "additionalProp2": "string",
                "additionalProp3": "string"
                                }
                          }
          }

Response

{
  "uuid": "string"
}

Edit Campaign

Required Permissions

You must have the Edit Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}

Method

PUT

Required Parameters


Name	Description
name `string`	Name of the campaign.
description `string`	Campaign description.
packages `string`	Update packages for the campaign.
campaignSettings `string`	Campaign setting specifications.
campaignId `string`	ID for the campaign.

Input Example

{
  "updateSpec": {
    "name": "string",
    "description": "string",
    "packages": [
      "string"
    ],
    "campaignSettings": {
      "settings": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  },
  "campaignId": "string"
}

Response

{
  "uuid": "string"
}

Delete Campaign

Required Permissions

You must have the Delete Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}

Method

DELETE

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Response

{}

Get Campaign

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}

Method

GET

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Response

{
  "status": "string",
  "name": "string",
  "creationTime": "string",
  "packages": {
    "packages": [
      "string"
    ]
  },
  "id": "string",
  "description": "string"
}

Start Campaign by ID

Required Permissions

You must have the Start Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/start

Method

PUT

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Input Example

{
  "campaignId": "string"
}

Response

{}

Stop Campaign by ID

Required Permissions

You must have the Stop Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/stop

Method

PUT

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Input Example

{
  "campaignId": "string"
}

Response

{}

Approve Campaign by ID

Required Permissions

You must have the Approve Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/approve

Method

PUT

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Input Example

{
  "campaignId": "string"
}

Response

{}

Register Completed Callback

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Register a completed callback. The callback runs after the OTA process ends for the campaign, and after adding every gateway to the campaign.

API

/api/campaigns/{campaign_id}/callbacks/completed

Method

PUT

Required Parameters


Name	Description
notificationDestinationId `string`	callback destination.
campaignId `string`	ID of the campaign.

Input Example

{
  "notificationDestinationId": "string",
  "campaignId": "string"
}

Response

{}

Register Wake Up Callback

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Register a wake up callback. The callback is triggered whenever the server components need to notify a gateway about running a command. The gateway receives the notification and poll for commands.

API

/api/campaigns/{campaign_id}/callbacks/wake-up

Method

PUT

Required Parameters


Name	Description
notificationDestinationId `string`	callback destination.
campaignId `string`	ID of the campaign.

Input Example

{
  "notificationDestinationId": "string",
  "campaignId": "string"
}

Response

{}

Notify Gateway

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Notify a gateway in the campaign to request or get tasks.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/notify

Method

PUT

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Input Example

{
  "gatewayId": "string",
  "campaignId": "string"
}

Response

{}

Assign Update Packages for the Target Gateway

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Assign Update Packages for a specific gateway to run packages for.

Note: This API will override the globally assigned default campaign packages.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/packages

Method

PUT

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
packages `string`	Update package IDs to be assigned.
campaignId `string`	ID of the campaign.

Input Example

{
  "gatewayId": "string",
  "packages": [
    "string"
  ],
  "campaignId": "string"
}

Response

{}

Get Updated Package Information for the Gateway in the Campaign

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/packages

Method

GET

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Response

{
  "packages": [
    "string"
  ]
}

Get Gateways Added to the Campaign

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices

Method

GET

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Response

{
  "pageResponse": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  },
  "gateways": [
    {
      "gatewayId": "string",
      "state": "string",
      "closed": true
    }
  ]
}

List Campaigns

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns

Method

GET

Optional Parameters


Name	Description
id `string`	Campaign ID.
name `string`	Name of the campaign.
status `string`	Status of the campaign: STARTED CREATED STOPPED APPROVAL_NEEDED APPROVED
preDeliveryCallback `string`	Pre-delivery callback for the campaign.
postDeliveryCallback `string`	Post-delivery callback of the campaign.
description `string`	Description of the campaign.
creationTime `int64`	Campaign creation time.
packages `string`	Package IDs used for campaign updates.

Response

"name" - name-of-the-campaign;
"status"-status-of-campaign (STARTED|CREATED|STOPPED);
"page" - {
          "number" : int32,
          "size" :int32,
          "sort": "sort-direction"
         }

Add Gateways to a Campaign

Required Permissions

You must have the Edit Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices

Method

POST

Required Parameters


Name	Description
gatewayId `string`	List of gateway IDs.
campaignId `string`	ID of the campaign.

Input Example

{
  "gatewayIds": [
    "string"
  ],
  "campaignId": "string"
}

Response

{}

Remove Gateways in a Campaign

Required Permissions

You must have the Edit Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices

Method

PUT

Required Parameters


Name	Description
gatewayIds `string`	List of gateway IDs.
campaignId `string`	ID of the campaign.

Input Example

{
  "gatewayIds": [
    "string"
  ],
  "campaignId": "string"
}

Response

{}

Set Campaign Distribution List

Required Permissions

You must have the Edit Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/distribution-list

Method

PUT

Required Parameters


Name	Description
distributionListId `string`	Distribution list ID.
reevaluationIntervalSeconds `string`	Re-evaluation interval in seconds for the distribution list.
campaignId `string`	ID of the campaign.

Input Example

{
  "distributionListId": "string",
  "reevaluationIntervalSeconds": "string",
  "campaignId": "string"
}

Response

{}

Get Campaign Distribution List

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/distribution-list

Method

GET

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Response

{
  "distributionListId": "string",
  "reevaluationIntervalSeconds": "string",
  "campaignId": "string"
}

Schedule Download

Required Permissions

You must have the Schedule Campaign permission to perform this operation.

Description

Schedule a download of the update packages for a gateway in the campaign.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/scheduled-download

Method

PUT

Required Parameters


Name	Description
begin end `string`	Represents a fixed slice of time where `begin` and `end` are seconds. (UNIX Epoc time with millisecond precision.) `begin`: start of the time period. `end`: End of the time period.
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Input Example

{
  "begin": "string",
  "end": "string"
}

Response

{}

Schedule Activation

Required Permissions

You must have the Schedule Campaign permission to perform this operation.

Description

Schedule activation of the update packages for the gateway in a campaign.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/scheduled-activation

Method

PUT

Required Parameters


Name	Description
begin end `string`	Represents a fixed slice of time where `begin` and `end` are seconds. (UNIX Epoc time with millisecond precision.) `begin`: start of the time period. `end`: End of the time period.
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Input Example

{
  "begin": "string",
  "end": "string"
}

Response

{}

Schedule Execution

Required Permissions

You must have the Schedule Campaign permission to perform this operation.

Description

Schedule execution of the update packages for the gateway in a campaign.

API

api/campaigns/{campaign_id}/devices/{gateway_id}/scheduled-execution

Method

PUT

Required Parameters


Name	Description
begin end `string`	Represents a fixed slice of time where `begin` and `end` are seconds. (UNIX Epoc time with millisecond precision.) `begin`: start of the time period. `end`: End of the time period.
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Input Example

{
  "begin": "string",
  "end": "string"
}

Response

{}

Close Campaign for a Gateway

Required Permissions

You must have the Edit Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/close

Method

PUT

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Input Example

{
  "gatewayId": "string",
  "campaignId": "string"
}

Response

{}

Get Campaign State

Required Permissions

You must have the View Campaign permission to perform this operation.

Description

Get the state of a specific gateway in the campaign.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/state

Method

GET

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Response

{
  "state": "string"
}

Register State Change Callback

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Register a state change callback. The callback runs when there is a change in the state of the gateway in the campaign.

API

/api/campaigns/{campaign_id}/callbacks/state-change

Method

PUT

Required Parameters


Name	Description
`notificationDestinationId`	Notification destination ID.
`campaignId`	Campaign ID.

Input Example

{
  "notificationDestinationId": "string",
  "trackedStates": [
    "string"
  ],
  "campaignId": "string"
}

Response

{}

Register Execution Progress Callback

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Register an execution progress callback. The callback runs when the execution progress is set.

API

/api/campaigns/{campaign_id}/callbacks/execution-progress

Method

PUT

Required Parameters


Name	Description
`notificationDestinationId`	Notification destination ID.
`campaignId`	Campaign ID.

Input Example

{
  "notificationDestinationId": "string",
  "campaignId": "string"
}

Response

{}

Register Download Progress Callback

Required Permissions

You must have the Edit Campaign permission to perform this operation.

Description

Register a download progress callback. The callback runs when the download progress is set.

API

/api/campaigns/{campaign_id}/callbacks/download-progress

Method

PUT

Required Parameters


Name	Description
`notificationDestinationId`	Notification destination ID.
`campaignId`	Campaign ID.

Input Example

{
  "notificationDestinationId": "string",
  "campaignId": "string"
}

Response

{}

Get Execution Progress

Required Permissions

You must have the View Campaign permission to perform this operation.

API

api/campaigns/{campaign_id}/devices/{gateway_id}/progress/execution

Method

GET

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Response

{
  "progress": [
    "string"
  ]
}

Get Download Progress

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/progress/download

Method

GET

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Response

{
  "packagesProgress": [
    {
      "progress": "string",
      "total": "string",
      "id": "string"
    }
  ]
}

Get Active Campaigns for a Gateway

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/devices/{gateway_id}/active-campaigns

Method

GET

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.

Response

{
  "campaignId": [
    "string"
  ]
}

Get Overall Campaign Status

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/status

Method

GET

Required Parameters


Name	Description
campaignId `string`	ID of the campaign.

Response

{
  "status": "string",
  "name": "string",
  "campaignId": "string",
  "numberOfGatewaysInActivationCompleteState": "string",
  "numberOfGatewaysInExecutionCompleteState": "string",
  "creationTime": "string",
  "modificationTime": "string",
  "totalNumberOfGateways": "string",
  "totalNumberOfPackages": "string",
  "numberOfGatewaysInDownloadCompleteState": "string",
  "description": "string"
}

Get Campaign Status Per Gateway

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaigns/{campaign_id}/devices/{gateway_id}/status

Method

GET

Required Parameters


Name	Description
gatewayId `string`	ID of the gateway.
campaignId `string`	ID of the campaign.

Response

{
  "campaignId": "string",
  "campaignState": {
    "state": "string"
  },
  "timestamp": "string",
  "downloadProgress": {
    "packagesProgress": [
      {
        "progress": "string",
        "total": "string",
        "id": "string"
      }
    ]
  },
  "executionProgress": [
    "string"
  ],
  "gatewayId": "string"
}

Get Campaign Count by Status

Required Permissions

You must have the View Campaign permission to perform this operation.

API

/api/campaign-status/campaigns

Method

GET

Required Parameters

None

Response

{
  "aprovedNotStartedCount": "string",
  "startedCount": "string",
  "stoppedCount": "string",
  "waitingApprovalCount": "string",
  "noApprovalNeededReadyToStartCount": "string"
}

Get Package Information

Required Permissions

You must have the View Package permission to perform this operation.

Description

This API provides information about the package.

API

/api/programs/{uuid}/file-info

Method

GET

Required Parameters


Name	Description
uuid `string`	IoTC ID.

Response

{
  "description": "string",
  "id": "string",
  "createdBy": "string",
  "createdOn": "string",
  "name": "string"
}

List Packages

Required Permissions

You must have the View Package permission to perform this operation.

API

/api/programs

Method

GET

Optional Parameters


Name	Description
name `string`	Name of the program.
page `string`	number size sort

Response

{
  "description": "string",
  "id": "string",
  "createdBy": "string",
  "createdOn": "string",
  "name": "string"
}

Delete a Package

Required Permissions

You must have the Delete Package permission to perform this operation.

API

/api/programs/{uuid}

Method

DELETE

Required Parameters


Name	Description
uuid `string`	IoTC ID to delete.

Response

{}

Upload Package Multipart

Required Permissions

You must have the Create Package permission to perform this operation.

Description

Use this API to upload a reprogramming package. The request size is limited to 1 GB. This API consumes only multipart requests.

API

/api/programs/

Method

POST

Required Parameters


Name	Description
file `file`	The file that is being uploaded.

Optional Parameters


Name	Description
description `string`	Description of the uploaded file. Maximum length of characters is 128.

Input Example

Accept "application/zip"
{                 
	   "description": "A"                           
 }

The request is not multipart and its body contains the file.

Response

{
"uuid": "string"
}

Upload Package Streaming

Required Permissions

You must have the Create Package permission to perform this operation.

Description

Use this API to upload a reprogramming package. The request size is unlimited.

API

/api/programs/

Method

POST

Required Parameters


Name	Description
file `file`	The file that is being uploaded.

Optional Parameters


Name	Description
description `string`	Description of the uploaded file. Maximum length of characters is 128.

Input Example

Accept "application/zip"
{                 
	   "description": "A"                           
 }

The request is not multipart and its body contains the file.

Response

{
"uuid": "string"
}

Run a Campaign on Thing Devices

API

/{campaign_id}/devices/things

Method

POST

Parameters


Name	Description
campaign_id `string`	ID of the campaign.
gateway_things `string`	List of connected Thing devices in a gateway.
gateway_id `string`	ID of the gateway.
thing_id `string`	ID of the Thing devices that are connected to the gateway.
state `string`	State of the gateway in a campaign.
not_processed_thing_ids `string`	ID of the connected Thing devices in a gateway that are not processed in the campaign.
closed `boolean`	Denotes that the gateway is closed for updates.
causedBy `string`	Contains the cause of failure if a gateway is in failed state.
download_progress `string`	List of campaigns that are being downloaded.
execution_progress `string`	List of campaigns that are running.
timestamp `string`	Time stamp.

Input Example

{
    "gateway_things": [
        {
            "gateway_id": "gw1_id",
            "thing_ids": [
                "thing1_id",
                "thing2_id"
            ]
        }
    ]
}