VMware Pulse IoT Center API Reference Guide - VMware Pulse ... · This guide provides information...

VMware Pulse IoT Center API Reference Guide

VMware Pulse IoT Center 2019.16

You can find the most up-to-date technical documentation on the VMware website at:

https://docs.vmware.com/

If you have comments about this documentation, submit your feedback to

[email protected]

VMware, Inc.3401 Hillview Ave.Palo Alto, CA 94304www.vmware.com

Copyright © 2020 VMware, Inc. All rights reserved. Copyright and trademark information.


VMware, Inc. 2

https://docs.vmware.com/

mailto:[email protected]

http://pubs.vmware.com/copyright-trademark.html

Contents

1 About the VMware Pulse IoT Center API Reference Guide 6

2 Introduction to the API 7User Authentication 8

Device Authentication 9

HTTP Response Codes 11

API Headers 11

Restricted Characters 12

3 Server APIs 13Device Management APIs 13

Campaign Management APIs 54

Alerts APIs 77

Identity and Access Management (IAM) APIs 89

Organization Management APIs 89

User Management APIs 92

Role Management APIs 97

Group Management APIs 101

Permission Management APIs 105

Organization Settings APIs 106

Password Management APIs 108

Token Management APIs 109

Notification APIs 110

Notification Definition APIs 110

Notification Instances APIs 121

System Notification APIs 123

Certificate Management APIs 125

Advanced Search APIs 134

Advanced Search APIs Sample Use Case 151

Metric APIs 154

Audit APIs 156

4 Agent APIs 159Data Structures 159

IotcApplicationId 159

IotcAllowedMetricInfo 159

IotcAllowedMetricSet 160

IotcBooleanValue 160

VMware, Inc. 3

IotcCampaignCallbacks 160

IotcCampaignId 161

IotcCampaignScheduleTimeWindow 161

IotcClientConfig 162

IotcCommand 162

IotcCommandArg 163

IotcCommandResponse 164

IotcDevice 164

IotcDeviceDetails 164

IotcDeviceId 164

IotcDeviceData 165

IotcDeviceSet 165

IotcDeviceDataSet 165

IotcDoubleValue 165

IotcEnrollmentCredentials 166

IotcEnrollmentData 166

IotcEnrollmentRequest 167

IotcEnrollmentResponse 167

IotcGetResponse 167

IotcInt64Value 168

IotcKeyValue 168

IotcKeyValueSet 168

IotcMetric 168

IotcMetricResponse 169

IotcNotificationDefinitionId 169

IotcNotificationResponse 169

IotcPackageId 170

IotcPropertySet 170

IotcSendNotificationRequest 171

IotcStringValue 171

IotcTemplateId 171

IotcUploadFileRequest 172

IotcUserCredentials 172

Functions 172

Iotc_AddMetricData 173

Iotc_AllocatePropertySet 173

Iotc_AllocateProperties 173

Iotc_AllocMetricDataSet 174

Iotc_CampaignScheduleActivation 174

Iotc_CampaignScheduleDownload 175

Iotc_CampaignScheduleExecution 175


VMware, Inc. 4

Iotc_CampaignSetExecutionProgress 176

IotcCommandCb 176

Iotc_Close 176

Iotc_DeletePropertySet 177

Iotc_DeleteProperties 177

Iotc_Enroll 177

Iotc_EnrollConnectedDevice 177

Iotc_FreeMetricDataSet 178

Iotc_GetCertificateIds 178

Iotc_GetCertificateIdsByIssuer 178

Iotc_GetCertificateIdsBySubject 179

Iotc_GetCertificate 179

Iotc_GetPrivateKey 180

Iotc_GetCommands 180

Iotc_GetCustomProperties 181

Iotc_FreeGetResponse 181

Iotc_GetResponseByType 181

Iotc_Sync 182

Iotc_GetDevices 182

Iotc_GetDevicesData 182

Iotc_GetMessageId 182

Iotc_GetResponse 183

Iotc_GetSessionSockfd 183

Iotc_GetSystemProperties 183

IotcSession* Iotc_Init 184

IotcSession*Iotc_InitWithConfig 184

Iotc_InsertProperty 184

Iotc_InsertProperties 184

Iotc_RegisterCampaignCallbacks 185

Iotc_RegisterCommandCallback 185

Iotc_SendMetric 185

Iotc_SendMetricSet 186

Iotc_SendNotification 186

Iotc_SendPropertySet 186

Iotc_UnEnroll 187

Iotc_UploadFile 187

Macro Definitions 187

Enumeration Types 188


VMware, Inc. 5

About the VMware Pulse IoT Center API Reference Guide 1This guide provides information about the Pulse IoT Center REST APIs for Server and Agent.

Intended AudienceThis guide is intended for developers who want to set up their environment to program applications with the VMware Pulse IoT Center APIs.

VMware Developer PublicationsTo view the other VMware API and SDK public documentation, go to http://www.vmware.com/support/developer.

VMware Technical Publications GlossaryVMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions of terms as they are used in VMware technical documentation, go to http://www.vmware.com/support/pubs.

VMware, Inc. 6

http://www.vmware.com/support/developer

http://www.vmware.com/support/developer

http://www.vmware.com/support/pubs

http://www.vmware.com/support/pubs

Introduction to the API 2The VMware Pulse IoT Center API offers a way for third-party systems to interact with VMware Pulse IoT Center.

VMware Pulse IoT Center provides programmable REST APIs to integrate with your existing enterprise solution. With the VMware Pulse IoT Center APIs, you can create, view, edit, and delete various VMware Pulse IoT Center entities such as Devices, Campaigns, Alerts, Notifications, Groups, and Users, programmatically. All the core features of the VMware Pulse IoT Center provide REST APIs.

TerminologyThis document uses the following terms.

API API is an acronym for Application Programming Interface. It is a name used to refer to a special framework some web applications or services provide which allows a user to connect to the system and perform some number of discrete actions such as running functions, requesting data, or updating information.

Call A call is another name for a request or a communication sent by a user to the API, in the form of a URL string, which invokes a specific action on one particular endpoint, and can also include additional parameters or values.

HTTP HTTP is an acronym for Hyper-Text Transport Protocol. It is one of the key architectural components behind how web-based content on the Internet is accessed through web browsers.

JSON JSON is an acronym for JavaScript Object Notation. It is a format for information, based on the JavaScript language, that is intended for consumption by a programmed function.

Method HTTP provides support for four methods which each describe a type of result a user might want to achieve through a given communication with a web server or API. The four methods are: GET (for retrieving data), PUT (for inserting data), POST (for updating data), and DELETE (for removing data).

VMware, Inc. 7

GET GET is one of the four HTTP methods used for retrieving or querying records from a system.

PUT PUT is one of the four HTTP methods used for inserting or creating records into a system.

POST POST is one of the four HTTP methods used for updating existing records in a system.

DELETE DELETE is one of the four HTTP methods used for removing records from a system.

REST REST is an acronym for Representational State Transfer. It is a form of software architecture that is primarily used for designing a web service.

Note The required permissions that are listed for each API are for invoking the API operation. Some APIs require additional permissions to complete the operation.

This chapter includes the following topics:

n User Authentication

n Device Authentication

n HTTP Response Codes

n API Headers

n Restricted Characters

User AuthenticationUse the following APIs to create and issue an authentication token for a user.


VMware, Inc. 8

Create a Token for the User

Header If the user name is available across multiple organizations, enter the following header:

x-org-domain-name:<domain>

API /api/tokens

Method GET

Required Parameters None

Response{

"accessToken": “string”,

"expiresInSecs": "1543317540",

"accessTokenExpiresAt": "1543317540",

"refreshToken": “string”,

"refreshTokenExpiresAt": "1544519940"

}

Issue Access Token Using Refresh Token

API /api/tokens/refresh

Method GET


Response{

"accessToken": "string",

"accessTokenExpiresAt": "1543317540"

"expiresInSecs": 0,

"refreshToken": null

}

Device AuthenticationUse the following APIs to issue device token and device credentials.


VMware, Inc. 9

Create Device Credential

Required Permissions You must have the Create Device Credential permission to perform this operation.

API api/device-credentials/{id}

Method POST

Input Example JWT_NATIVE

{}

PROPERTY_NATIVE

{"requestParams":"{\"DeviceKey\":\"1234\"}"}

TPM_NATIVE

{"requestParams":"{\"tpm_ek\":\"123456\"}"}

Response{

"credentials": "string"

}

Get Device Token

Required Permissions You must have the Get Device Token permission to perform this operation.

API /api/device-tokens

Header x-device-auth

Enter the device credential that you created in the Create Device Credential API.

Method GET

Required Parameters Name Description

id

string

Device ID.

Response{

"deviceId": "string",

"accessToken": "string"

}


VMware, Inc. 10

HTTP Response CodesThe following table lists the response codes used by VMware Pulse IoT Center.

The response codes adhere to the standard HTTP and REST conventions.

Table 2-1. HTTP Status Codes

Status Code Error Message

200 Success.

401 Unauthorized.

403 Permission denied.

404 Not found.

API HeadersAPIs must include the following headers:

API Version

Content-Type: application/json

Accept: application/json;api-version=<api-version>

To get the current API version, use the following API:

API /api/versions

Method GET

Sample Response{

"supportedApiVersions": [

"0.1

0.2

"

],

"currentApiVersion": "0.2"

}

User Access TokenYou require a user access token to perform API operations.

Authorization : {UserAccessToken}

For information about generating user access tokens, see the User Authentication section.


VMware, Inc. 11

Set the Current Organization IDUse this header to set the current organization ID for which you want to run the APIs.

x-current-org-id:<orgId>

Restricted CharactersThe following characters are restricted when creating a template name, device name, custom property, and metric name.

Template Name

< > % $ ( ) { }

Device Name

< > % $ ( ) { } [ ]

Custom Property

< > . % $ ( ) { }

Metric Name

: { } & "


VMware, Inc. 12

Server APIs 3This chapter includes the following topics:

n Device Management APIs

n Campaign Management APIs

n Alerts APIs

n Identity and Access Management (IAM) APIs

n Notification APIs

n Certificate Management APIs

n Advanced Search APIs

n Metric APIs

n Audit APIs

Device Management APIsThis section lists the APIs for performing operations on devices, device templates, device authentication, device commands, and files.

Enroll Device

HeaderAuthorization : {{DeviceAccessToken}}

Required Permissions You must have the Enroll Device permission to perform this operation.

API /api/devices/{id}/enroll

Method GET

VMware, Inc. 13


id

string

Device identifier.

Response{

"id": "string"

}

Get a Device

Required Permissions You must have the View Device permission to perform this operation.

API /api/devices/{id}

Method GET


id

string

Device identifier.

Response{

"id":"8d33b386-154e-46fd-9d19-b1452fb9da30",

"name":"Gateway3",

"deviceType":"GATEWAY",

"templateId":"492debf2-735e-4ddf-9440-d5542adf1770",

"systemProperties":[

{

"name":"os-sysname",

"value":"Linux"

}

],

"customProperties":[

{

"name":"a",

"value":"a"

}

],

"enrollmentState":"ENROLLED",

"parentGatewayId":"8d33b386-154e-46fd-9d19-b1452fb9da30",

"orgId":"1a813d5d-da81-410b-b252-b8ec9a91e069",

"createdTime":1564983544640,

"lastUpdatedTime":1565071895936,

"updateVersion":15

}


VMware, Inc. 14

List All Devices


API /api/devices

Method GET

Optional Parameters Name Description

parentId

string

Parent device ID.

name

string

Device name.

deviceType

string

Device type:

n GATEWAY

n THING

id

string

Device ID.

enrollmentState

string

Device states:

n REGISTERED

n ENROLLED

n UNENROLLED

n DELETED

templateId

string

Template ID.

page.number

int32

Page number.

page.size

string

Page size.

Response{

"pageInfo": {

"totalPages": "string",

"totalElements": "string",

"page": 0,

"pageSize": 0

},

"devices": [

{

"name": "string",

"systemProperties": [

{

"name": "string",

"value": "string"

}

],


VMware, Inc. 15

"templateId": "string",

"updateVersion": "string",

"createdTime": "string",

"deviceType": "GATEWAY",

"customProperties": [

{

"name": "string",

"value": "string"

}

],

"parentId": "string",

"enrollmentState": "ENROLLED",

"orgId": "string",

"id": "string",

"lastUpdatedTime": "string"

}

]

}

Register a Device

Required Permissions You must have the Create Device permission to perform this operation.

API /api/devices

Method POST

Parameters Name Description

parentId

string

Parent ID for the relationship. (This is an optional parameter.)

name

string

Device name.

templateName

string

Device template name.

Input Example{

"parentId": "string",

"name": "string",

"templateName": "string"

}

Response{

"id": "string"

}


VMware, Inc. 16

Unenroll a Device

Required Permissions You must have the Unenroll Device permission to perform this operation.

API /api/devices/{id}/unenroll

Method DELETE


id

string

Device identifier.

Response{}

Delete a Device

Required Permissions You must have the Delete Device permission to perform this operation.

API /api/devices/{id}

Method DELETE


id

string

Device identifier.

Response{}

Get a List of Connected Devices


API /api/devices/{{device_id}}/connected-devices

Method GET


VMware, Inc. 17


type

string

The supported values are ALL and THINGS.

page.number

int32

The number of pages to display.

page.size

string

The number of entries per page.

Response{

"devices": [

{

"name": "CD_01_02",

"deviceType": "THING",

"templateId": "21d30e3d-3176-4445-b2cd-e65ce662d76f",

"enrollmentState": "REGISTERED",

"parentId": "12c6006e-a27f-47eb-8a42-1313f3edd57f",

"parentGatewayId": "413d5b55-ec4a-4026-a89a-7eb3986f8f4e",

"orgId": "618ab173-efa4-4d8a-8793-fa5377f5bd7e",

"createdTime": 1570106199609,

"lastUpdatedTime": 1570106199609,

"updateVersion": 1,

"id": "30590692-ec76-4935-b09a-3b8fafeda4ef"

},

{

"name": "CD_01_01",

"templateName": "Thing_02",


"templateId": "21d30e3d-3176-4445-b2cd-e65ce662d76f",


"parentId": "12c6006e-a27f-47eb-8a42-1313f3edd57f",



"createdTime": 1570106188372,


"updateVersion": 1,

"id": "b522ccdc-6158-48d4-84db-76302b6c066f"

},

{

"name": "CD_01",

"templateName": "Thing_01",


"templateId": "83d95d04-8629-46e9-b1da-530b0e6d2cf6",


"parentId": "413d5b55-ec4a-4026-a89a-7eb3986f8f4e",



"createdTime": 1570102596241,


"updateVersion": 1,

"id": "12c6006e-a27f-47eb-8a42-1313f3edd57f"


VMware, Inc. 18

}

],

"pageInfo": {

"totalPages": 1,

"page": 1,

"pageSize": 1000,

"totalElements": 2

}

}

Update Device System Properties

HeaderAuthorization : {{DeviceAccessToken}}

Required Permissions You must have the Edit System Properties permission to perform this operation.

API /api/devices/{id}/system-properties

Method POST


remove

string

System property names to be removed.

upsert

string

System property names to be inserted or updated.

n name

n value

Input Example{

"upsert":[

{

"name":"os-machine",

"value":"Windows"

},

{

"name":"version",

"value":"123"

}

],

"remove":[

"model",

"make"

]

}

Response{}


VMware, Inc. 19

Update Device Custom Properties

Required Permissions You must have the Edit Custom Properties permission to perform this operation.

API /api/devices/{id}/custom-properties

Method POST


remove

string

Custom property names to be removed.

upsert

string

Custom property names to be inserted or updated.

n name

n value

Input Example{

"upsert":[

{


"value":"Windows"

},

{

"name":"version",

"value":"123"

}

],

"remove":[

"model",

"make"

]

}

Response{}

Update Custom Property on Multiple Devices

Required Permissions You must have the Edit Custom Properties permission to perform this operation.

API https://{{URL}}:{{PORT}}/api/devices

Method PUT


VMware, Inc. 20


Query param: action ->

UPDATE_CUSTOM_PROPERTY

string

Sample Request for Property Addition or Edit

{

"filter":

{

"deviceId": [

"3c499010-9e7b-4037-b024-d89a3f0b29eb",

"ca4417a7-6b45-4bff-8524-0bdc3342663c",

"42a6884c-7c7f-4b9f-9050-e4616cef5677",

"04345c2b-2787-4cf0-852c-3816ec23513f",

"56788d57-9f4b-4e07-84d6-afb4526c7e63"

]

},

"property" :

{

"upsert":[{"name":"test1","value":"123"},

{"name":"test2","value":"456"}]

}

}

Sample Request for Property Deletion

"filter":

{

"deviceId": [

"3c499010-9e7b-4037-b024-d89a3f0b29eb",

"ca4417a7-6b45-4bff-8524-0bdc3342663c",

"42a6884c-7c7f-4b9f-9050-e4616cef5677",

"04345c2b-2787-4cf0-852c-3816ec23513f",

"56788d57-9f4b-4e07-84d6-afb4526c7e63"

]

},

"property" :

{

"remove":["test1", "test2"]

}

}

Response{"taskId":"68560ff6-977f-4b23-bc5c-999d8c8da08y"}

Update Agent

Required Permissions You must have the Update Agent permission to perform this operation.

API /api/devices/{id}/update-agent

Method PUT


VMware, Inc. 21

Input Example{}

Response{}

Create a Device Template

Required Permissions You must have the Create Device Template permission to perform this operation.

API /api/device-templates

Method POST


name

string

Template name. Must be unique for the tenant. (Required)

deviceType

string

Device type for which the template is created (Required):

n GATEWAY

n THING

systemProperties

array

name: Property name key.

customProperties

array

n name: Property name key.

n value: Default value.

allowedMetrics

array

n name: Metric name key.

n value: Metric value type.

n INT64

n DOUBLE

n STRING

n BOOLEAN

n unit: Unit of metric that is collected from the IoTC Agent.


VMware, Inc. 22

Name Description

allowedCommands

array

Allowed commands.

n command: The supported command types are:

n SSH

n REBOOT

n FILE_UPLOAD

n EXECUTE

n CLIENT_EXECUTE - Supported on both gateway and Thing templates.

n name: Name of the command.

n asroot: The command is run as root.

n argument: The required arguments to run the command.

n execPath: The executable path required for custom commands.

n clientId: The client ID required for client commands.

childTemplates

array

Allowed templates.


VMware, Inc. 23

Name Description

enrollmentProvider

string

Available only on gateway templates.

The enrollment provider (Required):

n providerConfig: Enrollment provider property configuration.

n type: Enrollment provider type.

n JWT_NATIVE

"enrollmentProvider":{"type":"JWT_NATIVE","providerConfig":"{\"expiryTime\":57600}"

n PROPERTY_NATIVE

"enrollmentProvider": {"type": "PROPERTY_NATIVE", "providerConfig": "{\"identityKey\":\"DeviceKey\"}"

n TPM_NATIVE

"enrollmentProvider":{"type":"TPM_NATIVE","providerConfig":"{}"}

n BASIC

"enrollmentProvider":{"type": "BASIC","providerConfig": ""}

The property configuration changes according to the property type.

settings

array


Device template settings:

n commandFetchIntervalSeconds: The interval to fetch commands in seconds. The maximum value for the command fetch interval is 43200 seconds. The minimum value is 10 seconds and the default value for the command fetch interval is 30 seconds. If the time interval is not in the minimum value range, an error message is displayed.

n maxNumberOfClients: The maximum number of clients allowed.

n agentLogLevel: The log level to collect VMware Pulse IoTC Agent logs.

n metricsIntervalSeconds: The interval to collect metrics in seconds. The minimum value for the metrics interval is 60 seconds and the default value for the metric interval is 300 seconds. If the time interval is not in the minimum value range, an error message is displayed.

n grpcEnabled: Whether GPRC is enabled or not.

n serverRequestTimeoutSecond: Timeout in seconds after which the request from the VMware Pulse IoTC Agent to the server will timeout.


VMware, Inc. 24

Name Description

n networkBandwidth: The maximum network bandwidth allowed on the device for the IoTC Agent. The data rate is in Bytes per second (B/s). The value 0 denotes unlimited network bandwidth

Input Example Gateway Template Request

{

"name":"Gateway_01",



{

"name":"os-sysname"

},

{

"name":"os-machine"

},

{

"name":"os-release"

},

{

"name":"ssh"

},

{

"name":"bus-size"

}

],


{

"name":"location",

"value":"KM"

}

],

"allowedMetrics":[

{

"name":"CPU-Usage",

"displayName":"CPU-Usage",

"valueType":"DOUBLE",

"displayUnit":"%"

},

{

"name":"Memory-Usage",

"displayName":"Memory-Usage",


"displayUnit":"%"

},

{

"name":"Disk-Usage",

"displayName":"Disk-Usage",


"displayUnit":"%"


VMware, Inc. 25

}

],

"allowedCommands":[

{

"command":"EXECUTE",

"name":"CREATE_NEW_FILE_NON_ROOT",

"arguments":[

{

"name":"test123",

"value":[

"/opt/vmware/iotc-agent/NewFile_NonRoot"

],

"type":"STRING"

}

],

"asRoot":false,

"execPath":"/bin/touch"

},

{

"command":"SSH",

"name":"SSH",

"arguments":[

{

"name":"arg0",

"value":[

"enable"

],

"type":"STRING"

}

],

"asRoot":true

},

{

"command":"REBOOT",

"name":"REBOOT",

"asRoot":true

},

{

"command":"FILE_UPLOAD",

"name":"File_single",

"arguments":[

{

"name":"arg0",

"value":[

"/root/10MB_syslog"

],

"type":"STRING"

}

],

"asRoot":true

},

{

"name":"ints",

"command":"CLIENT_EXECUTE",


VMware, Inc. 26

"arguments":[

{

"name":"ints",

"value":[

1234

],

"type":"INT64"

}

],

"execPath":"/usr/bin/touch",

"clientId":"com.vmware.client.default"

}

],

"enrollmentProvider":{

"type":"JWT_NATIVE",

"providerConfig":"{\"expiryTime\":30}"

},

"settings":[

{

"category":"iotc-agent",

"settings":{

"commandFetchIntervalSeconds":30,

"maxNumberOfClients":6,

"agentLogLevel":6,

"metricsIntervalSeconds":60,

"grpcEnabled":1,

"serverRequestTimeoutSecond": 300

"networkBandwidth": 0

}

}

],

"childTemplates":[

"1234",

"4567"

]

}

