Use the following APIs to manage Campaigns.

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"
}