Thing Template Request

{

"name":"Thing_03",

"deviceType":"THING",


{

"name":"os-sysname"

}

],


{

"name":"location",

"value":"KM"

}

],


VMware, Inc. 27

"allowedMetrics":[

{

"name":"CPU",

"displayName":"CPU",

"valueType":"INT64",

"displayUnit":"%"

}

],

"allowedCommands":[

{

"name":"ints",


"arguments":[

{

"name":"ints",

"value":[

1234

],

"type":"INT64"

}

],



}

],

"childTemplates":[

"1234",

"4567"

]

}

Response{

"id": "string"

}

Update a Device Template

Required Permissions You must have the Edit Device Template permission to perform this operation.

API /api/device-templates/{id}

Method PUT


name

string

Template name. Must be unique for the tenant. (Required)

deviceType

string

Device type for which the template is created (Required):

n GATEWAY

n THING


VMware, Inc. 28

Name Description

systemProperties

array

name: Property name key.

customProperties

array

n name: Property name key.

n value: Default value.

allowedMetrics

array

n name: Metric name key.

n value: Metric value type.

n INT64

n DOUBLE

n STRING

n BOOLEAN

n unit: Unit of metric that is collected from the IoTC Agent.

allowedCommands

array

Allowed commands.

n command: The supported command types are:

n SSH

n REBOOT

n FILE_UPLOAD

n EXECUTE

n CLIENT_EXECUTE - Supported on both gateway and Thing templates.

n name: Name of the command.

n asroot: The command is run as root.

n argument: The required arguments to run the command.

n execPath: The executable path required for custom commands.

n clientId: The client ID required for client commands.

childTemplates

array

Allowed templates.


VMware, Inc. 29

Name Description

enrollmentProvider

string


The enrollment provider (Required):

n providerConfig: Enrollment provider property configuration.

n type: Enrollment provider type.

n JWT_NATIVE

"enrollmentProvider":{"type":"JWT_NATIVE","providerConfig":"{\"expiryTime\":57600}"

n PROPERTY_NATIVE

"enrollmentProvider": {"type": "PROPERTY_NATIVE", "providerConfig": "{\"identityKey\":\"DeviceKey\"}"

n TPM_NATIVE

"enrollmentProvider":{"type":"TPM_NATIVE","providerConfig":"{}"}

n BASIC

"enrollmentProvider":{"type": "BASIC","providerConfig": ""}

The property configuration changes according to the property type.

settings

array


Device template settings:

n commandFetchIntervalSeconds: The interval to fetch commands in seconds. The maximum value for the command fetch interval is 43200 seconds. The minimum value is 10 seconds and the default value for the command fetch interval is 30 seconds. If the time interval is not in the minimum value range, an error message is displayed.

n maxNumberOfClients: The maximum number of clients allowed.

n agentLogLevel: The log level to collect VMware Pulse IoTC Agent logs.

n metricsIntervalSeconds: The interval to collect metrics in seconds. The minimum value for the metrics interval is 60 seconds and the default value for the metric interval is 300 seconds. If the time interval is not in the minimum value range, an error message is displayed.

n grpcEnabled: Whether GPRC is enabled or not.

n serverRequestTimeoutSecond: Timeout in seconds after which the request from the VMware Pulse IoTC Agent to the server will timeout.


VMware, Inc. 30

Name Description

n networkBandwidth: The maximum network bandwidth allowed on the device for the IoTC Agent. The data rate is in Bytes per second (B/s). The value 0 denotes unlimited network bandwidth.

Input Example Gateway Template Request

{


{

"name":"os-sysname"

},

{

"name":"os-machine"

},

{

"name":"os-release"

},

{

"name":"ssh"

},

{

"name":"bus-size"

}

],


{

"name":"location",

"value":"KM"

}

],

"allowedMetrics":[

{

"name":"CPU-Usage",

"displayName":"CPU-Usage",


"displayUnit":"%"

},

{

"name":"Memory-Usage",

"displayName":"Memory-Usage",


"displayUnit":"%"

},

{

"name":"Disk-Usage",

"displayName":"Disk-Usage",


"displayUnit":"%"

}

],


VMware, Inc. 31

"allowedCommands":[

{

"command":"EXECUTE",

"name":"CREATE_NEW_FILE_NON_ROOT",

"arguments":[

{

"name":"test123",

"value":[

"/opt/vmware/iotc-agent/NewFile_NonRoot"

],

"type":"STRING"

}

],

"asRoot":false,

"execPath":"/bin/touch"

},

{

"command":"SSH",

"name":"SSH",

"arguments":[

{

"name":"arg0",

"value":[

"enable"

],

"type":"STRING"

}

],

"asRoot":true

},

{

"command":"REBOOT",

"name":"REBOOT",

"asRoot":true

},

{


"name":"File_single",

"arguments":[

{

"name":"arg0",

"value":[

"/root/10MB_syslog"

],

"type":"STRING"

}

],

"asRoot":true

},

{

"name":"ints",


"arguments":[

{


VMware, Inc. 32

"name":"ints",

"value":[

1234

],

"type":"INT64"

}

],



}

],

"enrollmentProvider":{

"type":"JWT_NATIVE",

"providerConfig":"{\"expiryTime\":30}"

},

"settings":[

{

"category":"iotc-agent",

"settings":{

"commandFetchIntervalSeconds":30,

"maxNumberOfClients":6,

"agentLogLevel":6,

"metricsIntervalSeconds":60,

"grpcEnabled":1,

"serverRequestTimeoutSecond": 300


}

}

],

"childTemplates":[

"1234",

"4567"

]

}

Thing Template Request

{


{

"name":"os-sysname"

}

],


{

"name":"location",

"value":"KM"

}

],

"allowedMetrics":[

{

"name":"CPU",

"displayName":"CPU",


VMware, Inc. 33

"valueType":"INT64",

"displayUnit":"%"

}

],

"allowedCommands":[

{

"name":"ints",


"arguments":[

{

"name":"ints",

"value":[

1234

],

"type":"INT64"

}

],



}

],

"childTemplates":[

"1234",

"4567"

]

}

Response{

"id": "string"

}

Get a Device Template by ID

Required Permissions You must have the View Device Template permission to perform this operation.


Method GET


id

string

Device template ID.

Response{

"imageDetails": [{

"imageUrl": "string",

"id": "string",

"sourceType": "string"


VMware, Inc. 34

}],

"name": "string",

"systemProperties": [{

"name": "string"

}],

"allowedMetrics": [{

"displayUnit": "string",

"displayName": "string",

"name": "string",

"valueType": "UNKNOWN_VALUE_TYPE"

}],

"updateVersion": 0,

"enrollmentProvider": {

"providerConfig": "string",

"type": "string"

},

"deviceType": "UNKNOWN_TYPE",

"allowedCommands": [{

"command": "string",

"name": "string",

"arguments": [{

"name": "string",

"value": [

"string"

],

"type": "string"

}],

"asRoot": true,

"execPath": "string"

}],

"customProperties": [{

"name": "string",

"value": "string"

}],

"settings": [{

"category": "string",

"settings": {

"commandFetchIntervalSeconds": long,

"maxNumberOfClients": long,

"agentLogLevel": long,

"metricsIntervalSeconds": long,

"grpcEnabled": long,

"serverRequestTimeoutSecond": long


},

"finalSettings": {}

}],

"lastUpdatedTime": "string",


"orgId": "string",

"id": "string",

"childTemplates": [


VMware, Inc. 35

"string"

]

}

Delete a Device Template by ID

Required Permissions You must have the Delete Device Template permission to perform this operation.


Method DELETE


id

string

Device template ID.

Response{}

List Device Templates

Required Permissions You must have the View Device Template permission to perform this operation.

API /api/device-templates

Method GET


id

array

List of device template IDs.

name

string

Template name.

deviceType

string

Device type:

n GATEWAY

n THING

page.number

int32

Page number.

page.size

string

Page size.


VMware, Inc. 36

Name Description

exactName

string

Exact name of the search.

queryType SHOW_CURRENT, SHOW_ANCESTORS,SHOW_DESCENDANTS or SHOW_ALL

Response{

"templates": [

{

"imageDetails": [

{

"imageUrl": "string",

"id": "string",

"sourceType": "string"

}

],

"name": "string",

"systemProperties": [

{

"name": "string"

}

],

"allowedMetrics": [

{

"displayUnit": "string",

"displayName": "string",

"name": "string",

"valueType": "UNKNOWN_VALUE_TYPE",

}

],

"updateVersion": 0,

"enrollmentProvider": {

"providerConfig": "string",

"type": "string"

},

"deviceType": "UNKNOWN_TYPE",

"allowedCommands": [

{


"name": "string",

"asRoot": true,

"arguments": [

"string"

]

}

],

"customProperties": [

{

"name": "string",


VMware, Inc. 37

"value": "string"

}

],



"orgId": "string",

"id": "string",

"childTemplates": [

"string"

]

}

],

"pageInfo": {



"page": 0,

"pageSize": 0

}

}

Get Property Keys From Device Templates


API https://{{URL}}:{{PORT}}/api/devices/keys

Method GET


id Device template ID.

name

string

Property key name.

maxSize

string

Number of keys to be returned in the response.

Response"keys": [

{

"key": "os-release",

"keyQualifier": "systemProperties"

},

{

"key": "ssh",


}

]

}


VMware, Inc. 38

Get Property Values From Device


API https://{{URL}}:{{PORT}}/api/devices/keys/values

Method GET

Mandatory Query Parameters

Name Description

keyQualifier Allowed values: customProperties/systemProperties/device

key

string

If keyQualifier is set to device then the key should be either name/id/parentGatewayId/ deviceType/templateId/

enrollmentState


name

string

Property value.

maxSize

string

Number of keys to be returned in the response.

Requesthttps://{{URL}}:{{PORT}}/api/devices/keys/values?

keyQualifier=systemProperties&key=ssh&name=enable

https://{{URL}}:{{PORT}}/api/devices/keys/values?

maxSize=10&keyQualifier=device&key=name

Response{

"values": [

{

"key": "name",

"keyQualifier": "device",

"values": [

{

"value": "test1",

"count": 1

}

]

}

]

}

Get Pending Commands

Required Permissions You must have the Get Device Command permission to perform this operation.

API /api/devices/{device_id}/commands


VMware, Inc. 39

Method GET


deviceId

string

Device ID.

Response

{

"commandMessage": [{


"asRoot": true,


"arguments": [{

"name": "string",

"value": [

"string"

],

"type": "string"

}],


"commandId": "string",


"name": "string"

}]

}"

Invoke Device Command

Required Permissions You must have the Send Device Command permission to perform this operation.


Method POST


deviceId

string

Device ID.

Invoke Command Examples

SSH

{"name":"SSH_EN","command":"SSH","arguments":

[{"name":"args","type":"STRING","value":["enable"]}]}

REBOOT

{"name":"REBOOT","command":"REBOOT","arguments":[]}


VMware, Inc. 40

FILE_UPLOAD

{"name":"UploadFile","command":"FILE_UPLOAD","arguments":

[{"name":"test","type":"STRING","value":["/root/test.log"]}]}

EXECUTE

{"name":"create_file","command":"EXECUTE","arguments":

[{"name":"test","type":"STRING","value":["/root/test.txt"]}]}

CLIENT_EXECUTE

{"name":"ExecuteClientCmd","command":"CLIENT_EXECUTE","arguments":

[{"name":"ints","type":"STRING","value":["1234”]}]}

Response{

"commandId": "string"

}

Update Device Command Status

Required Permissions You must have the Edit Device Command permission to perform this operation.


Method PUT


Input Example{

"commandResponse": [

{


"status": "EXECUTED/FAILED",

"response": "string"

}

]

}

Response{

"commandIds": [

"string"

]

}


VMware, Inc. 41

List Device Commands

Required Permissions You must have the Get Device Command permission to perform this operation.

API /api/devices/commands

Method GET


deviceId

string

Device ID.

page.number

int32

Page number.

page.size

string

Page size.

commandName

stringCommand name.

commandStatus

stringCommand status.

commandType

stringCommand type.

commandId

stringCommand ID

Response{

"commands": [

{

"status": "string",

"name": "string",


"asRoot": true,

"response": "string",


"arguments": [

"string"

],



"deviceId": "string"

}

],

"pageInfo": {




VMware, Inc. 42

"page": 0,

"pageSize": 0

}

}

Create Device Credential

Required Permissions You must have the Create Device Credential permission to perform this operation.

API api/device-credentials/{id}

Method POST

Input Example JWT_NATIVE

{}

PROPERTY_NATIVE

{"requestParams":"{\"DeviceKey\":\"1234\"}"}

TPM_NATIVE

{"requestParams":"{\"tpm_ek\":\"123456\"}"}

Response{

"credentials": "string"

}

Get Device Token

Required Permissions You must have the Get Device Token permission to perform this operation.

API /api/device-tokens

Header Set the header based on the type of enrollment you want to perform:

n Basic Enrollment:

Authorization - {{UserAcccessToken}}

Accept - application/json;api-version={{VERSION}}

Content-Type - application/json


VMware, Inc. 43

n Token Based Enrollment:

x-device-auth - {{device-credentials}}



Enter the device credential that you created in the Create Device Credential API.

Method GET


id

string

Device ID.

Response{


"accessToken": "string"

}

File Upload

API api/devices/files

HeaderAuthorization: {{DeviceAccessToken}}

Content-Type: application/octet-stream

Or

Authorization: {{DeviceAccessToken}}

Content-Type: multipart/form-data

Method POST


filename

string

File name (required).

description

stringFile description (optional).

deviceId

stringDevice ID (optional).

Response{

"id": "string"

}


VMware, Inc. 44

File DownloadDownload a file that is stored in the database.

API api/devices/files/{fileId}

HeaderAccept: application/octet-stream

Add a Range header to specify the file size to download. For example:

Range: bytes=100-2000

Method GET

Response Content of the file.

Get File InfoGet the file information.

API api/devices/files/{fileId}/file-info

Method GET

Response{

"deviceIds": [

"string"

],

"fsId": "string",

"name": "string",

"size": long,

"path": "string",

"parentDirectory": "string",

"isDirectory": false,

"orgId": "string",

"createdTime": long,

"lastUpdatedTime": long,

"updateVersion": int,

"createdBy": "string",

"lastUpdatedBy": "string",

"expireAt": long,

"id": "string"

}"


VMware, Inc. 45

List FilesList all the files uploaded for a device.

API /api/devices/files

HeaderAuthorization - {{UserAcccessToken}}



Method GET


page.number

int32

Page number.

page.size

stringPage size.

fileId

stringFile ID.

name

stringName of the file.

Response{

"files":[

{

"expireAt":1568022685000,

"deviceIds":[

"35137adb-e801-4238-a2dc-ea9c06857aa2"

],

"name":"FileExpiryTest12.txt",

"path":"/devices/3fac7479-fb77-4c7b-9454-805649aed3d9",

"isDirectory":false,

"orgId":"9480f326-aa95-41bd-886e-25e574f79f09",

"createdTime":1568022565351,


"createdBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",

"lastUpdatedBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",

"id":"3fac7479-fb77-4c7b-9454-805649aed3d9"

},

{

"expireAt":1568022680000,

"deviceIds":[

"35137adb-e801-4238-a2dc-ea9c06857aa2"

],

"name":"FileExpiryTest11.txt",

"path":"/devices/bd6164d7-07ba-4227-9134-1fd0dae58aea",

"isDirectory":false,

"orgId":"9480f326-aa95-41bd-886e-25e574f79f09",

"createdTime":1568022560351,



VMware, Inc. 46

"createdBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",

"lastUpdatedBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",

"id":"bd6164d7-07ba-4227-9134-1fd0dae58aea"

}

],

"pageInfo":{

"totalPages":1,

"page":1,

"pageSize":20,

"totalElements":2

}

}

Delete Filedelete files.

API /api/devices/files

Method DELETE



Advanced FilterUse the advanced filter API to search for devices based on certain property values.

API /api/devices/advanced-filter

Method POST

Input Example{

"property":[

{

"name":"color",

"operatorValue":[

{

"operator":"EQUAL_TO",

"value":"red"

}

],


VMware, Inc. 47

"type":"CUSTOM_PROPERTY"

}

]

}

Response Returns the list of devices that satisfy the property filter criteria.

{

"devices":[

{

"name":"device3",

"templateName":"Default Gateway Template",


"templateId":"870bbefe-4796-448a-a92a-0c83989b480c",


{


"value":""

},

{


"value":""

},

{

"name":"os-release",

"value":""

},

{

"name":"ssh",

"value":""

},

{

"name":"iotc-agent-version",

"value":""

}

],


{

"name":"color",

"value":"red"

},

{

"name":"qr-code",

"value":"qr-code-value"

}

],

"enrollmentState":"REGISTERED",

"parentGatewayId":"cf37abdf-6352-424e-ae31-117173077d1e",

"orgId":"a085e01b-b561-4239-89f1-802df460405a",

"createdTime":1566539088764,


"updateVersion":1,

"id":"cf37abdf-6352-424e-ae31-117173077d1e"


VMware, Inc. 48

},

{

"name":"device2",





{


"value":""

},

{


"value":""

},

{


"value":""

},

{

"name":"ssh",

"value":""

},

{


"value":""

}

],


{

"name":"color",

"value":"red"

},

{

"name":"qr-code",

"value":"qr-code-value"

}

],


"parentGatewayId":"1599653f-9c03-4eaa-b608-c66e32f84b1d",

"orgId":"a085e01b-b561-4239-89f1-802df460405a",

"createdTime":1566539081748,


"updateVersion":1,

"id":"1599653f-9c03-4eaa-b608-c66e32f84b1d"

},

{

"name":"device1",





{



VMware, Inc. 49

"value":""

},

{

"name":"ssh",

"value":""

},

{


"value":""

},

{


"value":""

},

{


"value":""

}

],


{

"name":"color",

"value":"red"

}

],


"parentGatewayId":"05cf8b0b-b3ae-486c-87d3-80f67868668a",

"orgId":"a085e01b-b561-4239-89f1-802df460405a",

"createdTime":1566538985229,


"updateVersion":2,

"id":"05cf8b0b-b3ae-486c-87d3-80f67868668a"

}

],

"pageInfo":{

"totalPages":1,

"page":1,

"pageSize":10,

"totalElements":3

}

}

Invoke Bulk CommandSend commands to multiple devices.

API /api/devices

Method PUT


VMware, Inc. 50





action

string

SEND_COMMAND

Input Example{

"filter":{

"deviceId":[

"f32c1dcf-52ce-4d53-b558-6ca7fba60f86",

"f32c1dcf-52ce-4d53-b558-6ca7fba60f84",

"f32c1dcf-52ce-4d53-b558-6ca7fba60f87"

]

},

"command":[

{

"command":"SSH",

"name":"SSH_ENABLE",

"arguments":[

{

"name":"args",

"value":[

"enable"

],

"type":"STRING"

}

]

}

]

}

Sample Response{"taskId":"68560ff6-977f-4b23-bc5c-999d8c8da08e"}

Invoke Bulk Agent UpdateSend agent update command to multiple devices.

API /api/devices

Method PUT





VMware, Inc. 51


action

string

UPDATE_AGENT

Input Example{

"filter": {

"deviceId": [

"ca4417a7-6b45-4bff-8524-0bdc3342663c",

"42a6884c-7c7f-4b9f-9050-e4616cef5677"

]

}

}

Sample Response{"taskId":"68560ff6-977f-4b23-bc5c-999d8c8da08e"}

Get Task InfoGet information about a task.

API /api/tasks/{taskId}

Method GET




Sample Response{

"id":"ef996658-6111-43bd-bdfc-9d1fa4448ee0",

"fqId":"ef996658-6111-43bd-bdfc-9d1fa4448ee0",

"parentId":"",

"queueName":"devicemgmt",

"type":"DEVICE_BULK_INVOKE_COMMAND_TASK",

"version":"1.0",

"data":{

"filter":{

"deviceId":[

"27e9963f-4f95-4206-9eb2-1b66739d1b4b",

"42e59eb0-f44b-4d6c-af68-a4077dab8731",

"cd340f6a-d862-4cc1-bd34-e919729daa20",

"ebd14b77-95f2-490c-86d2-197b75f5ed4a",

"0cd13e61-a136-4d19-afc2-b559cd0598f9"

]

},

"command":[

{

"name":"UPLOAD_AGENT_INSTALL_LOG_FILE",



VMware, Inc. 52

"arguments":[

{

"name":"arg0",

"type":"STRING",

"value":[

"/var/log/vmware/iotc-agent/install.log"

]

}

]

}

]

},

"context":{

"userName":"[email protected]",

"userId":"d2bcaddf-7b2f-4776-95db-25f92d4f8101",

"orgId":"b5abe95e-2cef-4caa-ab6c-3745f0c482bd",

"deviceId":null,

"system":false,

"device":false,

"traceId":"07244fa664378efa69c62f0bfe3cd4e3"

},

"state":"REQUEUED",

"prevState":"COMMAND_EXECUTION_IN_PROGRESS",

"result":{

"summary":{

"skipped":0,

"pending":0,

"executed":5,

"failed":0,

"total":5

},

"details":[

{

"deviceId":"27e9963f-4f95-4206-9eb2-1b66739d1b4b",

"status":"EXECUTED"

},

{

"deviceId":"42e59eb0-f44b-4d6c-af68-a4077dab8731",

"status":"EXECUTED"

},

{

"deviceId":"cd340f6a-d862-4cc1-bd34-e919729daa20",

"status":"EXECUTED"

},

{

"deviceId":"ebd14b77-95f2-490c-86d2-197b75f5ed4a",

"status":"EXECUTED"

},

{

"deviceId":"0cd13e61-a136-4d19-afc2-b559cd0598f9",

"status":"EXECUTED"

}

]

},


VMware, Inc. 53

"lastUpdatedByTaskManager":"devicemgmt-10.92.183.251",

"availableAt":1567517299638,

"createdTime":1567515912843,


"notifyParentOnComplete":false,

"failTaskOnException":true,

"name":"Device Command - UPLOAD_AGENT_INSTALL_LOG_FILE",

"numOfSubTasks":1,

"numOfSubTasksCompleted":1,

"numOfSubTasksFailed":0

}

Campaign Management APIsUse 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


name

string

Name of the campaign.

Input Example{

"name": "string",

"description": "string",

"packages": [

"string"

],

"campaignSettings": {

"settings": {

"additionalProp1": "string",


"additionalProp3": "string"

}

}

}

Response{

"uuid": "string"

}


VMware, Inc. 54

Edit Campaign

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

API /api/campaigns/{campaign_id}

Method PUT


name

string


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


"packages": [

"string"

],

"campaignSettings": {

"settings": {



"additionalProp3": "string"

}

}

},

"campaignId": "string"

}

Response{

"uuid": "string"

}

Delete Campaign

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



VMware, Inc. 55

Method DELETE


campaignId

string

ID of the campaign.

Response{}

Get Campaign

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


Method GET


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


VMware, Inc. 56

Method PUT


campaignId

string

ID of the campaign.

Input Example{


}

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


campaignId

string

ID of the campaign.

Input Example{


}

Response{}

Approve Campaign by ID

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

API /api/campaigns/{campaign_id}/approve


VMware, Inc. 57

Method PUT


campaignId

string

ID of the campaign.

Input Example{


}

Response{}

Register Completed Callback


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


notificationDestinationI

d

string

callback destination.

campaignId

string

ID of the campaign.

Input Example{

"notificationDestinationId": "string",


}

Response{}


VMware, Inc. 58

Register Wake Up Callback


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


notificationDestinationI

d

string

callback destination.

campaignId

string

ID of the campaign.

Input Example{



}

Response{}

Notify Gateway


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

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


VMware, Inc. 59

Method PUT


gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Input Example{

"gatewayId": "string",


}

Response{}

Assign Update Packages for the Target Gateway


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


VMware, Inc. 60

Method PUT


gatewayId

string

ID of the gateway.

packages

string

Update package IDs to be assigned.

campaignId

string

ID of the campaign.

Input Example{


"packages": [

"string"

],


}

Response{}

Get Updated Package Information for the Gateway in the Campaign


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

Method GET


gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Response{

"packages": [

"string"

]

}


VMware, Inc. 61

Get Gateways Added to the Campaign


API /api/campaigns/{campaign_id}/devices

Method GET


campaignId

string

ID of the campaign.

Response{

"pageResponse": {



"page": 0,

"pageSize": 0

},

"gateways": [

{


"state": "string",

"closed": true

}

]

}

List Campaigns


API /api/campaigns

Method GET


id

string

Campaign ID.

name

string


status

string

Status of the campaign:

n STARTED

n CREATED

n STOPPED

n APPROVAL_NEEDED

n APPROVED


VMware, Inc. 62

Name Description

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



Method POST


gatewayId

string

List of gateway IDs.

campaignId

string

ID of the campaign.

Input Example{

"gatewayIds": [

"string"

],


}

Response{}


VMware, Inc. 63

Remove Gateways in a Campaign



Method PUT


gatewayIds

string

List of gateway IDs.

campaignId

string

ID of the campaign.

Input Example{

"gatewayIds": [

"string"

],


}

Response{}

Set Campaign Distribution List


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


VMware, Inc. 64

Method PUT


distributionListId

string

Distribution list ID.

reevaluationIntervalSeco

nds

string

Re-evaluation interval in seconds for the distribution list.

campaignId

string

ID of the campaign.

Input Example{

"distributionListId": "string",

"reevaluationIntervalSeconds": "string",


}

Response{}

Get Campaign Distribution List


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

Method GET


campaignId

string

ID of the campaign.

Response{

"distributionListId": "string",

"reevaluationIntervalSeconds": "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.


VMware, Inc. 65

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

download

Method PUT


n begin

n end

string

Represents a fixed slice of time where begin and end are seconds. (UNIX Epoc time with millisecond precision.)

n begin: start of the time period.

n 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


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

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

activation


VMware, Inc. 66

Method PUT


n begin

n end

string




gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Input Example{

"begin": "string",

"end": "string"

}

Response{}

Schedule Execution


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

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

execution


VMware, Inc. 67

Method PUT


n begin

n end

string




gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Input Example{

"begin": "string",

"end": "string"

}

Response{}

Close Campaign for a Gateway


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

Method PUT


gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Input Example{



}

Response{}


VMware, Inc. 68

Get Campaign State


Description Get the state of a specific gateway in the campaign.

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

Method GET


gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Response{

"state": "string"

}

Register State Change Callback


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


notificationDestinationId Notification destination ID.

campaignId Campaign ID.

Input Example{


"trackedStates": [

"string"

],


}

Response{}


VMware, Inc. 69

Register Execution Progress Callback


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




Input Example{



}

Response{}

Register Download Progress Callback


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




Input Example{



}

Response{}


VMware, Inc. 70

Get Execution Progress


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

Method GET


gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Response{

"progress": [

"string"

]

}

Get Download Progress


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

Method GET


gatewayId

string

ID of the gateway.

campaignId

string

ID of the campaign.

Response{

"packagesProgress": [

{

"progress": "string",

"total": "string",

"id": "string"

}

]

}


VMware, Inc. 71

Get Active Campaigns for a Gateway


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

Method GET


gatewayId

string

ID of the gateway.

Response{

"campaignId": [

"string"

]

}

Get Overall Campaign Status


API /api/campaigns/{campaign_id}/status

Method GET


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


}


VMware, Inc. 72

Get Campaign Status Per Gateway


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

Method GET


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


API /api/campaign-status/campaigns

Method GET


VMware, Inc. 73


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


uuid

string

IoTC ID.

Response{


"id": "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


VMware, Inc. 74


name

string

Name of the program.

page

string

n number

n size

n sort

Response{


"id": "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


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


file

file

The file that is being uploaded.


VMware, Inc. 75


description

string

Description of the uploaded file. Maximum length of characters is 128.

Input ExampleAccept "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


file

file

The file that is being uploaded.


description

string

Description of the uploaded file. Maximum length of characters is 128.

Input ExampleAccept "application/zip"

{

"description": "A"

}

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

Response{

"uuid": "string"

}


VMware, Inc. 76

Run a Campaign on Thing Devices

API /{campaign_id}/devices/things

Method POST


campaign_id

string

ID of the campaign.

gateway_things

stringList of connected Thing devices in a gateway.

gateway_id

stringID of the gateway.

thing_id

stringID of the Thing devices that are connected to the gateway.

state

stringState of the gateway in a campaign.

not_processed_thing_ids

stringID of the connected Thing devices in a gateway that are not processed in the campaign.

closed

booleanDenotes that the gateway is closed for updates.

causedBy

stringContains the cause of failure if a gateway is in failed state.

download_progress

stringList of campaigns that are being downloaded.

execution_progress

stringList of campaigns that are running.

timestamp

stringTime stamp.

Input Example{

"gateway_things": [

{

"gateway_id": "gw1_id",

"thing_ids": [

"thing1_id",

"thing2_id"

]

}

]

}

Alerts APIsUse the following APIs to get, create, update, and delete alerts and alert definitions.


VMware, Inc. 77

Create an Alert Definition

Required Permissions You must have the Create Alert Definition permission to perform this operation.

Description Create an alert definition. Send a JSON request that includes the AlertDefinition fields. You will receive a response with the alert definition ID.

HeadersAuthorization: Bearer <JWT Token>

Accept: application/json;api-version=0.14

API /api/alert-definitions

Method POST


name

string

Name of the alert definition.

description

string

Alert definition description.

deviceTemplateIds List of device template IDs.

properties Property value based on which the alert is triggered.

metrics

string

List of metrics the alert definition depends on.

triggerCount

integer

Number of times metric must exceed threshold to trigger.

recommendation

string

Recommended actions when alerts are triggered.

symptoms

array

The alert definition symptom.

n lambda: Alert condition.

n alertSeverity:

n CRITICAL

n WARNING

n INFO

n NORMAL

alertTemplate

string

Alert template:

n THRESHOLD

notificationDefinitionId

string

Notification definition ID.

savedSearchIds List of saved search IDs.


VMware, Inc. 78

Input Example{

"name": "ABC Alert",

"description": "High CPU Alert",

"deviceTemplateIds": [

"Dell5K",

"Dell6K",

"Dell7K"

],

"savedSearchIds": [],

"metrics": [

"CPU"

],

"triggerCount": 1,

"cancelCount": 1,

"recommendation": "Offload some processes from this machine",

"duration": 1,

"isRealTime": true,

"symptoms": [

{

"lambda": "\"CPU(INT64)\" >= 90",

"alertSeverity": "CRITICAL"

},

{

"lambda": "\"CPU(INT64)\" >= 70",

"alertSeverity": "WARNING"

}

],

"alertTemplate": "THRESHOLD",

"notificationId": "12"

}

Response Example{

"alertDefId": "0f70d96a-36b3-47c3-ab34-339bd3f697bd"

}


VMware, Inc. 79

Get Details of an Alert Definition

Required Permissions You must have the View Alert Definition permission to perform this operation.

Description Get the details of an alert definition.

API /api/alert-definitions/{alert_def_id}

Method GET


alert_def_id

string

Alert definition ID created by the service.

Response{


"alertDef": {

"name": "string",

"triggerCount": 0,

"symptoms": [

{

"lambda": "string",

"alertSeverity": "UNKNOWN_SEVERITY"

}

],

"metrics": [

"string"

],

"notificationId": "string",

"recommendation": "string",

"alertTemplate": "UNKNOWN_TEMPLATE",

"deviceTemplateId": "string",


},


"updateVersion": 0,



"alertDefId": "string"

}


VMware, Inc. 80

Update an Alert Definition

Required Permissions You must have the Edit Alert Definition permission to perform this operation.

Description Update the fields of an alert definition. Send a JSON request that includes all the fields of AlertDefinition, including non-updated fields. Missing fields will overwrite the existing values with default values. You will get a response with the alert definition ID.


Method PUT


name

string


description

string

Alert definition description.

deviceTemplateIds List of device template IDs.

properties Property value based on which the alert is triggered.

metrics

string

List of metrics the alert definition depends on.

triggerCount

integer

Number of times metric must exceed threshold to trigger.

recommendation

string

Recommended actions when alerts are triggered.

symptoms

array



n alertSeverity:

n CRITICAL

n WARNING

n INFO

n NORMAL

alertTemplate

string

Alert template:

n THRESHOLD

notificationDefinitionId

string


savedSearchIds List of saved search IDs.


VMware, Inc. 81

Input Example{

"name": "ABC Alert",

"description": "High CPU Alert",

"deviceTemplateIds": [

"Dell5K",

"Dell6K",

"Dell7K"

],

"savedSearchIds": [],

"metrics": [

"CPU"

],

"triggerCount": 1,

"cancelCount": 1,

"recommendation": "Offload some processes from this machine",

"duration": 1,

"isRealTime": true,

"symptoms": [

{

"lambda": "\"CPU(INT64)\" >= 90",

"alertSeverity": "CRITICAL"

},

{

"lambda": "\"CPU(INT64)\" >= 70",

"alertSeverity": "WARNING"

}

],

"alertTemplate": "THRESHOLD",

"notificationId": "12"

}

Response{


}


VMware, Inc. 82

Delete an Alert Definition

Required Permissions You must have the Delete Alert Definition permission to perform this operation.

Description Delete an alert definition. The system cancels all active alerts that use this definition.


Method DELETE


alert_def_id

string

Alert definition ID created by the service.

Response{}

Get a List of Alert Definitions

Required Permissions You must have the View Alert Definition permission to perform this operation.

Description Get a list of alert definitions that satisfies the optional search parameters.

API /api/alert-definitions

Method GET


name

string


deviceTemplateId

string

Device template ID.

deviceId

string

Device ID.

symptoms

array



n alertSeverity:

n CRITICAL

n WARNING

n INFO

n NORMAL


VMware, Inc. 83

Name Description

alertTemplate

string

Alert template:

n THRESHOLD

n OFFLINE

page.number

int32

Page number.

page.size

int32

Page size.

Response{

"alertDefInfos": [

{


"alertDef": {

"name": "string",

"triggerCount": 0,

"symptoms": [

{

"lambda": "string",

"alertSeverity": "UNKNOWN_SEVERITY"

}

],

"metrics": [

"string"

],

"notificationId": "string",

"recommendation": "string",

"alertTemplate": "UNKNOWN_TEMPLATE",

"deviceTemplateId": "string",


},


"updateVersion": 0,




}

],

"page": {



"page": 0,

"pageSize": 0

}

}


VMware, Inc. 84

Get Alert Details

Required Permissions You must have the View Alert permission to perform this operation.

Description Get details of an alert.

API /api/alerts/{alert_id}

Method GET


alert_id

string

Alert ID created by the service.

Response{


"alertId": "string",

"triggers": [

{

"valueInt64": "0",

"timeMs": "string",

"metric": "string",

"valueDouble": 0.0

}

],

"alertSeverity": "UNKNOWN_SEVERITY",

"state": "UNKNOWN_ALERTSTATE",


"updateVersion": 0,



"userAcknowledged": "string",

"alertDefId": "string",

"alertDefName": "string"

}


VMware, Inc. 85

Changing the Alert State

Required Permissions You must have the Edit Alert permission to perform this operation.

Description Update the alert state from Active to Acknowledged.

Note You cannot revert an alert from Acknowledged state to Active state.

API /api/alerts/{alert_id}

Method PUT


alert_id

string

Alert ID created by the service.

state

string

The alert state:

n ACTIVE

n ACKNOWLEDGED

Input Example{

"state": "ACTIVE"

}

Response{

"alertId": "string"

}

Get a List of Alerts


Description Get a list of alerts that satisfy certain search parameters.

API /api/alerts

Method GET


alert_def_id

string

Alert definition ID.

alert_def_name

string

Alert definition name.


VMware, Inc. 86

Name Description

last_updated_time_start_

ms

int64

Last updated start time (UNIX Epoc time with millisecond precision).

last_updated_time_end_ms

int64

Last updated end time.

symptoms

array



n alertSeverity:

n CRITICAL

n WARNING

n INFO

n NORMAL

state

string

The alert state:

n ACTIVE

n ACKNOWLEDGED

page.number

int32

Page number.

page.size

int32

Page size.

Response{

"page": {



"page": 0,

"pageSize": 0

},

"alertInfos": [

{


"alertId": "string",

"triggers": [

{

"valueInt64": "string",

"timeMs": "string",

"metric": "string",

"valueBoolean": true,

"valueString": "string",

"valueDouble": 0

}

],

"alertSeverity": "UNKNOWN_SEVERITY",

"state": "UNKNOWN_ALERTSTATE",


"updateVersion": 0,



VMware, Inc. 87


"userAcknowledged": "string",

"alertDefId": "string",

"alertDefName": "string"

}

]

Get Alert Trigger History


Description Get a list of alert trigger/cancel/acknowledge history of a device for an alert definition.

API /api/alerts/{alert_id}/trigger-history

Method GET


alert_id

string

Alert ID.

Response

message AlertTriggerHistory {

// the detailed alert triggered/cancelled/acknowledged record

repeated Trigger triggers = 1;

}

// trigger details

message Trigger {

// metric name

string metric = 1;

// timestamp in milliseconds

int64 time_ms = 2;

// metric value (four data types) when the alert is triggered:

string, int64, double or boolean

oneof value {

string value_string = 3;

int64 value_int64 = 4;

double value_double = 5;

bool value_boolean = 6;

}

AlertState state = 7;

// the username who creates the trigger record

string userName = 8;

// severity level when the alert is triggered, added for multi-level


VMware, Inc. 88

alert support

Severity severity = 9; //

};

Identity and Access Management (IAM) APIsUse the following APIs to perform tenant management, role management, user management, and group management operations.

Organization Management APIsUse the following APIs to create, view, update, and delete an organization.

Create an Organization

Required Permissions You must have the Create Organization permission to perform this operation.

API /api/organizations

Method POST


name

string

Organization name.

parentId

string

Immediate parent in the organization hierarchy.

status

string

n INACTIVE

n ACTIVE

domainName

string

Enter a unique identifier name to identify your organization with. If you are a part of multiple organizations, use this identifier when signing in so that VMware Pulse IoT center associates you with the correct organization.

Input Example

{

"name": "",

"parentId":"",

"status":"",

"domainName":""

}

Response{

"id": "string"

}


VMware, Inc. 89

Get a List of Organizations

Required Permissions You must have the View Organization permission to perform this operation.

API /api/organizations

Method GET

Required Parameters None.

Response{

"tenants": [

{

"id": "",

"name": "",

"parentId": "",

"status": "",

"domainName":"",

"createdTime": "",

"lastUpdatedTime": "",

"updateVersion": 1

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,

"totalElements": "11",

"totalPages": "2"

}

}


VMware, Inc. 90

Get an Organization by ID

Required Permissions You must have the View Organization permission to perform this operation.

API /api/organizations/{id}

Method GET


id

string

Organization ID.

domainName

string


Response{

"id":"",

"name": "",

"parentId":"",

"status":"",

"domainName":"",

"createdTime": "",


"updateVersion":1,

"orgId":"",

"createdBy":"",

"lastUpdatedBy":""

}

Update an Organization

Required Permissions You must have the Edit Organization permission to perform this operation.


Method PUT


name

string

Organization name.

parentId

string

Immediate parent in the organization hierarchy.


VMware, Inc. 91

Name Description

status

string

n INACTIVE

n ACTIVE

domainName

string


Input Example

{

"name": "",

"parentId":"",

"status":"",

"domainName":"",

"updateVersion":1,

}

Response{

"id": "string"

}

Delete a Organization

Required Permissions You must have the Delete Organization permission to perform this operation.


Method DELETE


id

string

Organization ID.

Response{}

User Management APIsUse the following APIs to create, fetch, update, and delete users.


VMware, Inc. 92

Create a User

Required Permissions You must have the Create User permission to perform this operation.

API /api/users

Method POST


userName

string

User name.

displayName

string

User display name.

password

string

The password for the user.

status

string

Status of the user:

n INACTIVE: The user is inactive.

n ACTIVE: The user is active.

email

string

Email address of the user.

roles

string

Array of role Ids.

group

string

Array of group Ids.

Input Example{

"userName": "",

"displayName": "",

"password":"",

"status":"",

"email":"",

"roles":[

],

"groups":[

],

}

Response{

"id": "string"

}


VMware, Inc. 93

Get a User by ID

Required Permissions You must have the View User permission to perform this operation.

API /api/users/{id}

Method GET

Required Parameters Name Type Description

id string User ID.

Response{

"id": "",

"userName": "",

"displayName": "",

"tenantId": "",

"status": "",

"email": "",

"accessToken":"",

"refreshToken":"",

"roles":[//Array of role details object],

"groups": [//Array of role details object],

"createdTime": "",


"updateVersion":1

}

Get a List of Users


API /api/users

Method GET

Parameters None

Response{

"users": [

{

"id": "",

"userName": "",

"displayName": "",

"tenantId": "",

"status": "",

"email": "",

"accessToken": "",

"refreshToken": "",

"roles": [],

"groups":[],


VMware, Inc. 94

"createdTime": "",


"updateVersion":1

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}

Update a User

Required Permissions You must have the Edit User permission to perform this operation.

API /api/users/{id}

Method PUT


userName

string

User name.

displayName

string

User display name.

password

string

The password for the user.

status

string

Status of the user:

n INACTIVE: The user is inactive.

n ACTIVE: The user is active.

email

string

Email address of the user.

roles

string

Array of role Ids.

group

string

Array of group Ids.

Input Example{

"userName": "",

"displayName": "",

"password":"VMware1!",

"status": "",

"email": "",


VMware, Inc. 95

"roles":[],

"groups":[],

"updateVersion":1

}

Response{

"id": "string"

}

Delete a User

Required Permissions You must have the Delete User permission to perform this operation.

API /api/users/{id}

Method DELETE


id

string

User ID.

Response{}

Get User Details


API /api/me

Method GET


Response{

"userName": "[email protected]",

"displayName": "sysadmin",

"tenantId": "5bc2126a69eac734fe16e9b1",

"permissions": [

"CREATE_TENANT",

"VIEW_TENANT",

"EDIT_TENANT",

"EDIT_TENANT_SETTINGS",

"DELETE_TENANT"

]

}


VMware, Inc. 96

Role Management APIsUse the following APIs to create, fetch, update, and delete roles.

Create a Role

Required Permissions You must have the Create Role permission to perform this operation.

API /api/roles

Method POST


name

string

Role name.

description

string

Description of the role.

permissions

n Permission number

integer

Permission numbers.

Input Example{

"name": "",

"description": "",

"permissions": [

// Integer array of permission numbers

]

}

Response{

"id": "string"

}


VMware, Inc. 97

Get a Role by ID

Required Permissions You must have the View Role permission to perform this operation.

API /api/roles/{id}

Method GET


id

string

Role ID.

Response{

"id": "",

"name": "",

"description": "",

"isDefault": false,

"permissions": [

{

"permissionNumber":1,

"name": "",

"description": ""

},

{


"name": "",

"description": ""

}

],

"createdTime":"",

"lastUpdatedTime":"",

"updateVersion":1

}

Get a List of Roles


API /api/roles

Method GET




VMware, Inc. 98

None

Response{

"roles": [

{

"id": "",

"name": "",

"isDefault": false,

"description":"",

"createdTime": "",


"updateVersion":1

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}

Update a Role

Required Permissions You must have the Edit Role permission to perform this operation.

API /api/roles/{id}

Method PUT


name

string

Role name.

description

string


permissions

n Permission number

integer

n name

string

n description

string

Permission number, name, and description of the role.

updateVersion

string

Version of the update.


VMware, Inc. 99

Input Example{

"name": "",

"description":"",

"permissions":[],

"updateVersion":1

}

Response{

"id": "string"

}

Delete a Role

Required Permissions You must have the Delete Role permission to perform this operation.

API /api/roles/{id}

Method DELETE


id

string

Role ID.

Response{}

List Users for Role


API /api/console-roles/{id}/users?page.number=1&page.size=10

Method GET

Required Parameters Parameter Description


Response{

"users": [

{

"id": "",

"userName": "",

"displayName": "",

"status": "",

"orgId": "",


VMware, Inc. 100

"createdTime": "",


"updateVersion": 5,

"createdBy": "s",

"lastUpdatedBy": ""

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}

Group Management APIsUse the following APIs to create, fetch, update, and delete user groups.

Create a Group

Required Permissions You must have the Create Group permission to perform this operation.

API /api/groups

Method POST


name

string

Group name.

description

string

Description of the group.

roles

string

The roles assigned to the group.

Input Example{

"name": "",

"description": "",

"roles": [//Array of role ids]

}

Response{

"id": "string"

}


VMware, Inc. 101

Get a Group by ID

Required Permissions You must have the View Group permission to perform this operation.

API /api/groups/{id}

Method GET


id

string

The group's identifier.

Response{

"id": "",

"name": "",

"description": "",

"isDefault": false,

"roles": [

{

"name": ""

},

{

"name": ""

}

],

"createdTime":"",

"lastUpdatedTime":"",

"updateVersion":1,

"createdBy":"",

"lastUpdatedBy":""

}


VMware, Inc. 102

Get a List of Groups


API /api/groups

Method GET


name

string

Enter a minimum of 3 letters of the group name that you are searching for. Group names that contain these 3 letters in any order are displayed.


Response{

"groups": [

{

"id": "",

"name": "",

"description":"",

"isDefault": false,

"createdTime": "",


"createdBy":"",

"lastUpdatedBy":"",

"updateVersion":1

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}


VMware, Inc. 103

Update a Group

Required Permissions You must have the Edit Group permission to perform this operation.


Method PUT


name

string

Name of the role.

description

string


roles

string

The roles assigned to the group.

updateVersion

integer

The update version of the role.

Input Example{

"name": "",

"description":"",

"roles":[//Array of role ids],

"updateVersion":1

}

Response{

"id": "string"

}

Delete a Group

Required Permissions You must have the Delete Group permission to perform this operation.


Method DELETE


id

string

The group's identifier.

Response{}


VMware, Inc. 104

List Users for Group


API /api/console-groups/{id}/users?page.number=1&page.size=10

Method GET

Required Parameters Parameter Description


Response{

"users": [

{

"id": "",

"userName": "",

"displayName": "",

"status": "",

"orgId": "",

"createdTime": "",


"updateVersion": 5,

"createdBy": "s",

"lastUpdatedBy": ""

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}

Permission Management APIsUse the following API to fetch permissions.


VMware, Inc. 105

Get a List of Permissions

API /api/permissions

Method GET

Parameters None

Response{

"permissions": [

{


"name": "",

"description": "",

"updateVersion":1

},

{


"name": "",

"description": "",

"updateVersion":1

}

]

}

Organization Settings APIsUse the following APIs to view and update your organization settings.

Update Organization Settings

Required Permissions You must have the Edit Organization Settings permission to perform this operation.

API /api/organizations/{id}/settings

Method PUT


category

string

Enter categories such as metric, campaign, identity, and notifications. A system namespace is available by default.

settings

string

Enter the settings for the organization.


VMware, Inc. 106

Input Example[{

"category" : "campaign",

"settings" : {

"campaign-approval-needed": "false"

}

}]

Response{

"id": ""

}

Get Organization Settings for a Category

Required Permissions You must have the View Organization Settings permission to perform this operation.

API /api/organizations/{id}/settings?category=<category>

Method GET


category

string

Enter categories such as metric, campaign, identity, and notifications. A system namespace is available by default.

Response{

"category" : "iam",

"settings" : {

"delete-ttl-days" : 20

},

}


VMware, Inc. 107

Get Organization Settings

Required Permissions You must have the View Organization Settings permission to perform this operation.

API /api/organizations/{id}/settings

Method GET


Response

[{

"category" : "campaign",

"settings" : {

"campaign-approval-needed": "false"

}

}]

Password Management APIsUse the following APIs to generate a password recovery link and reset the password.

Forgot Password

Header If the user exists in multiple organizations, pass the request header x-org-domain-name.

API /api/users/forgot-password

Description This API takes the user name as input and generates a password recovery link. If the user name is valid, an email with the password recovery link is sent to the user. The link is valid for 15 minutes.

Method POST


username

string

User name.

Input Example{

"username":""

}

Response{ }


VMware, Inc. 108

Reset Password

API /api/users/reset-password

Description This API resets the password for the given user name.

Method POST


password

string

New password.

Input Example{

"password":""

}

Response{ }

Token Management APIsUse the following APIs to generate access and refresh tokens.

Create a Token for the User

Header If the user exists in multiple organizations, pass the request header x-org-domain-name.

API /api/tokens

Method GET


Response{


"expiresInSecs": "1543317540",

"accessTokenExpiresAt": "1543317540",

"refreshToken": "string",

"refreshTokenExpiresAt": "1544519940"

}


VMware, Inc. 109

Generate Access Token Using Refresh Token

API /api/tokens/refresh

Method GET


Response{


"accessTokenExpiresAt": "1543317540"

"expiresInSecs": 0,

"refreshToken": null

}

Notification APIsThis section lists the APIs for Notification Destinations, Notification Definitions, and Notification Instances.

Notification Definition APIsUse the following APIs to create, update, get, and delete notification definitions.

Create a Notification Definition

Required Permissions You must have the Create Notification Definition permission to perform this operation.

API /api/notification-definitions

Method POST


name

string

Name of the notification definition. (Mandatory)

description

string

Description of the notification definition. (Optional)


VMware, Inc. 110

Name Description

httpParameters

json

It is mandatory to include one of the following options, but not both:

n http_parameters

n email_parameters

If the notification definition's protocol is HTTP, then httpParameters is mandatory.

It includes the following fields:

n relativePath

string : The relative API endpoint where the notifications are to be delivered.

n headers

json : The list of headers that is expected by the API endpoint.

n key

string: Header key.

n value

string: Header value.

n payloadTemplate

string: The custom REST template for receiving notifications.

retrySchedule

n retryInterval: The retry interval in milliseconds.

n maxRetryCount: The maximum number of times to retry.

n requestTimeout: The response wait time in milliseconds.

sslTlsVersion

n NO_CERT: Use this option if the REST server is non-TLS.

n TLS1_2: Use this option if the REST server is TLS.

(Mandatory)

host

Hostname or IP address of the REST server. (Mandatory)

port

Port number of the REST server. (Mandatory)

certificate

Certificate of the REST server.

Mandatory if sslTlsVersion is other than NO_CERT.

authenticationType

n NO_AUTH: Use this option if the REST server does not require any authentication.

n BASIC: Use this option if the REST server requires basic authentication.

(Mandatory)

username

User name is mandatory if authenticationType is BASIC.

password

Password is mandatory if authenticationType is BASIC.


VMware, Inc. 111

Name Description

emailParameters

json

It is mandatory to include one of the following options, but not both:

n http_parameters

n email_parameters

emailParameters is mandatory for sending email notifications.

It consists of the following fields:

n emailRecipients: Consists of a list of email recipients. It is mandatory to enter at least one recipient.

n emailSubjectTemplate: Consists of the email subject. You can derive the keys from the Create Default Template API.

n emailBodyTemplate: Consists of the email body.

n senderEmailAddress: Consists of the sender's email address.

n senderName: Consists of the sender's name.

schedule

n repeatInterval: The repeat interval in milliseconds.

n maxRepetition: The maximum number of repetitions.

onFailure

stringThe definition id for which the instance gets triggered if the notification for the current definition has a FAILED status.

onSuccess

stringThe definition id for which the instance gets triggered if the notification for the current definition has a SENT status.

onCompletion

stringThe definition id for which the instance gets triggered irrespective of the status of the instance for the current definition.

protocol n HTTP

Use the HTTP protocol to notify to an HTTP REST server.

n SMTP

Use the SMTP protocol to notify using Emails

(Mandatory)

Input Example for HTTP Notification Definition {

"name": "REST",

"description": "REST Definition",

"protocol": "HTTP",

"httpParameters": {

"headers": [{

"key": "Content-Type",

"value": "application/json"

}],

"relativePath": "/basicauth/notification",

"retrySchedule": {

"retryInterval": 120000,

"maxRetryCount": 5,

"requestTimeout": 5000

},

"sslTlsVersion": "TLS1_2",

"host": "10.5.103.137",

"port": 9403,

"certificate": "-----BEGIN CERTIFICATE-----


VMware, Inc. 112

MIIDcTCCAlmgAwIBAgIEXO9mujANBgkqhkiG9w0BAQsFADBwMQswCQYDVQQGEwJJ

TjESMBAGA1UECAwJS2FybmF0YWthMRIwEAYDVQQHDAlCZW5nYWx1cnUxDzANBgNV

BAoMBlZNd2FyZTESMBAGA1UECwwJUHVsc2UgSW9UMRQwEgYDVQQDDAtNb2NrIFNl

cnZlcjAeFw0xOTA1MzAwNTE0MzRaFw0yMDA1MjkwNTE0MzRaMHAxCzAJBgNVBAYT

AklOMRIwEAYDVQQIDAlLYXJuYXRha2ExEjAQBgNVBAcMCUJlbmdhbHVydTEPMA0G

A1UECgwGVk13YXJlMRIwEAYDVQQLDAlQdWxzZSBJb1QxFDASBgNVBAMMC01vY2sg

U2VydmVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3YnPOFGEN3c7

6 Zu5UPyhZf / +fv8LS0xVs6jqZ1PP8ra1ZNvJUTd10gih4WdHDGUm6 / 35 OzfWQyYT

Z2RtTl + gnaw / 6 Ti3IUp / yrE0mqWa6AlR +

i3CsETO7YA5o31M86fmVyvB8NyTqrqw

yZ7ufuJd12TPnl7ZiBNLAavowJ5i8YUwXOpvwyYLV8HXQ / B4ljv8Zdpn0tex0AzE +

sgYVd7S1CtPwh4ozy4Xig8Yow5MkAAwNMcuPBkE7LtqHu + Sez6JUCsRkZxJhiLL

gUUuJw9DdhyMZDR7Eqsd7 / KiAqlQ9StoZDjpED1HWIiq6LRZDZwpLFaG / ixzfXZ +

x1trMy0 / eQIDAQABoxMwETAPBgNVHREECDAGhwQKBWeJMA0GCSqGSIb3DQEBCwUA

A4IBAQAKcJlyE6tQBpSoVW2GqTVm93 / Z3 / f4QZreAIUogJsCOO / ZBbED6WrpKFLO

QZGOmr4q9i09w0IeWP6P2yL2KImfQsn9D + LpreA10h7Lz6a9b / 0 icSpgeHP1dBII

BsK3tFG2VlCHP0W / h7fnOAlUeoZlYy / WWxrAtTnS5cmX4cNaeI6441zUZdB3kYHS

XKEFnNZVFa4weJb + cR84gB6xy5gsFaz8y3X40jxYNq4VuML + k4iprrV86mlX6BIH

rM2MRYnpjm8j9MCuqrBmUOadKDu6PSUQ8IEhsH2IDXNIAJWBNO6MnneLaxKge1 / s

46 bChTVzwk2uwH + RGQOkTqLkqUYj

-- -- - END CERTIFICATE-- -- - ",

"authenticationType": "BASIC",

"username": "root",

"password": "VMware1!"

},

"onSuccess": "61871b1f-3d33-4203-a6b3-880d2b4e5a1a",

"onFailure": "61871b1f-3d33-4203-a6b3-880d2b4e5a1a",

"onCompletion": "61871b1f-3d33-4203-a6b3-880d2b4e5a1a"

}

Input Example for SMTP or Email Notification Definition

{

"name": "Email",

"description": "Email Definition",

"protocol": "SMTP",

"emailParameters": {

"senderEmailAddress": "[email protected]",

"senderName": "svc.pulse-notify",

"emailSubjectTemplate": "Notification for Alert ${alertState}",

"emailRecipients": [

"[email protected]"

],

"schedule": {

"repeatInterval": 120000,

"maxRepetition": 5

}

}

}

Response{

"id": "5bf29d8178d80c88c89df352"

}


VMware, Inc. 113

Get Notification Definition

Required Permissions You must have the View Notification Definition permission to perform this operation.

API /api/notification-definitions/{id}

Method GET


Sample Response{

"id": "5bf29d8178d80c88c89df352",

"name": "SampleHttpNotificationDefinition",

"description": "This is a sample notification definition",

"httpParameters": {

"relativePath": "/callback",

"headers": [

{



}

]

},

"retryCount": 2,

"tenantId": "5beaa559a40a82f457340c4d",

"createdTime": "1542470980533",

"lastUpdatedTime": "1542470980533",

"createdBy": "[email protected]",

"lastUpdatedBy": "[email protected]",

"updateVersion": 1

"payloadTemplate": "{\"description\" : \"${description}

\",\"deviceTemplateId\" : \"${deviceTemplateId}\",\"deviceId\" : \"$

{deviceId}\",\"triggerCount\": \"${triggerCount}\"}"

}

}

Update Notification Definition

Required Permissions You must have the Edit Notification Definition permission to perform this operation.


Method PUT


id

string

Notification definition ID. (Mandatory)

name

string

Name of the notification definition. (Optional)


VMware, Inc. 114

Name Description

description

string

Description of the notification definition. (Optional)

httpParameters

json

If the notification definition's protocol is HTTP, then httpParameters is mandatory.

You cannot edit the protocol type.

It includes the following fields:

n relativePath

string : The relative API endpoint where the notifications are to be delivered.

n headers

json : The list of headers that is expected by the API endpoint.

n key

string: Header key.

n value

string: Header value.

n payloadTemplate

string: The custom REST template for receiving notifications.

retrySchedule

n retryInterval: The retry interval in milliseconds.

n maxRetryCount: The maximum number of times to retry.

n requestTimeout: The response wait time in milliseconds.

sslTlsVersion

n NO_CERT: Use this option if the REST server is non-TLS.

n TLS1_2: Use this option if the REST server is TLS.

(Mandatory)

host

Hostname or IP address of the REST server. (Mandatory)

port

Port number of the REST server. (Mandatory)

certificate

Certificate of the REST server.

authenticationType

n NO_AUTH: Use this option if the REST server does not require any authentication.

n BASIC: Use this option if the REST server requires basic authentication.

(Mandatory)

username

User name is mandatory if authenticationType is BASIC.

password

Password is mandatory if authenticationType is BASIC.


VMware, Inc. 115

Name Description

emailParameters

json

You cannot edit the protocol type.

emailParameters is mandatory for sending email notifications.

It consists of the following fields:

n emailRecipients: Consists of a list of email recipients. It is mandatory to enter at least one recipient.

n emailSubjectTemplate: Consists of the email subject. You can derive the keys from the Create Default Template API.

n emailBodyTemplate: Consists of the email body.

n senderEmailAddress: Consists of the sender's email address.

n senderName: Consists of the sender's name.

schedule

n repeatInterval: The repeat interval in milliseconds.

n maxRepetition: The maximum number of repetitions.

onFailure

stringThe definition id for which the instance gets triggered if the notification for the current definition has a FAILED status.

onSuccess

stringThe definition id for which the instance gets triggered if the notification for the current definition has a SENT status.

onCompletion

stringThe definition id for which the instance gets triggered irrespective of the status of the instance for the current definition.

Input Example for HTTP Update Notification Definition

{


"description": "This is a sample HTTP Notification Definition",

"httpParameters": {

"headers": [{

"key": "content-type",


}],

"relativePath": "/basicauth/notification",

"retrySchedule": {

"retryInterval": 5000,

"maxRetryCount": 1,

"requestTimeout": 5000

}

},

"onFailure": "b6ece001-88d6-4300-aca8-9d515fd906c8",

"onSuccess": "7024eb44-b5ec-47c0-9264-51015a2917a6",

"onCompletion": "7024eb44-b5ec-47c0-9264-51015a2917a6"

}

Input Example for SMTP Update Notification Definition

{

"name": "SampleSmtpNotificationDefinition",

"description": "This is a sample Smtp Notification Definition",



VMware, Inc. 116


"senderName": "Sample name",


"[email protected]"

],

"schedule": {

"repeatInterval": 0, //Time in milliseconds

"maxRepetition": 0 //Time in milliseconds

}

}

}

Response{

"id": "5bf29d8178d80c88c89df352"

}

Delete Notification Definition

Required Permissions You must have the Delete Notification Definition permission to perform this operation.


Method DELETE


id

string


Response{}

List All Notification Definitions

Required Permissions You must have the View Notification Definition permission to perform this operation.

API /api/notification-definitions

Method GET


Response{

"notificationDefinitions": [

{

"id": "5bf29d8243d80c88c25an910",


VMware, Inc. 117

"name": "SampleSmtpNotificationDefinition",




"[email protected]",

"[email protected]"

],


"senderName": "User 3",

"emailSubjectTemplate": "Notification for Alert ${alertState}",

"emailBodyTemplate": "<html lang=\"en\"> Notification for alert

${alertDefinitionId} </html>"

},


"createdTime": "1542626689123",




"updateVersion": 1

},

{

"id": "5bf29d8178d80c88c89df352",



"httpParameters": {

"relativePath": "/callback",

"headers": [

{



}

],

"payloadTemplate": "{\"description\" : \"${description}

\",\"deviceTemplateId\" : \"${deviceTemplateId}\",\"deviceId\" :

\"$

{deviceId}\",\"triggerCount\": \"${triggerCount}\"}"

},

"retryCount": 1,


"createdTime": "1542622551030",




"updateVersion": 1

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}


VMware, Inc. 118

Get Template

API /api/notification-templates

Method GET

Required Parameters type. For example, /api/notification-templates?type=default

Response{

"templateKeys": [

{

"key": "entityType",

"description": "Entity type like Alert, campaign for which

notification is generated"

},

{

"key": "alertSeverity",

"description": "Alert severity defined in the alert

definition."

},

{

"key": "triggersMetricName",

"description": "Metric name for which alert was triggered"

},

{

"key": "description",

"description": "Description of alert"

},

{

"key": "recommendation",

"description": "Defined in alert definition who takes

remediation steps for user"

},

{

"key": "entityId",

"description": "Id of the generated alert"

},

{

"key": "alertTemplate",

"description": "Alert template selected by user"

},

{

"key": "notificationInstanceId",

"description": "Id of notification instance created for this

alert"

},

{

"key": "deviceId",

"description": "Device Id for which alert is generated"

},

{

"key": "triggersTimeMs",

"description": "Time for which alert was triggered"

},


VMware, Inc. 119

{

"key": "triggerCount",

"description": "No of times metric exceeded the threshold

which results in triggering alert"

},

{

"key": "duration",

"description": "Duration (in sec) of absence of metrics from

offline alert triggering device"

},

{

"key": "lambda",

"description": "Threshold value for triggering alert"

},

{

"key": "cancelCount",

"description": "Count of consecutive ingestion on which the

alert cancellation will take place"

},

{

"key": "entityState",

"description": "Present state of the entity like active,

user_acknowledged etc"

},

{

"key": "entityName",

"description": "Entity name for which notification is

generated"

},

{

"key": "deviceTemplateId",

"description": "ID of device template"

},

{

"key": "createdTime",

"description": "Time at which alert was created"

},

{

"key": "lastUpdatedTime",

"description": "Last time when alert was updated"

},

{

"key": "metrics",

"description": "List of metrics on a threshold alert symptom"

},

{

"key": "alertDefinitionId",

"description": "alert definition id"

},

{

"key": "triggersValue",

"description": "The value which caused the triggering of alert"

},

{


VMware, Inc. 120

"key": "userAcknowledged",

"description": "User who acknowledged the alert"

}

],

"subject": "${entityType} ${entityState} Notification for $

{entityType} ${entityName}(${entityId})",

"default.alert.body.template": "<html lang=\"en\"> <head> <meta

charset=\"UTF-8\"> <meta name=\"viewport\" content=\"width=device-

width, initial-scale=1.0\"> <meta http-equiv=\"Content-Type\" content=

\"text/html\"> <link rel=\" stylesheet\" href=\"https://unpkg.com/

[email protected]/clarity-ui.min.css\"> </head> <body style=\"word-

wrap:break-word;-webkit-nbsp-mode:space;color:rgb(0,0,0)\"> <div xmlns=

\"http://www.w3.org/1999/xhtml\" lang=\"en\"> <style type=\"text/css\"

media=\"all\"> @font-face { font-family: 'subjectFont'; src:

url('https://console.cloud.vmware.com/csp/gateway/portal/assets/fonts/

Metropolis/Metropolis-Light.otf') format('opentype'); src: url('https://

console.cloud.vmware.com/csp/gateway/portal/assets/fonts/Metropolis/

Metropolis-Light.ttf') format('truetype'); src: url('https://


Metropolis-Light.woff') format('woff'); src: url('https://


Metropolis-Light.woff2') format('woff2'); font-weight: normal; font-

style: normal; } @font-face { font-family: 'bodyFont'; src:


Metropolis/Metropolis-Regular.otf') format('opentype'); src:


Metropolis/Metropolis-Regular.ttf') format('truetype'); src:


Metropolis/Metropolis-Regular.woff') format('woff'); src: url('https://


Metropolis-Regular.woff2') format('woff2'); font-weight: normal; font-

style: normal; } .wrapper-container { overflow-wrap: normal; background-

color: #fafafa; /*gray color*/ } .container { max-width: 600px; margin:

0 auto; background-color: #ffffff; /*white color*/ } .csp-header { font-

family: 'subjectFont', Helvetica, Arial, sans-serif; font-size: 23px;

padding: 24px

Notification Instances APIsUse the following APIs to retrieve notification instances.

Get Notification Instance by ID

Required Permissions You must have the View Notification Instance permission to perform this operation.

API /api/notification-instances/{id}

Method GET


VMware, Inc. 121


id

string

Notification instance ID. (Mandatory)

Response{

"id": "5bf29d8178d80c88c32sq819",

"notificationDefinitionId": "5bf29d8178d80c88c89df352",

"entityState": "ENTITY_CREATED",

"entityId": "1234567890abcef1234567890abcef",

"entityName": "TestEntity-001",

"entityType": "TestEntity",

"additionalDetails": [

{

"key": "temperature",

"valueInt64": 20

}

],

"responseStatus": 500,

"responseBody": "Internal Server Error",

"status": "FAILED",


"createdTime": "1542626737552",




"updateVersion": 2

}

List All Notification Instances

Required Permissions You must have the View Notification Instance permission to perform this operation.

API /api/notification-instances

Method GET


Response{

"notificationInstances": [

{

"id": "5bf29d8178d80c88c32sq819",

"notificationDefinitionId": "5bf29d8178d80c88c89df352",






{


VMware, Inc. 122

"key": "temperature",

"valueInt64": 20

}

],

"status": "FAILED",

"responseStatus": 500,

"responseBody": "Internal Server Error",


"createdTime": "1542626737552",




"updateVersion": 2

},

{

"id": "6dc29d9378d80c88c25ed317",

"notificationDefinitionId": "5bf29d8243d80c88c25an910",






{

"key": "CPU",

"valueInt64": 100

}

],

"status": "NOTIFIED",


"createdTime": "1542622648733",




"updateVersion": 2

}

],

"pageInfo": {

"page": 1,

"pageSize": 10,


"totalPages": "1"

}

}

System Notification APIsUse the following APIs to view system notifications. System notifications are generated when there is a system downtime. The notifications are sent to the users through email or displayed on the UI.

Required PermissionsYou must have the View System Notification Instance permission to perform these operations.


VMware, Inc. 123

Get System Notification Instances

Description Get a list of system notification instances.

API /api/system-notification-instances

Method GET


Response Example{

"systemNotificationInstances": [

{

"title": "Sample system notification",

"content": "Sample content",

"startTime": 1568270646743,

"endTime": 1568356200000,

"consoleParameters": {},

"emailParameters": {},

"status": "INSTANTIATED",

"orgId": "eb962043-3bc4-43a5-afe5-f3d1d7c97d8a",

"createdTime": 1568885017232,


"updateVersion": 1,

"createdBy": "25cdc85d-b6f2-4837-88ea-74b809e34e63",

"lastUpdatedBy": "25cdc85d-b6f2-4837-88ea-74b809e34e63",

"expireAt": 1571477017232,

"id": "a9451b48-f664-4555-a23b-8993019b8539"

}

],

"pageInfo": {

"totalPages": 1,

"page": 1,

"pageSize": 10,

"totalElements": 1

}

}


VMware, Inc. 124

Get a System Notification Instance by ID

Description Get a system notification instance by ID.

API /api/system-notification-instances/{id}

Method GET


id

string

System notification ID.

Response Example{

"title": "System downtime",

"content": "System downtime on 1st Feb between 1 AM to 3AM",

"startTime": 1549279788621,

"endTime": 1549279788621,

"status": "INSTANTIATED",

"tenantId": "7df0d3ad-01c9-4d16-a39c-96ca8c0e0625",

"createdTime": 1549367946749,


"updateVersion": 2,

"createdBy": "nodemanagement@iotc-system",

"lastUpdatedBy": "nodemanagement@iotc-system",

"expireAt": 1551959946749,

"id": "4bfa3f84-e67d-4cea-85bb-2e5d923b2fc0"

}

Certificate Management APIsUse the following APIs to create, update and delete certificates.

Generate a CA Certificate

Required Permissions You must have CREATE_CERTIFICATE permissions to perform this operation.

API /api/certificates/generate

Method POST


Input Example of Generate a Self-Signed CA Certificate

{

"certificateType": "CA",

"displayName": "Test-CA",

"validity": 365,

"countryName": "US",


VMware, Inc. 125

"stateOrProvinceName": "CA",

"localityName": "Palo Alto",

"organizationName": "VMWare Inc.",

"organizationalUnitName": "R&D",

"emailAddress": "[email protected]",

"commonName": "Test-CA"

}

Note The output of generate CA certificate is a certificate ID. This must be passed into caCertificateID field in generate entity certificate and generate entity certificate from CSR request.

Input Example of Generate Entity Certificate

{

"certificateType": "ENTITY",

"displayName": "Entity1",

"validity": 90,

"countryName": "US",

"stateOrProvinceName": "CA",

"localityName": "Palo Alto",

"organizationName": "VMWare Inc.",

"organizationalUnitName": "R&D",

"emailAddress": "[email protected]",

"commonName": "Entity1",

"caCertificateId": "84fee0ac-65fd-4b3d-aa36-917582cfc4f1"

}

Input Example of Generate Entity Certificate from CSR

{


"displayName": "Entity1",

"validity": 90,

"csr": "-----BEGIN CERTIFICATE REQUEST-----

\nMIICuDCCAaACAQAwczELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQH

\nDAlQYWxvIEFsdG8xFDASBgNVBAoMC1ZNd2FyZSBJbmMuMS0wKwYDVQQDDCRhMGM4\nN2Qx

My05Mjg2LTRiMDQtOWFlMy1jMDBhN2E4YzgxMGIwggEiMA0GCSqGSIb3DQEB

\nAQUAA4IBDwAwggEKAoIBAQDtS3iA2+nynRiZVgPOKxphMPLwcE9p8yMO2IqImevd

\nG6hCtINqNw/jAgxF/Ja0SvYLzStvl0E+pY6wVq8xD0OWoo9cpwVSAVaoq2wcA/VM

\nTaU7OQtLaoRbPXgYCTE3okFaZsQ+xtFAyPFEvnOD5dItAhKEpYv0noKxPyTeBmIq

\naOAGBtEpCk7uwRtgPLm6JfoDBI2LK54hAbsS0kHOkOMX6Cg2fu1+9CnVNZIFYf76\nsKS

+lT5fLitgfPlB7lJZCmVWriZMybD3IA4EwiTG0UDUQ08LAhdAw0nWKAAyGIuK\nRJ

+WjHPFpt0MWZ8i3265Iftns0u293gau7+Z9hjUQ3qNAgMBAAGgADANBgkqhkiG

\n9w0BAQsFAAOCAQEAoinoPp0V1n2iFc4z3WvvSotUhTKeRpTvpkifgyLbcFcRPkM0\nPpZV

lUVypDwk+zpm2MqRogJu+7iN6xsF7RQreXXAQUw4P8xNiySS4fMie0hMjpri

\nHGWVA7EsjadabvmBCwCoeWhd+hs0dp2VCDHRZh2yYrKpgJcQephkKGH+sjUkR2kd

\n354U4bNa9gIrGers7z7KNcFIOOfc6VuLIG+th4sJkTCDQ386gLzmfF8bhsiOro6z

\nlxEaUWdU1QXZJqJYDfpCPb37nyJb4tN/

qJGaGvjuU20ivhroIcFNp2fSfKuvQ294\nb6eVxYLKwtrZQcaJ5RwZ9D0tutqtQgngmekJRA

==\n-----END CERTIFICATE REQUEST-----\n",

"caCertificateId": "84fee0ac-65fd-4b3d-aa36-917582cfc4f1"


VMware, Inc. 126

Response{

"id": "84fee0ac-65fd-4b3d-aa36-917582cfc4f1"

}

Register an External CA Certificate

Required Permissions You must have the CREATE_CERTIFICATE permission to perform this operation.

API /api/certificates

Method POST


Sample Request for Register CA Certificate

{

"certificateType": "CA",

"displayName": "TestCA",


\nMIIEAzCCAuugAwIBAgIJAO3/xKDSEL0PMA0GCSqGSIb3DQEBCwUAMF4xCzAJBgNV

\nBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRIwEAYDVQQHDAlQYWxvIEFsdG8x

\nETAPBgNVBAoMCFZNVy1UZXN0MRMwEQYDVQQDDApUZXN0Q0FDZXJ0MB4XDTE5MDky

\nOTA5NTU0MVoXDTIwMDkyODA5NTU0MVowXjELMAkGA1UEBhMCVVMxEzARBgNVBAgM

\nCkNhbGlmb3JuaWExEjAQBgNVBAcMCVBhbG8gQWx0bzERMA8GA1UECgwIVk1XLVRl

\nc3QxEzARBgNVBAMMClRlc3RDQUNlcnQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw

\nggEKAoIBAQDfhlnvJ+/cyYEqtkVbnNx0wXiDEYf5cNpvbHCTHWja+JEZg8P3f5VB

\nQIF8HX65BVVnE3f7nXPSdN+/BTUPh7qsnwyH5HcnnUOvMlaida2yKUfKC8ZJYCVv

\nxNTUk7TWfTWeMSVY++/HfcfQzHQ8PRtU8LqjEdvsLHcAEZJO+4fTVUTYikGeIeRj

\n66OEEpK69l2NK11VJ0mXezw1wFDMP318kUZqWdtJIWKBkXMrSIrL9aJQlrYxo63A

\nbJlM3UGrGxQl1wKcVBpXF9RQ6t0pEqYxXIG876b0LyvHRH2Ktmth1nCDrrKzq0LY

\nz5Lv7k6PdZEkQ4PeMS2NGRBJnbWmOA2PAgMBAAGjgcMwgcAwHQYDVR0OBBYEFHo9\nVCfL

M9PTZyape/pY14Nut/BLMIGQBgNVHSMEgYgwgYWAFHo9VCfLM9PTZyape/pY\n14Nut/

BLoWKkYDBeMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTES

\nMBAGA1UEBwwJUGFsbyBBbHRvMREwDwYDVQQKDAhWTVctVGVzdDETMBEGA1UEAwwK

\nVGVzdENBQ2VydIIJAO3/xKDSEL0PMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEL

\nBQADggEBAK4UrP7kiU8dmOVgQw2dKcBeZS4vgbcLtJm7R

+BgmMGLVlz5RSWyUGN3\n2VqpgUVgTGO4wXMxpn/

K9+SKSRN4L2UexwsMZ6PpCbhYataLsb5WEPaVBC4Aue8k

\njQvz1QYNQBmtVf0JQd2S5edEj3b7D5wxgsLNgpkcScb/yK7rf0TGgARd4uj2jIXu

\nWLc1QgW2DDrz9+qfud9X3mi9+x1gero2+j65FJ//F8t9UU2GzJWIvJZIE74YP+gS

\nQZAFMQjIYHdz+lEyEhaIrvs2Hn4ux8dQnHEYVOqMNIPpmFiIE

+QmZm8q5MnH9lu1\noos2FYWcpDfazh9oqtsc5Uf+5BHTFpQ=\n

-----END CERTIFICATE-----\n",

"privateKeyVerificationCertificate": "-----BEGIN CERTIFICATE-----

\nMIIDKTCCAhECCQC/8PN1bxg4ezANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJV

\nUzETMBEGA1UECAwKQ2FsaWZvcm5pYTESMBAGA1UEBwwJUGFsbyBBbHRvMREwDwYD

\nVQQKDAhWTVctVGVzdDETMBEGA1UEAwwKVGVzdENBQ2VydDAeFw0xOTA5MjkwOTU4\nMTRa

Fw0yMDA5MjgwOTU4MTRaME8xCzAJBgNVBAYTAlVTMREwDwYDVQQKDAhWTVct

\nVGVzdDEtMCsGA1UEAwwkYTBjODdkMTMtOTI4Ni00YjA0LTlhZTMtYzAwYTdhOGM4\nMTBi

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlff5HOpU738EsErQ

\nxmEldKAB2FjHIIS0s4fGZixBSR5R+RpPpfSbnyGPsIhYZqqWr+nUW/TWUrSONeFt\nP14/


VMware, Inc. 127

FAtzHbZcnNAru9ODrTLMTJEsmxFU1NhcFmKIXbnaEuLLdL1o/h4pwpej3w6c

\nQbHv7kym1m/11aHxa4Btnp9lgNN0Qjx161wC325CO6C4yw+mmoOa35PhqxMEF5Aa

\nSUU6IqK9pl70zM0IASjbkPcbLkQYhjNpjzxk5jeeYSHIgoor0YlxdGPzj/EYzwSV

\nb35UoAM/A6TaamOsm2XHktht5QHsNnlWFfBMfS+kb33p/XbX7vyFrr9enEjPuPYn

\njV50gwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBf36PeazgEgZf09h3xgNpwZEBB

\n79ypJf8BItsro7oscblvxsuIgGxeYEyxE2ce7U/zlPKZNIWtdYZIpp95C976vhHy

\n6ObpJRaIwjACvGkOzZvZ2CpoVENyoAEWfdeOvz1SVkekjdRz6jBOvzfpKmyA1DW5\n2nai

TvwVNasRMPgGZPVDOBqGQOzW64xnk/EYEt3uqxY3/iL3jcIOOwFRyj6lzKan

\nqaDUIvaf6vGtIHFpuWNZq5D3VJwzmtdqZ7+oEavVW2JRv+fXA8xKVDQclVZ4qcuZ

\ncghLCt2aVDP7lpuePtBooTgQjl2fBahOlDc8MCm2Sz08bAwmfq2fbXfPM2Vv\n-----

END CERTIFICATE-----\n",

"state": "ACTIVE"

}

Sample Request for Register Entity Certificate

{


"displayName": "TestDevice1Cert",

"certificate": "-----BEGIN CERTIFICATE-----\nMIIDEjCCAfoCCQC/

8PN1bxg4fDANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJV


\nVQQKDAhWTVctVGVzdDETMBEGA1UEAwwKVGVzdENBQ2VydDAeFw0xOTA5MjkwOTU5\nMzVa

Fw0xOTEyMjgwOTU5MzVaMDgxCzAJBgNVBAYTAlVTMRAwDgYDVQQKDAdWTVct

\nVGVzMRcwFQYDVQQDDA5kZXZpY2UxLXJhbmRvbTCCASIwDQYJKoZIhvcNAQEBBQAD

\nggEPADCCAQoCggEBAKn

+UYn9bIFH0kDZ9dzJ2EHzrqqALrbW2j5ZFNvksYWLLG71\nB5ifBeGV7m

+UAbXzpmZfNm9injGHi9Y9Y0pJfJYYxLNIUdE/U1K6NBk5HbJJUCy/

\n6KX9aB7PA7N4h2d9YrQCDLOc7rlJBEaQkaRx+Hbm1jZis2poZTENJgxmdP4eGmQS\n2xoV

++IzXdXdS2Bo//

sOWXcSvVlWFQoLHfVvHOXuQnCXNnpRKsllZ161EQxF4HC8\n78Yd51EDqVp7jTmO8m4jZHYA

avZPL

+T3Xuz2U76ykj42ykWs6PU9hRPf4ehyMgo6\nkidErMplwx1yUszO9vfYUwmHBl7LPX4pajD

It/kCAwEAATANBgkqhkiG9w0BAQsF\nAAOCAQEAuHfQqohJI9NPr/

km320g0PeVY3U9NZkbGzgt5G9sznnaLTzQCe9YxM+z

\nc5lhloTdL6Us7J7Z5VT3t3f5CRGHyuQTHYgnE/inML1OKRc/5UlKznbdPfwOLsTg

\njPZ9KoP5F260CO1SCEKY448dNtMxsOehYO6GpsgB6RgInjYrbz40fklhw/Vz5ubg

\nbebyy84c/abDcKaxDsQUSgc8boWBVnVRG9gtiL6ifP18NbWjluwTsysOn6tHs0oS

\nMIApJXaJi2+PJ7jp729cm2MFpwSKKZc272dDJEOqa7GPjXtJ/8sg+2n3YrZjGq8x

\nAviQmnfUT8kwqeGefM3xHWYnF0SWPQ==\n-----END CERTIFICATE-----\n",

"caCertificateId": "261f5328-0822-47ce-85ce-c0a797b9911b",

"state": "ACTIVE"

}

Response"id": "7df0d3ad-01c9-4d16-a39c-96ca8c0e0625"

List the Certificates

Required Permissions You must have the VIEW_CERTIFICATE permission to perform this operation.

API /api/certificates


VMware, Inc. 128

Method GET

Required Parameters Parameters Values

queryType SHOW_CURRENT, SHOW_DESCENDANTS, SHOW_ANCESTORS, SHOW_ALL

state ACTIVE, REVOKED, EXPIRED

name CA, ENTITY

caCertificateId DEVICE

entityId If true, returns all entity certificates currently not assigned to any entity. If false, returns all entity certificates assigned to any entity.

Sample Request

Response{

"certificates": [

{


"state": "ACTIVE",
























+QmZm8q5MnH9lu1\noos2FYWcpDfazh9oqtsc5Uf+5BHTFpQ=\n-----END

CERTIFICATE-----\n",

"providerType": "UNKNOWN",

"subjectDN": "CN=TestDevice1Cert, O=VMW-Test, L=Palo Alto,

ST=California, C=US",

"issuerDN": "CN=TestDevice1Cert, O=VMW-Test, L=Palo Alto,


"validFrom": 1569751175000,


VMware, Inc. 129

"validTill": 1577527175000,

"serialNumber": "17149642101048261903",

"isRootCA": false,

"isCaCert": false,

"entityType": null,

"entityId": null,

"caCertificateId": "f2010f44-5200-48ca-bbcc-0f82d19341d0",

"additionalProperties": {},

"orgId": "a0c87d13-9286-4b04-9ae3-c00a7a8c810b",

"createdTime": 1569751434413,


"updateVersion": 1,

"createdBy": "40c3608a-3d7c-47f8-aa57-b8c799c8c971",

"lastUpdatedBy": "40c3608a-3d7c-47f8-aa57-b8c799c8c971",

"id": "0415f537-1d00-4353-97e3-ce4cb1124c78"

},

{

"displayName": "TestCACert",

"state": "ACTIVE",



























"subjectDN": "CN=TestCACert, O=VMW-Test, L=Palo Alto,


"issuerDN": "CN=TestCACert, O=VMW-Test, L=Palo Alto,


"validFrom": 1569750941000,

"validTill": 1601286941000,

"serialNumber": "121496423451048261287",

"isRootCA": true,

"isCaCert": true,


VMware, Inc. 130

"entityType": null,

"entityId": null,

"caCertificateId": null,



"createdTime": 1569751336660,


"updateVersion": 1,



"id": "f2010f44-5200-48ca-bbcc-0f82d19341d0"

}

],

"pageInfo": {

"totalPages": 1,

"page": 1,

"pageSize": 10,

"totalElements": 2

}

}

Assign a Certificate to an Entity

Required Permissions You must have the DEVICE_ADMIN permission to perform this operation.

API /api/certificates/{id}/assign

Method POST


id

stringCertificate identifier

Sample Request{

"entityType": "DEVICE",

"entityId": "1fa595a5-c851-4447-ba34-74a6057c5d00"

}

Response"id": "75ase0ac-65fd-4b3d-aa36-917582cfcff7"

Unassign a Certificate

Required Permissions You must have the DEVICE_ADMIN permission to perform this operation.

API /api/certificates/{id}/assign

Method POST


VMware, Inc. 131


id


Sample Request

Response{

"id": "75ase0ac-65fd-4b3d-aa36-917582cfcff7"

}

List the Certificate With the Given Id

Required Permissions You must have the VIEW_CERTIFICATE permission to perform this operation.

API /api/certificates/{id}

Method GET


id


Sample Request

Response{

"displayName": "TestCACert",

"state": "ACTIVE",

"certificate": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgIJAO3/

xKDSEL0PMA0GCSqGSIb3DQEBCwUAMF4xCzAJBgNV




















VMware, Inc. 132







"subjectDN": "CN=TestCACert, O=VMW-Test, L=Palo Alto, ST=California,

C=US",

"issuerDN": "CN=TestCACert, O=VMW-Test, L=Palo Alto, ST=California,

C=US",

"validFrom": 1569750941000,

"validTill": 1601286941000,

"serialNumber": "17149642101048261903",

"isCaCert": true,

"isRootCA": true,

"entityType": null,

"entityId": null,

"caCertificateId": null,



"createdTime": 1569751336660,


"updateVersion": 1,



"id": "f2010f44-5200-48ca-bbcc-0f82d19341d0"

}

Delete a Certificate

Required Permissions You must have the DELETE_CERTIFICATE permission to perform this operation.


Method DELETE


id


Sample Request

Response


VMware, Inc. 133

Update a Certificate

Required Permissions You must have the EDIT_CERTIFICATE permission to perform this operation.


Method PUT


id


Sample Request{


"certificate": "-----BEGIN CERTIFICATE-----\nMIIDEjCCAfoCCQC/

8PN1bxg4fDANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJV


\nVQQKDAhWTVctVGVzdDETMBEGA1UEAwwKVGVzdENBQ2VydDAeFw0xOTA5MjkwOTU5\nMzVa

Fw0xOTEyMjgwOTU5MzVaMDgxCzAJBgNVBAYTAlVTMRAwDgYDVQQKDAdWTVct

\nVGVzMRcwFQYDVQQDDA5kZXZpY2UxLXJhbmRvbTCCASIwDQYJKoZIhvcNAQEBBQAD

\nggEPADCCAQoCggEBAKn

+UYn9bIFH0kDZ9dzJ2EHzrqqALrbW2j5ZFNvksYWLLG71\nB5ifBeGV7m

+UAbXzpmZfNm9injGHi9Y9Y0pJfJYYxLNIUdE/U1K6NBk5HbJJUCy/

\n6KX9aB7PA7N4h2d9YrQCDLOc7rlJBEaQkaRx+Hbm1jZis2poZTENJgxmdP4eGmQS\n2xoV

++IzXdXdS2Bo//

sOWXcSvVlWFQoLHfVvHOXuQnCXNnpRKsllZ161EQxF4HC8\n78Yd51EDqVp7jTmO8m4jZHYA

avZPL

+T3Xuz2U76ykj42ykWs6PU9hRPf4ehyMgo6\nkidErMplwx1yUszO9vfYUwmHBl7LPX4pajD

It/kCAwEAATANBgkqhkiG9w0BAQsF\nAAOCAQEAuHfQqohJI9NPr/

km320g0PeVY3U9NZkbGzgt5G9sznnaLTzQCe9YxM+z

\nc5lhloTdL6Us7J7Z5VT3t3f5CRGHyuQTHYgnE/inML1OKRc/5UlKznbdPfwOLsTg

\njPZ9KoP5F260CO1SCEKY448dNtMxsOehYO6GpsgB6RgInjYrbz40fklhw/Vz5ubg

\nbebyy84c/abDcKaxDsQUSgc8boWBVnVRG9gtiL6ifP18NbWjluwTsysOn6tHs0oS

\nMIApJXaJi2+PJ7jp729cm2MFpwSKKZc272dDJEOqa7GPjXtJ/8sg+2n3YrZjGq8x

\nAviQmnfUT8kwqeGefM3xHWYnF0SWPQ==\n-----END CERTIFICATE-----\n",

"caCertificateId": "261f5328-0822-47ce-85ce-c0a797b9911b",

"state": "ACTIVE"

}

Response{

"id": "75ase0ac-65fd-4b3d-aa36-917582cfcff7"

}

Advanced Search APIsUse the following APIs to create, get, update, and delete a filtered device list.


VMware, Inc. 134

Required PermissionsYou must be a Monitoring Administrator or a Device Administrator to perform these operations.

Create a Filtered Device List

Required Permissions You must have the Create Filter Definition permission to perform this operation.

Description Create a filtered device list based on a user-defined filter definition and return the ID of the list. Use the id to make a GET call of the filtered device list to view the list of devices.

You can set baseFilterDefId, queryTypeForBaseFilterDef ,templateIds, filters, projections and so on, in a CreateFilteredDeviceListRequest.

After receiving the CreateFilteredDeviceListRequest, advanced search service first verifies if baseFilterDefId is empty. If not, advanced search service retrieves the filter definition from DB and uses the filter definition values as base request parameters.

Advanced search service uses:

n The union of templateIds in the request and templateIds from the filter definition.

n The union of filters and the union of projections.

For parameters, such as startTimeMs, endTimeMs, values from the request has priority over values from the filter definition.

API /api/filter-results/


VMware, Inc. 135

Deprecated: /api/filters

Method POST


projection n keyQualifier

string

Key qualifier to specify the location of the key when the key is in a nested document.

n dataSource

string

n DEVICEMGMT_SERVICE: Device management micro service.

n CAMPAIGN_SERVICE: Campaign management micro service.

n METRIC_SERVICE: Metric query micro service.

n key

string

startTimeMs

int64

Start time for metric filters

retentionTimeSec

string

Retention time of a filtered device list. The list is automatically deleted after the retention time unless the user reads it. This parameter is deprecated from version 0.7 onwards.


VMware, Inc. 136

Name Description

filter

string

Filters are always ANDed. A filter consists of a key and multiple operator-value pairs. Only the OR operation is allowed between the operator-value pairs.

oredOperatorValuePair

n operator

string

n EQUAL_TO

n NOT_EQUAL_TO

n GREATER_THAN

n GREATER_THAN_EQUAL_TO

n LESS_THAN

n LESS_THAN_EQUAL_TO

n CONTAINS

Enter one of the following values:

n valueInt64

int64

n valueString

string

n valueBoolean

boolean

n valueDouble

double

keyObj

n valueType

string

n INT64

n DOUBLE

n STRING

n BOOLEAN

n dataSource

string




n key

string

n keyQualifier

string



VMware, Inc. 137

Name Description

n isPeriodRequired

string

Whether or not the key requires a period. For example, metric filter keys require a period (start/end time).

n keyType

n PROJECTABLE

n FILTERABLE

n BOTH

n displayUnit

The unit of value if the key is a metric key.

n factor

The conversion factor to convert from the reported unit of metric to the display unit of metric. This parameter is deprecated from version 0.7 onwards.

n displayName

The display name of the filter.

endTimeMs

int64

End time for metric filters.

offsetMs

int64

A time amount to be subtracted from the current time, for the start time of a relative time-ranged query.

Note You must specify either the startTimeMs and endTimeMs parameters or the offsetMs parameter.

limit

int32

The maximum number of results.

isRelative

boolean

Indicate whether the time range is relative or not.

templateId

string

Device template Ids.

queryType SHOW_CURRENT, SHOW_DESCENDANTS

queryTypeForBaseFilterDe

f

SHOW_CURRENT, SHOW_ANCESTORS

Input Example{

"filter": [

{

"keyObj": {

"dataSource": "DEVICEMGMT_SERVICE",

"key": "id",


"valueType": "STRING",

"keyType": "BOTH"

},


VMware, Inc. 138

"oredOperationValuePair": [

{

"operator": "2",

"valueString": "1"

}

]

}

],

"projection": [

{


"key": "name",

"keyQualifier": "device"

}

],

"templateId": [

"2c18410f-fe2e-48e6-ae13-8b040704916e"

],

"limit": 2

}

Response{

"id": "string"

}

Get a Filtered Device List

Required Permissions You must have the View Filter Definition permission to perform this operation.

API /api/filter-results/{id}

Deprecated: /api/filters/{id}

Method GET


queryType SHOW_CURRENT, SHOW_ANCESTORS

Response{

"filteredDevice": [

{

"keyValuePair": [

{

"valueString": "string",

"key": "string",

}

],

"id": "string"

}


VMware, Inc. 139

],

"aggregationTaskStatus": "STARTED",

"pageInfo": {

"totalPages": 2,

"totalElements": 2",

"page": 1,

"pageSize": 1

}

}

Delete a Filtered Device List

Required Permissions You must have the Delete Filter Definition permission to perform this operation.

API /api/filter-results/{id}

Deprecated: /api/filters/{id}

Method DELETE


id

string

ID of the filtered device list.

Response{}

Get All Keys for Filters and Projections


API /api/filter-keys

Deprecated: /api/filters/filter-keys

Method GET




Response{

"keyObjs": [

{

"valueType": "BOOLEAN",


VMware, Inc. 140

"keyQualifier": "string",

"isPeriodRequired": false,

"dataSource": "CAMPAIGN_SERVICE",

"key": "string"

"keyType": "BOTH"

},

{

"valueType": "INT64",


"isPeriodRequired": true,

"dataSource": "METRIC_SERVICE",

"key": "string",

"keyType": "FILTERABLE",

"displayUnit" :"%",

"factor": 1

}

]

}

Save a Filter Definition

Required Permissions You must have the Edit Filter Definition permission to perform this operation.

API /api/filter-definitions

Deprecated: /api/filters/definitions

Method POST



string


n dataSource

string




n key

string

startTimeMs

int64

Start time for metric filters.

retentionTimeSec

string

Retention time of a filtered device list. The list is automatically deleted after the retention time unless the user reads it.


VMware, Inc. 141

Name Description

filter

string



n operator

string

n EQUAL_TO

n NOT_EQUAL_TO

n GREATER_THAN


n LESS_THAN


n CONTAINS


n valueInt64

int64

n valueString

string

n valueBoolean

boolean

n valueDouble

double

keyObj

n valueType

string

n INT64

n DOUBLE

n STRING

n BOOLEAN

n dataSource

string




n key

string

n keyQualifier

string



VMware, Inc. 142

Name Description

n isPeriodRequired

string

Whether or not the key requires a period. For example, metric filter keys require a period (start/end time).

n keyType

n PROJECTABLE

n FILTERABLE

n BOTH

n displayUnit


n factor

The conversion factor to convert from the reported unit of metric to the display unit of metric.

endTimeMs

int64


isRelative

boolean


templateId

string


Input Example{

name: "string",

templateId: ["string", "string"],

filter: [

keyObj: {

dataSource: "DEVICEMGMT_SERVICE",

key: "string",

keyQualifier: "string",

valueType: "STRING",

isPeriodRequired: false,

keyType: "BOTH"

},

oredOperationValuePair: [

{

operator: "EQUAL_TO",

valueString: "blue"

},

{


valueString: "red"

}

]

},

{

keyObj: {

dataSource: "CAMPAIGN_SERVICE",


VMware, Inc. 143

key: "string",

keyQualifier: "",



keyType: "BOTH"

},


{


valueString: "INITIALIZED"

}

]

},

{

keyObj: {

"dataSource": "METRIC_SERVICE",

"key": "string",

"keyType": "FILTERABLE",

"valueType": "INT64",


"isPeriodRequired": true,

"displayUnit" :"%",

"factor": 1

}

},


{

operator: "GREATER_THAN",

valueInt64: 90

}

]

}

],

projection: [

{


"key": "string",

"keyQualifier": ""

}

],

startTimeMs: 1500000001000,

endTimeMs: 1500000002000

}

Response{

"id": "string"

}


VMware, Inc. 144

Update a Filter Definition

Required Permissions You must have the Edit Filter Definition permission to perform this operation.

API /api/filter-definitions/{id}

Deprecated: /api/filters/definitions/{id}

Method PUT



string


n dataSource

string




n key

string

startTimeMs

int64

Start time for metric filters.

retentionTimeSec

string

Retention time of a filtered device list.


VMware, Inc. 145

Name Description

filter

string



n operator

string

n EQUAL_TO

n NOT_EQUAL_TO

n GREATER_THAN


n LESS_THAN


n CONTAINS


n valueInt64

int64

n valueString

string

n valueBoolean

boolean

n valueDouble

double

keyObj

n valueType

string

n INT64

n DOUBLE

n STRING

n BOOLEAN

n dataSource

string




n key

string

n keyQualifier

string



VMware, Inc. 146

Name Description

n isPeriodRequired

string

Whether or not the key requires a period-like metric key.

n keyType

n PROJECTABLE

n FILTERABLE

n BOTH

n displayUnit


n factor

The conversion factor to convert from the reported unit of metric to the display unit of metric.

endTimeMs

int64


offsetMs

int64

A time amount to be subtracted from the current time, for the start time of a relative time-ranged query.

Note You must specify either the startTimeMs and endTimeMs parameters or the offsetMs parameter.

isRelative

boolean


templateId

string


Input Example{

name: "string",

templateId: ["string", "string"],

filter: [

keyObj: {

dataSource: "DEVICEMGMT_SERVICE",

key: "string",

keyQualifier: "string",



keyType: "BOTH"

},


{


valueString: "blue"

},

{


valueString: "red"

}


VMware, Inc. 147

]

},

{

keyObj: {

dataSource: "CAMPAIGN_SERVICE",

key: "string",

keyQualifier: "",



keyType: "BOTH"

},


{


valueString: "INITIALIZED"

}

]

},

{

keyObj: {

dataSource: "METRIC_SERVICE",

key: "string",

keyQualifier: "",

valueType: "NUMBER",

isPeriodRequired: true,

keyType: "FILTERABLE"

},


{

operator: "GREATER_THAN",

valueInt64: 90

}

]

}

],

projection: [

{


"key": "string",

"keyQualifier": ""

}

],

startTimeMs: 1500000001000,

endTimeMs: 1500000002000

}

Response{

"id": "string"

}


VMware, Inc. 148

Get a Filter Definition by ID




Method GET


id

string

ID of the filter definition.



Response{

"id": "string",

"name": "string",

"templateId": ["string", "string"],

"filter": [

{

"keyObj": {


"key": "type",


"valueType": "STRING"

}

}

],

"projection": [

{


"key": "string"

},

{


"key": "string",

"keyQualifier": "string"

}

],

"startTimeMs": 1500000000000,

"endTimeMs": 1500000001000,

"tenantId": "string",

"createdTime": 1500000002000,



VMware, Inc. 149



"updateVersion": 2

}

Delete a Filter Definition by ID

Required Permissions You must have the Delete Filter Definition permission to perform this operation.



Method DELETE


id

string

ID of the filter definition.

Response{}

Get a Filter Definition List


API /api/filter-definitions

Deprecated: /api/filters/definitions

Method GET


id ID of the filter definition.

page.number

int32

Enter the number of pages to be displayed.

page.size

int32

Enter the number of items to be displayed per page. The default number is 10.


VMware, Inc. 150



Response{

"filterDefinitionObjIdName": [

{

"id": "string",

"name": "string"

}

],

"pageInfo": {

"page": 1,

"pageSize": 10


"totalPages": "1"

}

}

Advanced Search APIs Sample Use CaseIn this use case, we use the Advanced Search APIs to find devices.

Prerequisites

Create an Advanced Search filter using the VMware Pulse IoT Center console. For information about creating an Advanced Search filter, see the VMware Pulse IoT Center User Guide.

Procedure

1 Retrieve the Filter ID of the Advanced Search filter that you created. - GET /api/filter-definitions.

curl -X GET https://iotc123-pulse.xyz.com/api/filter-definitions?page.number=1&page.size=1000

{

"filterDefinitionObjIdName": [{

"id": "0cb97d04-60e3-46da-b46d-6ca7c2bfceab",

"name": "G-RPI-AJ-01"

}, {

"id": "12dde5c4-0c96-493c-906b-a59b85ec936f",

"name": "XYZ Test"

}, {

"id": "16a5dd . . . .


VMware, Inc. 151

2 Using the Filter ID, retrieve the filter query parameters - GET /api/filter-definitions/<<filterID>>.

curl -X GET https://iotc123-pulse.xyz.com/api/filter-definitions/0cb97d04-60e3-46da-

b46d-6ca7c2bfceab

{

"id": "0cb97d04-60e3-46da-b46d-6ca7c2bfceab",

"name": "G-RPI-AJ-01",

"templateId": [

"7b275cba-4403-4951-91e9-ec6fad73506d"

],

"filter": [

{

"keyObj": {


"key": "net-mac-eth0",

"keyQualifier": "systemProperties",

"valueType": "STRING",

"keyType": "BOTH"

},

"oredOperationValuePair": [

{

"operator": "EQUAL_TO",

"valueString": "b8:27:eb:c0:69:c6"

}

]

}

],

"projection": [

{


"key": "name",

"keyQualifier": "device"

},

{


"key": "net-mac-eth0",


}

],

"orgId": "d5c67393-cc8a-4c44-b320-15a4f1be46f9",

"createdTime": "1560534152934",




"updateVersion": 2

}


VMware, Inc. 152

3 Start the search process and get the Filter Results ID - POST /api/filter-results/ .

From the result body, copy the templateid field and the full body of the filter field. Use these JSON fields to construct a device search callback. Update the valueString field in the filter with the device that you are interested in. Perform a call to start the search. You can also specify a projection if you want to retrieve other fields for the device in the final result set:

Note Ensure that you make a POST call.

curl -X POST https://iotc123-pulse.xyz.com/api/filter-results/

-d '{

"templateId":[

7 b275cba-4403-4951-91e9-ec6fad73506d

],

"filter":[

{

"keyObj":{

"dataSource":"DEVICEMGMT_SERVICE",

"key":"net-mac-eth0",

"keyQualifier":"systemProperties",

"valueType":"STRING",

"keyType":"BOTH"

},

"oredOperationValuePair":[

{

"operator":"EQUAL_TO",

"valueString":"b8:27:eb:c0:69:c6"

}

]

}

]

}'

This call returns a filtered device list ID. Use this ID to retrieve the results.

4 Get the result set - GET /api/filter-results/<filterResultsID>>

Wait for a few seconds for the search to complete before retrieving the results. If you try to call too early, a warning message is displayed.

curl -X GET https://iotc123-pulse.xyz.com/api/filter-results/

761a5e65-7253-4fda-8c35-53a44a58772d

{

"aggregationTaskStatus":"FINISHED",

"filteredDevice":[

{

"id":"16292df1-b095-4de7-bd26-2f446a09996e"

},

{

"id":"13fe6eb3-135a-402d-99ac-087ac8ecaeff"

}

],


VMware, Inc. 153

"pageInfo":{

"page":1,

"pageSize":10,

"totalElements":"2",

"totalPages":"1"

}

}

Metric APIsUse the following APIs to query metrics.

Get Device Time Series Metric Data by Device ID and Metric Name

Note 1000 is the default response max points limit. However, you can use the GET /api/metrics/{device_id}/{metric_name} API to configure the limit parameter to display any number of data points.

Required Permissions You must have the View Metrics permission to perform this operation.

Description Get the device time series metric data by device ID, time range, and metric name. In response, you will get a list timestamp and value pairs for the specified time range with one of the following values:

n valueInt64

n valueString

n valueBoolean

n valueDouble

API /api/metrics/{device_id}/{metric_name}

Method GET


deviceId

string

Unique identification of the device entity in the Pulse IoT Center.

metricName

string

Metric name for the time series data for a particular metric.

startTimeMs

int64

Start time in milliseconds, in the request time range for the time series value.

endTimeMs

int64

End time in milliseconds, in the request time range for the time series value.

limit

int64(Optional) 1000 is the default response max points limit if no limit is provided.


VMware, Inc. 154

Sample Requesthttps://10.196.178.245:443/api/metrics/

55542147-68a5-47c9-9281-7f8af9e07fbc/Bus-Size(INT64)?

start_time_ms=1566382609693&&end_time_ms=1568974609693

Sample Response{

"deviceId":"55542147-68a5-47c9-9281-7f8af9e07fbc",

"metricData":{

"name":"Bus-Size(INT64)",

"tsData":[

{

"timeMs":"1568895027835",

"valueDouble":50.0

},

{

"timeMs":"1568895033835",

"valueDouble":30.0

},

{

"timeMs":"1568895039835",

"valueDouble":4.0

},

{

"timeMs":"1568895045835",

"valueDouble":11.0

},

{

"timeMs":"1568895051835",

"valueDouble":5.0

},

{

"timeMs":"1568895057835",

"valueDouble":1.0

},

{

"timeMs":"1568895063835",

"valueDouble":28.0

},

{

"timeMs":"1568895069835",

"valueDouble":12.0

},

{

"timeMs":"1568895075835",

"valueDouble":3.0

},

{

"timeMs":"1568895081835",

"valueDouble":13.0

},

{

"timeMs":"1568895087835",


VMware, Inc. 155

"valueDouble":23.0

}

]

}

Audit APIsUse the following APIs to get audit logs, get audit types, and get entity types.

Required PermissionsYou must have the View Audit Logs permission to perform these operations.

Get Audit Logs

API /api/audit-logs

Method GET


Sample Response{

"audits": [

{

"id": "5bbdecdc07c1c851a0a73491",



"auditType": "ENTITY_CREATED",

"auditInformation": "Entity created with some

information",

"createdTime": 1541843929120,

"deviceId": "5be5845cd7c65c0001e48c90"

},

{

"id": "5bbdecdc07c1c851a0a73492",



"auditType": "ENTITY_DELETED",

"createdTime": 1541867890431,

"deviceId": "5be5845cd7c65c0001e48c90"

}

],

"page": {

"number": 1,

"size": 10,


"totalPages": "1"

}

}


VMware, Inc. 156

Get Audit Types

API /api/audit/audit-types

Method GET


Sample Response{

"auditTypes": [

"ENTITY_CREATED",

"ENTITY_DELETED",

"ENTITY_UPDATED",

"ENTITY_ENROLLED",

"ENTITY_UNENROLLED",

"AGENT_CLIENT_CONNECTED",

"AGENT_CLIENT_DISCONNECTED"

]

}

Get Entity Types

API /api/entity-types

Method GET


Sample Response{

"entityTypes": [

"ALERT",

"ALERT_DEFINITION",

"CALLBACK",

"DEVICE",

"DEVICE_TEMPLATE",

"FILTER_DEFINITION",

"GREETING",

"GROUP",

"NOTIFICATION_DESTINATION",

"NOTIFICATION_DEFINITION",

"NOTIFICATION_INSTANCE",

"ROLE",

"TENANT",

"USER",

"CAMPAIGN"

]

}


VMware, Inc. 157

Export Audit Logs in CSV Format

API /api/audit-logs/export

Method GET

HeadersContent-Type: application/json

Accept: text/csv;api-version=<api-version>


startTime Start time in epoch format in milliseconds. For example: 1557930540000

endTime End time in epoch format in milliseconds.

Sample ResponsetraceId,nodeName,lastUpdatedBy,instanceName,updateVersion,entityType,ent

ityId,auditType,expireAt,deviceId,userId,orgId,createdBy,createdTime,las

tUpdatedTime,id,auditInformation

bd45a6664f5ecaf5dab3d91cc0ca2ca9,iotc-node-1,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,default,1,DEVICE,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,ENTITY_UPDATED,1561538879315,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,5a906597-4c18-4d7a-ac1d-4e13c49757c3,e3f0187b-

a435-4236-a61f-11a515ae95a3,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,1558946879315,1558946879315,4e0499a4-9486-4af5-8996-

dc5566dc8b04,System property updated.

87277e6db5952709955dc0f31d4226fb,iotc-node-1,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,default,1,DEVICE,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,ENTITY_ENROLLED,1561538876023,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,5a906597-4c18-4d7a-ac1d-4e13c49757c3,e3f0187b-

a435-4236-a61f-11a515ae95a3,5a906597-4c18-4d7a-

ac1d-4e13c49757c3,1558946876023,1558946876023,319b1dc1-6619-4ce8-967d-1d

47609c3345,Agent_x86 GATEWAY device enrolled.


VMware, Inc. 158

Agent APIs 4This chapter includes the following topics:

n Data Structures

n Functions

n Macro Definitions

n Enumeration Types

Data Structures

IotcApplicationIdIotcApplicationId represents the application identifier.

Application identifier is any string with a maximum length of IOTC_APP_ID_SIZE - 1. It is used to identify an application uniquely during an exchange of data between the client side application and the server side application. Use the reverse domain name notation, such as com.vmware.iotc.agent.

Header #include <iotcAgent.h>

Data Fields n char id [IOTC_APP_ID_SIZE]

Field Description Field Description

char

IotcApplicationId::id[IOTC_APP_ID_SIZE]

Holds the actual characters of the identifiers.

IotcAllowedMetricInfoStores the allowed metric information.

n metricName - Name of the metric.

VMware, Inc. 159

n metricType - Type of metric.


Data Fields n char metricName [IOTC_METRIC_NAME_SIZE]

n IotcMetricType metricType

IotcAllowedMetricSetSet of allowed metrics of a device.

n size - Size of the allowed metric set.

n allowedMetricInfo - Set of allowed metrics.


Data Fields n size_t size

n IotcAllowedMetricInfo*allowedMetricInfo

IotcBooleanValueIotcBooleanValue represents the boolean type metric data point.


Data Fields n time_t ts

n unsigned char value

IotcCampaignCallbacksIotcCampaignCallbacks represents a collection of campaign callback functions.


Data Fields n IotcUpdateInventoryInfoCb * inventoryInfoCb

n IotcCampaignPreDownloadCb * preDownloadCb

n IotcCampaignPreExecutionCb * preExecutionCb

n IotcCampaignExecuteCb * executeCb

n IotcCampaignPreActivationCb * preActivationCb

n IotcCampaignActivateCb * activateCb

n IotcCampaignDownloadProgressCb * downloadProgressCb


VMware, Inc. 160

n IotcCampaignStateChangeCb * stateChangeCb


IotcUpdateInventoryInfoCb*

IotcCampaignCallbacks::inventoryInfoCb

An update inventory info callback function.

IotcCampaignPreDownloadCb*

IotcCampaignCallbacks::preDownloadCb

A pre-download callback function.

IotcCampaignPreExecutionCb*

IotcCampaignCallbacks::preExecutionCb

A pre-execution callback function.

IotcCampaignExecuteCb*

IotcCampaignCallbacks::executeCb

An execute callback function.

IotcCampaignPreActivationCb*

IotcCampaignCallbacks::preActivationCb

A pre-activate callback function.

IotcCampaignActivateCb*

IotcCampaignCallbacks::activateCb

An activate callback function.

IotcCampaignDownloadProgressCb*

IotcCampaignCallbacks::downloadProgressCb

A Download progress callback function.

IotcCampaignStateChangeCb*

IotcCampaignCallbacks::stateChangeCb

A state change callback function.

IotcCampaignIdIotcCampaignId represents the campaign identifier.

Campaign identifier is any string with a maximum length of IOTC_UUID_SIZE - 1. It is provided by the VMware server as a response to an agent API or server API, or through campaign callbacks. A campaign identifier could be in the GUID format such as 123e4567-e89b-12d3-a456-426655440000, or any string such as 5b1656704cedfd000626bcaa.


Data Fields n char id [IOTC_UUID_SIZE]


char id [IOTC_UUID_SIZE] Holds the actual characters of the identifiers.

IotcCampaignScheduleTimeWindowIotcCampaignScheduleTimeWindow represents the campaign time window.


VMware, Inc. 161

Contains the begin and end date and time for scheduling in the timestamp format expressed in epoch time. For example,

beginTime - Stamp : 1534855979, endTimeStamp : 1534856979


Data Fields n time_t beginTimeStamp

n time_t endTimeStamp


time_t

IotcCampaignScheduleTimeWindow::beginTimeSt

amp

Beginning timestamp for the time window

time_t

IotcCampaignScheduleTimeWindow::endTimeStam

p

Ending timestamp for the time window.

IotcClientConfigIotcClientConfig represents client configuration SDKs.

Contains the begin and end date and time for scheduling in the timestamp format expressed in epoch time. For example,

beginTime - Stamp : 1534855979, endTimeStamp : 1534856979


Data Fields n IotcApplicationId appId

n IotcClientLogLevel logLevel

IotcCommandCommand structure to hold details about a command message received from the server.


Data Fields n char IotcCommand::name[IOTC_NAME_MAX_SIZE]

n char IotcCommand::id[IOTC_UUID_SIZE]

n IotcDeviceId IotcCommand::deviceId

n char IotcCommand::execPath[IOTC_PATH_MAX]

n size_t IotcCommand::numArgs


VMware, Inc. 162

n IotcCommandArg * args


char IotcCommand::name[IOTC_NAME_MAX_SIZE] Friendly name of the command.

char IotcCommand::id[IOTC_UUID_SIZE] Command identifier generated by the server.

IotcDeviceId IotcCommand::deviceId Device identifier for the targeted device. This is an optional field.

char IotcCommand::execPath[IOTC_PATH_MAX] Absolute path to the executable. This is an optional field.

size_t IotcCommand::numArgs Number of command arguments.

IotcCommandArg * args List of arguments for the command.

IotcCommandArgCommand argument structure.


Data Fields n IotcCommandArgValueType IotcCommandArg::type

n char IotcCommandArg::name[IOTC_NAME_MAX_SIZE]

n size_t IotcCommandArg::numValues

n union {

int64_t * intValues

double * doubleValues

char ** strValues

};


IotcCommandArgValueType

IotcCommandArg::type

The value type.

char

IotcCommandArg::name[IOTC_NAME_MAX_SIZE]

Name of the argument.

IotcDeviceId IotcCommand::deviceId Device identifier for the targeted device. This is an optional field.

size_t IotcCommandArg::numValues Number of items in the value array.

union {int64_t * intValuesdouble * doubleValueschar ** strValues};

Value array of the argument.


VMware, Inc. 163

IotcCommandResponseCommand response to hold the response received for a command.


Data Fields n char message [IOTC_PAYLOAD_MAX_SIZE]


char

IotcCommandResponse::message[IOTC_PAYLOAD_M

AX_SIZE]

The error message to be sent to the server.

IotcDevice(Deprecated) Represents a device entity.


Data Fields n IotcDeviceId deviceId

n IotcDeviceType type

IotcDeviceDetailsIotcDeviceDetails represents the device details.


Data Fields n char name [IOTC_NAME_MAX_SIZE]

n char deviceTemplate [IOTC_NAME_MAX_SIZE]


char

IotcDeviceDetails::name[IOTC_NAME_MAX_SIZE]

Name of the device.

char

IotcDeviceDetails::deviceTemplate[IOTC_NAME

_MAX_SIZE]

Name of the device template.

IotcDeviceIdIotcDeviceId represents the device identifier.




VMware, Inc. 164

IotcDeviceDataIotcDeviceData represents a device entity.



n IotcTemplateId templateId

n IotcDeviceId parentId

n IotcDeviceId parentGatewayId

n IotcDeviceType type

n IotcEnrollmentState enrollmentState

n char deviceName [IOTC_NAME_MAX_SIZE]

n char templateName [IOTC_NAME_MAX_SIZE]

n IotcKeyValueSet systemProperties

n IotcKeyValueSet customProperties

n IotcAllowedMetricSet allowedMetrics

IotcDeviceSetRepresents the set of devices.


Data Fields n IotcDevice*device

n size_t used

n size_t size

IotcDeviceDataSet

IotcDoubleValueIotcDoubleValue represents the float type metric data point.



n double value


VMware, Inc. 165

IotcEnrollmentCredentialsIotcEnrollmentCredentials represents the enrollment credentials.


Data Fields n char authToken [IOTC_PAYLOAD_MAX_SIZE]


char

IotcEnrollmentCredentials::authToken[IOTC_P

AYLOAD_MAX_SIZE]

authToken contains the credentials required by the enrollment provider.

IotcEnrollmentDataIotcEnrollmentData represents the enrollment data.

Enrollment data contains the type of enrollment and the required data for the enrollment.


Data Fields n IotcEnrollmentType type


n union {

IotcDeviceId deviceId

IotcDeviceDetails deviceDetails

};


IotcDeviceId IotcEnrollmentData::parentId parentId is the device ID of the gateway device that the device connects to. For the root gateway device, the parent ID must be empty.

IotcDeviceId IotcEnrollmentData::deviceId deviceId must be set for the IOTC_PRE_REGISTERED type.

IotcDeviceDetails

IotcEnrollmentData::deviceDetails

deviceDetails must be set for the IOTC_NOT_REGISTERED type.


VMware, Inc. 166

IotcEnrollmentRequestIotcEnrollmentRequest represents the enrollment request structure.


Data Fields n IotcEnrollmentData data

n union {

IotcEnrollmentCredentials enrollmentCredentials

IotcUserCredentials userCredentials

};


IotcEnrollmentData

IotcEnrollmentRequest::data

Data contains the required enrollment data.

IotcEnrollmentCredentials

IotcEnrollmentRequest::enrollmentCredential

s

enrollmentCredentials must be set for the IOTC_PRE_REGISTERED type.

IotcUserCredentials

IotcEnrollmentRequest::userCredentials

userCredentials must be set for the IOTC_NOT_REGISTERED type.

IotcEnrollmentResponseIotcEnrollmentResponse represents the enrollment response.




IotcGetResponseIotcGetResponse represents the GetResponse sent from the agent to the SDK.


Data Fields n uint64_t messageId

n IotcGetResponseMsgType type

n void * response


VMware, Inc. 167

IotcInt64ValueIotcInt64Value represents the integer type metric data point.



n int64_t value

IotcKeyValueIotcKeyValue represents a key value pair.


Data Fields n char key [IOTC_NAME_MAX_SIZE]

n char value [IOTC_VALUE_MAX_SIZE]

IotcKeyValueSetIotcKeyValueSet contains an array of device properties used. It represents the number of current keyValue set size and the capacity of the keyValue set.


Data Fields n IotcKeyValue*keyValue

n size_t used

n size_t size

IotcMetricIotcMetric represents the metric data point to be sent to the agent.


Data Fields n IotcMetricType type

n IotcDeviceId deviceId

n char name [IOTC_METRIC_NAME_SIZE]

n union {

struct IotcStringValue strings [0]

struct IotcIntegerValue integers [0]

struct IotcFloatValue floats [0]

struct IotcBooleanValue bools [0]

};


VMware, Inc. 168

IotcMetricResponseIotcMetricResponse represents the metric response.


Data Fields n IotcMetricResponseStatus status

n IotcMetric metric [0]


IotcMetricResponseStatus Metric status of type.

metric Metric information that is received from agent.

IotcNotificationDefinitionIdIotcNotificationDefinitionId represents the notification definition identifier.



char

IotcNotificationDefinitionId::id[IOTC_UUI

D_SIZE]

Holds the actual characters of the identifiers.

IotcNotificationResponseIotcMetricIntvlResponse represents the notification response sent from the server to the client.


Data Fields n int status

n IotcNotificationDefinitionId definitionId

n IotcNotificationId notificationId

n char payload [IOTC_PAYLOAD_MAX_SIZE]


IotcNotificationDefinitionId

IotcNotificationResponse::definitionId

Notification definition identifier.

IotcNotificationId

IotcNotificationResponse::notificationId

Notification instance identifier.


VMware, Inc. 169

Field Description

char

IotcNotificationResponse::payload[IOTC_PA

YLOAD_MAX_SIZE]

The payload byte size.

int IotcNotificationResponse::status Status flag.

IotcPackageIdIotcPackageId represents the package identifier string.

The package identifier is a string with a maximum length of IOTC_UUID_SIZE - 1. It is in the GUID format such as, 98732222-1234-12d3-a456-426655440000.




char IotcPackageId::id[IOTC_UUID_SIZE] Holds the actual characters of the identifiers.

IotcPropertySet(Deprecated) IotcPropertySet represents information about the properties that are currently set.


Data Fields n IotcProperty * property

n size_t used

n size_t size


IotcDeviceId deviceId Contains an array of devices used.

IotcProperty * property Contains an array of properties used.

size_t used Represents the number properties currently set.

size_t size Represents the capacity of the property set.


VMware, Inc. 170

IotcSendNotificationRequestIotcSendNotificationRequest represents the send notification request sent from the client to the server.


Data Fields n IotcNotificationDefinitionId definitionId

n IotcApplicationId entityId

n size_t numKeyValues

n IotcKeyValue * keyValues


IotcNotificationDefinitionId

IotcSendNotificationRequest::definitionId

Notification definition identifier.

IotcApplicationId

IotcSendNotificationRequest::entityId

Source of the request.

IotcKeyValue*

IotcSendNotificationRequest::keyValues

Array of key value pairs.

size_t

IotcSendNotificationRequest::numKeyValues

Number of key value pairs.

IotcStringValueIotcStringValue represents the string type metric data point.



n char value [IOTC_METRIC_STRING_VALUE_SIZE]

IotcTemplateIdIotcTemplateId represents the template identifier.




VMware, Inc. 171

IotcUploadFileRequestIotcUploadFileRequest represents the Upload File request sent from the agent to the server.


Data Fields n char srcFilePath [PATH_MAX]

n char dstFilePath [PATH_MAX]


char

IotcUploadFileRequest::srcFilePath[PATH_MAX

]

File path at the local system to be uploaded.

char

IotcUploadFileRequest::dstFilePath[PATH_MAX

]

Path with the destination file name appended at end of the URL to upload the file.

IotcUserCredentialsIotcUserCredentials represents basic user credentials and organization domain name.


Data Fields n char username [IOTC_NAME_MAX_SIZE]

n char password [IOTC_NAME_MAX_SIZE]

n char orgDomainName [IOTC_NAME_MAX_SIZE]

Functions


VMware, Inc. 172

Iotc_AddMetricDataAdds metric data point in the metric data set.

API int Iotc_AddMetricData ( struct IotcMetricDataSet * metricDataSet,

IotcMetric * metric )

Description Sort the list based on device IDs. This ensures that all the metrics belonging to the same device are inserted from the device list when you fetch a device node.

ParametersmetricDataSet[IN,O

UT]

Is the pointer to the metric data set.

metric Is the metric data to be sent to Agent.

Returns 0 on success. -1 on failure.

Iotc_AllocatePropertySet(Deprecated) Allocates memory for the property set to hold the size and the number of properties.

API int Iotc_AllocatePropertySet ( IotcPropertySet * properties, size_t

size )

Parametersin, out properties Pointer to the property set.

in size Capacity of the property set in terms of number of properties.

Returns 0 on success and -1 on failure.

Iotc_AllocatePropertiesAllocates memory to hold the total number of properties.

API int Iotc_AllocateProperties ( IotcKeyValueSet * properties, size_t

size )


in size Capacity of the property set in terms of number of properties.



VMware, Inc. 173

Iotc_AllocMetricDataSetAllocates memory for metric data set to hold metrics data points

API struct IotcMetricDataSet* Iotc_AllocMetricDataSet ( void )

Returns Pointer to allocated metric data set structure on success, and NULL on failure.

Iotc_CampaignScheduleActivationSchedules the campaign for activation.

API int Iotc_CampaignScheduleActivation ( IotcSession * session,

IotcCampaignId * campaignId, IotcCampaignScheduleTimeWindow *

timeWindow )

Description Sends a request to the Server to schedule the campaign for activation. If the time window is empty, it indicates that client is ready to activate the campaign. Otherwise, the supplied time window is used by the server to schedule the campaign to activate for this gateway.

Parametersin session Is the connected session returned as part of Iotc_Init call.

in campaignId Is the campaign ID of the campaign that is scheduled for activation.

in timeWindow Is the schedule time window for the campaign to activate.

Returns 0 on success.


VMware, Inc. 174

Iotc_CampaignScheduleDownloadSchedules the campaign for download.

API int Iotc_CampaignScheduleDownload ( IotcSession * session,


timeWindow )

Description Sends a request to the server to schedule the campaign for download. If the time window is empty, it indicates that the client is ready for downloading the campaign. Otherwise, the supplied time window is used by the server to schedule download of the campaign for this gateway.


in campaignId Is the campaign ID of the campaign that is scheduled for download.

in timeWindow Is the schedule time window for the campaign to download.


Iotc_CampaignScheduleExecutionSchedules the campaign for execution.

API int Iotc_CampaignScheduleExecution ( IotcSession * session,


timeWindow )

Description Sends a request to the Server to schedule the campaign for running. If the time window is empty, it indicates that client is ready to run the campaign. Otherwise, the supplied time window is used by the server to schedule the campaign to run for this gateway.


in campaignId Is the campaign ID of the campaign that is scheduled for running.

in timeWindow Is the schedule time window for the campaign to run.



VMware, Inc. 175

Iotc_CampaignSetExecutionProgressUpdates the execution progress of the campaign.

API int Iotc_CampaignSetExecutionProgress ( IotcSession * session,

IotcCampaignId * campaignId, const char * progress )

Description Sends a request to the server to update the execution progress of the campaign.


in campaignId Is the campaign identifier.

in progress Is progress string to be sent to the server.


IotcCommandCbThe command callback function type.

API typedef int IotcCommandCb(const IotcCommand *command,

IotcCommandResponse *response, void *context)

Parametersin command is the command received from the server.

out response is the response data to be sent to the server for the command.

in context is the opaque context data that is supplied by the client during command callback registration.

Returns 0 on success. -1 on error.

Iotc_CloseCloses the communication channel with the IoTC Agent.

API void Iotc_Close ( IotcSession * session )



VMware, Inc. 176

Iotc_DeletePropertySet(Deprecated) Frees the memory used by the property set.

API void Iotc_DeletePropertySet ( IotcPropertySet * properties )


Iotc_DeletePropertiesFrees the memory used by the properties.

API void Iotc_DeleteProperties ( IotcKeyValueSet * properties )


Iotc_EnrollEnrolls the gateway and generates a Gateway Identifier.

API int Iotc_Enroll ( IotcSession * iotcSession, IotcEnrollmentRequest

* enrollmentRequest )


in requestData Is the pointer to the enroll request object.

out responseData Contains the enroll response received for the request.


Iotc_EnrollConnectedDeviceEnrolls a connected device to the gateway.

API int Iotc_EnrollConnectedDevice ( IotcSession * iotcSession,

IotcEnrollmentData * enrollmentData )


in requestData Is the pointer to the enroll request object.



VMware, Inc. 177

Iotc_FreeMetricDataSetFrees the metric data points in the metric data set. Mandatory if Iotc_AllocMetricDataSet() is called.

API void Iotc_FreeMetricDataSet ( struct IotcMetricDataSet *

metricDataSet )

ParametersmetricDataSet[IN] Is the pointer to the metric data set.

Returns 0 on success. -1 on failure.

Iotc_GetCertificateIdsThis function retrieves all the certificate Ids of the associated devices.

API int Iotc_GetCertificateIds(IotcSession *iotcSession, const

IotcDeviceId *deviceId )

Description Get all the certificate Ids associated with a device.

ParametersiotcSession The current IotcSession to be used.

deviceId Pointer to the device identifier of the device.


Iotc_GetCertificateIdsByIssuerThis function retrieves all the certificate Ids associated with a devices matching the specified issuer.

API int Iotc_GetCertificateIdsByIssuer(IotcSession *iotcSession, const

IotcDeviceId *deviceId, const char *issuer )

Description Get certificate ids associated with a device whose issuer entry matches the specified issuer.



issuer NULL terminated UTF-8 string. This string is matched against all the entries in a certificate issuer(for example, Common Name, Organization Name). If one of the entries completely matches this string, the certificate Id is included in the response.



VMware, Inc. 178

Iotc_GetCertificateIdsBySubjectThis function retrieves all the certificate Ids of the associated devices matching the subject.

API int Iotc_GetCertificateIdsBySubject(IotcSession *iotcSession, const

IotcDeviceId *deviceId, const char *subject)

Description Get certificate ids associated with a device whose subject entry matches the appropriate subject.



subject NULL terminated UTF-8 string. This string is matched against all the entries in a certificate subject(for example, Common Name, Organization Name). If one of the entries fully matches this string, the certificate id is included in the response.

Returns 0 on success and -1 on failure

Iotc_GetCertificateThis function retrieves the certificate associated with a device.

API int Iotc_GetCertificate(IotcSession *iotcSession, const

IotcDeviceId *deviceId, const IotcCertificateId *certId, const char

*filePath)

Description Get private key as a PEM file. The PEM file is written to a specified file path.



certId Pointer to IotcCertificateId.

filePath The path to which the certificate is written. Must be a full path.



VMware, Inc. 179

Iotc_GetPrivateKeyThis function retrieves the private key.

API int Iotc_GetPrivateKey(IotcSession *iotcSession, const IotcDeviceId

*deviceId, const IotcCertificateId *certId, const char *filePath)

Description Get private key as a PEM file. The PEM file is written to a specified file path.



certId Pointer to IotcCertificateId

filePath The path to which the certificate is written. Must be a full path.


Iotc_GetCommandsGets commands available for this gateway device from the Server.

API int Iotc_GetData ( IotcSession * session, IotcGetDataRequest *

requestData )

Description Sends a request to the server to check if there are any commands available for this gateway. If the retrieved command data is for the agent, then the agent processes it. Any command data that is not for the agent is returned to the client as response data.




VMware, Inc. 180

Iotc_GetCustomProperties(Deprecated) Retrieves the custom properties of the gateway device.

API int Iotc_GetCustomProperties ( IotcSession * iotcSession,

IotcDeviceId * deviceId )

Parametersin iotcSession Is the connected session returned as part of Iotc_Init call.

in deviceId Is the device identifier.


Iotc_FreeGetResponseA general function to free internal resources used in a IotcGetResponse message.

API void Iotc_FreeGetResponse ( IotcGetResponse * getResponse )

ParametersgetResponse pointer of the IotcGetResponse message.

Iotc_GetResponseByTypeProcesses response messages and returns only the desired message based on the message type provided.

API int Iotc_GetResponseByType ( IotcSession * session,

IotcGetResponseMsgType requestedType, int timeout, IotcGetResponse

* getResponse )

Parametersin session The current IotcSession to be used.

in requestedType The desired type of response message to be obtained.

in timeout The duration to wait for a response from the agent, in milliseconds.

out getResponse IotcGetResponse pointer for holding the result.

Returns Returns -1 on failure. This value comes from the status of the response message or from a communication error. To handle differences between these failures, check the returned message type.


VMware, Inc. 181

Iotc_SyncThis function synchronizes device related information such as default properties with the server.

API int Iotc_Sync ( IotcSession * iotcSession )

Iotc_GetDevices(Deprecated) This function retrieves all the connected devices for a device using the ID and type.

API int Iotc_GetDevices ( IotcSession * iotcSession, IotcDeviceId *

parentId )

Description The devices would be returned with a pointer to IotcDeviceSet in the IotcGetResponse with IOTC_GET_DEVICES as the response message type.


parentId Device ID for which the connected device IDs must be retrieved.

Iotc_GetDevicesDataThis function retrieves details such as device ID, device type, device name, template ID, template name, enrollment state, parent ID, parent gateway ID, system properties, custom properties and allowed metrics of all the connected devices of a device.

API int Iotc_GetDevicesData ( IotcSession * iotcSession, IotcDeviceId *

parentId )

Description The devices are returned with a pointer to IotcDeviceDataSet in the IotcGetResponse with IOTC_GET_DEVICES_DATA as the response message type.


parentId Device ID for which the connected device IDs must be retrieved.

Iotc_GetMessageIdReturns the messageId corresponding to the latest API invoked by the client. Invoke Iotc_GetMessageId before calling the next API.

API uint64_t Iotc_GetMessageId ( IotcSession * iotcSession )



VMware, Inc. 182

Iotc_GetResponseGets response from the agent.

API int Iotc_GetResponse ( IotcSession * iotcSession, IotcGetResponse *

response )

Description Returns GetData response to the Client. If the retrieved command data is for the agent, then agent processes it. Any command data that is not for the agent is returned to the client as response data.


out responseData Contains the response data received for the request.


Iotc_GetSessionSockfdReturns sockfd to the client.

API int Iotc_GetSessionSockfd ( IotcSession * iotcSession )


Iotc_GetSystemProperties(Deprecated) Retrieves the system properties of the gateway device.

API int Iotc_GetSystemProperties ( IotcSession * iotcSession,

IotcDeviceId * deviceId )


in deviceId Is the device identifier.



VMware, Inc. 183

IotcSession* Iotc_InitInitializes the communication channel with the IoTC Agent.

API IotcSession* Iotc_Init ( IotcApplicationId * applicationId )

Parametersin applicationId Is the application identifier of the invoking client.

Returns Pointer to the session object on success or NULL on failure.

IotcSession*Iotc_InitWithConfigInitializes a communication channel with the IoTC Agent using the supplied configuration.

API IotcSession*Iotc_InitWithConfig ( IotcClientConfig * config )

Parametersin config Is a pointer to the client configuration object.

Returns Pointer to the session object on success or NULL on failure.

Iotc_InsertProperty(Deprecated) Adds a property to the property set.

API int Iotc_InsertProperty ( IotcPropertySet * properties,

IotcProperty * property )


in property Pointer to the property to be added.


Iotc_InsertPropertiesAdds a property to the property set.

API int Iotc_InsertProperties ( IotcKeyValueSet * properties,

IotcKeyValue * property )


in property Pointer to the property to be added.



VMware, Inc. 184

Iotc_RegisterCampaignCallbacksRegisters campaign callback functions.

API int Iotc_RegisterCampaignCallbacks ( IotcSession * session,

IotcCampaignCallbacks * cbs, void * userData )


in cbs Is the campaign callback functions collection that is invoked by the IoTC Agent during state change, download progress, download, and so on.

in userData Is any user context data that is returned when invoking callback functions.


Iotc_RegisterCommandCallbackThe command callback registration function.

API int Iotc_RegisterCommandCallback ( IotcSession * iotcSession,

IotcCommandCb * cb, void * context )

Parametersin IotcSession - The current IoTCSession to be used.

in cb - The command callback function.

in context - The pointer to any context data that must be supplied when cb is called.

Returns 0 on success. -1 on error.

Iotc_SendMetricRequests the agent to send a metric to the server.

API int Iotc_SendMetric ( IotcSession * iotcSession, IotcMetric *

requestData )


in requestData Is the pointer to the send metric request data.


VMware, Inc. 185

Iotc_SendMetricSetSends multiple metrics to the Agent to be sent to the server.

API int Iotc_SendMetricSet ( IotcSession * iotcSession, struct

IotcMetricDataSet * metricDataSet )

Description Use following helper functions to add metrics data:

Iotc_MetricDataSet

*Iotc_AllocMetricDataSet(void);Iotc_AddMetricData(IotcMetricDataSet

*metricDataSet, IotcMetric *metric);

Iotc_SendNotificationSends the notification request to the server.

API IotcSession * session, IotcSendNotificationRequest * requestData

Parametersin session Is the connected session returned from Iotc_Init call.

in requestData Is the pointer to the notification request object.


Iotc_SendPropertySetSends the property set to the server.

API int Iotc_SendPropertySet ( IotcSession * iotcSession,

IotcKeyValueSet * properties, IotcDeviceId * deviceId )

Parametersin iotcSession Is the connected session returned from Iotc_Init call.

in properties Pointer to the property set.

in devuceId Device identifier.



VMware, Inc. 186

Iotc_UnEnrollRequests to un-enroll a device.

API int Iotc_UnEnroll ( IotcSession * iotcSession, IotcDeviceId *

deviceId )

Description Sends a request to the Server to un-enroll the device specified by deviceId. If the deviceId is empty, then the root gateway device is un-enrolled.


in deviceId Pointer to the device identifier of the device.

Iotc_UploadFileUploads the specified file to the server.

API int Iotc_UploadFile ( IotcSession * session, IotcUploadFileRequest

* requestData )


in requestData Is the pointer to the post data request object.


Macro DefinitionsThis section lists the macros and their definitions for the Agent APIs.

Table 4-1. Macro Definitions

Macro Definition

#define IOTC_UUID_SIZE 37 The maximum size of the UUID.

#define IOTC_NAME_MAX_SIZE 256 The maximum size for a name string. Used in device names and in device property name-value pairs.

#define IOTC_VALUE_MAX_SIZE 512 The maximum size for a value string. Used in device property name-value pairs.

#define IOTC_APP_ID_SIZE 65 The maximum size of an application identifier.

#define IOTC_PAYLOAD_MAX_SIZE 4096 The maximum size for the payloads.

#define IOTC_METRIC_NAME_SIZE 64 The maximum size of the metric name.

#define IOTC_METRIC_STRING_VALUE_SIZE 32 The maximum size of the metric string data point.


VMware, Inc. 187

Enumeration TypesThis section lists the enumeration types and their definitions for the Agent APIs.

Table 4-2. Enumeration Types

Enumeration Type Definition

enum IotcValType{ BOOLEAN, FLOAT, STRING, INTEGER }

Denotes the metric unit type.

enum IotcCampaignState{ IOTC_CAMPAIGN_INITIALIZED, IOTC_CAMPAIGN_INSTANTIATED, IOTC_CAMPAIGN_INVENTORY_UP_TO_DATE, IOTC_CAMPAIGN_INVENTORY_UPDATE_FAILURE, IOTC_CAMPAIGN_WAITING_FOR_DOWNLOAD_APPROVAL, IOTC_CAMPAIGN_SCHEDULED_DOWNLOAD, IOTC_CAMPAIGN_WAITING_FOR_DOWNLOAD, IOTC_CAMPAIGN_DOWNLOADING, IOTC_CAMPAIGN_DOWNLOAD_COMPLETE, IOTC_CAMPAIGN_DOWNLOAD_FAILED, IOTC_CAMPAIGN_WAITING_FOR_EXECUTION_APPROVAL, IOTC_CAMPAIGN_SCHEDULED_EXECUTION, IOTC_CAMPAIGN_WAITING_TO_EXECUTE, IOTC_CAMPAIGN_EXECUTING, IOTC_CAMPAIGN_EXECUTION_COMPLETE, IOTC_CAMPAIGN_EXECUTION_FAILED, IOTC_CAMPAIGN_WAITING_FOR_ACTIVATION_APPROVAL, IOTC_CAMPAIGN_SCHEDULED_ACTIVATION, IOTC_CAMPAIGN_WAITING_TO_ACTIVATE, IOTC_CAMPAIGN_ACTIVATING, IOTC_CAMPAIGN_ACTIVATION_COMPLETE, IOTC_CAMPAIGN_ACTIVATION_FAILED }

Denotes the supported campaign states.

enum IotcGetResponseMsgType{IOTC_INVALID_RESPONSE, IOTC_NOTIFICATION_RESPONSE, IOTC_ENROLL_RESPONSE, IOTC_UNENROLL_RESPONSE,IOTC_CAMPAIGN_STATE_CHANGE, IOTC_SCHEDULE_RESPONSE, IOTC_SET_PROGRESS, IOTC_SEND_METRIC,IOTC_UPLOAD_FILE, IOTC_GET_COMMANDS_FINISHED, IOTC_REGISTER_CB, IOTC_SEND_PROPERTIES,IOTC_GET_SYSTEM_PROPERTIES, IOTC_GET_CUSTOM_PROPERTIES, IOTC_GET_DEVICES, IOTC_GET_DEVICES_DATA,IOTC_CLIENT_COMMAND, IOTC_ERROR_RESPONSE, IOTC_NO_RESPONSE }

Denotes the supported response message types.

enum IotcEnrollmentType{ IOTC_PRE_REGISTERED, IOTC_NOT_REGISTERED }

Denotes the supported enrollment types.

enum boolean{ FALSE, TRUE }

Denotes the boolean state.


VMware, Inc. 188

Table 4-2. Enumeration Types (continued)

Enumeration Type Definition

enum IotcMetricType{ IOTC_METRIC_ERROR, IOTC_METRIC_STRING, IOTC_METRIC_INTEGER, IOTC_METRIC_FLOAT,IOTC_METRIC_BOOLEAN, IOTC_METRIC_UNKNOWN }

Denotes the metric unit type.

enum IotcMetricResponseStatus{ IOTC_METRIC_SUCCESS, IOTC_METRIC_STORED, IOTC_METRIC_NOT_ALLOWED, IOTC_METRIC_FAILED }

Status of the metric response sent from the Agent SDK.

n IOTC_METRIC_FAILED: Metric failed to be stored at the agent or sent to the server.

n IOTC_METRIC_NOT_ALLOWED: The metric is not in the allowed list.

n IOTC_METRIC_STORED: The metric is successfully stored in the agent.

n IOTC_METRIC_SUCCESS: The metric is successfully sent to the server.

IotcClientLogLevel{IOTC_LOG_EMERG = 0, IOTC_LOG_ALERT = 1, IOTC_LOG_CRIT = 2, IOTC_LOG_ERROR = 3,IOTC_LOG_WARN = 4, IOTC_LOG_NOTICE = 5, IOTC_LOG_INFO = 6, IOTC_LOG_DEBUG = 7 }

Denotes the SDK client log levels.

enum IotcEnrollmentState Supported device states.


VMware, Inc. 189

VMware Pulse IoT Center API Reference Guide - VMware Pulse ... · This guide provides information...

Documents

Transcript of VMware Pulse IoT Center API Reference Guide - VMware Pulse ... · This guide provides information...