Example of query in CURL :
curl --user 'clientId:client password' -k https://api-sandbox.everyware-cloud.com/v2/alerts.xml?severity=CRITICAL" | xmllint --format - ]]>
At present only XML is supported in the request body.]]>
To delete a given alert, the best way is to use its unique identifier "uuid".
Example of query in CURL :
curl --user 'clientId:client password' -X DELETE -k "https://api-sandbox.everyware-cloud.com/v2/alerts.xml?uuid=de9959b7-b80d-4881-bffd-0d7c93523ded"]]>
If the flag AllowedCertificatesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more pkis exist and can be read by moving the offset forward in a new request

Target ClientIDs

In a Device job target clientIDs can be specified specifically and/or specifying tagIDs that groups them. It is possible to use any combination of both declaration, and duplicates are
automatically detected and removed.

Job Type

The following operation are supported in a Device Job:

Configuration Update: updates one or more components on the target ClientIDs

Software Install: installs or updates a package on the target ClientIDs that supports DEPLOY-V1 application

Software Install V2: installs or updates a package on the target ClientIDs that supports DEPLOY-V2 application

Software Uninstall: uninstalls a package on the target ClientIDs that supports DEPLOY-V1 application

Configuration Update

This Job is used to change the configuration of one ore more components on all target ClientIDs.
The configuration file must be specified on the JobAttachment field, while anything wrote in the jobPropertiesMap field is ignored.
Please refer to JobAttachmentCreator documentation.

Software Install

This Job is used to install or update a package on all target ClientIDs that support DEPLOY-V1 application.
The package to be installed via:

File: The package will be uploaded to EDC platform and then sent to all target device. The package file must be specified on the JobAttachment field. Please refer to JobAttachmentCreator
documentation.

URL: The package will be download directly by the target device using the URL given. Properties needs to be added to jobPropertiesMap field. Available properties for this type of job via URL are listed below.

Name

Type

Mandatory

Default Value

deployUrl

String

Yes

Software Install V2

This Job is used to install or update a package on all target ClientIDs that support DEPLOY-V2 application.
Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name

Type

Mandatory

Default Value

Description

dp.uri

String

Yes

The deployment package (or .sh script) URI where to download the file.

dp.name

String

yes

The deployment package name to install. This is used on the device to search for already installed version of this package.

dp.version

String

Yes

The deployment package version to install. This is used on the device to manage the updates of the packages.

dp.download.protocol

String

No

HTTP

The protocol used to download the file from the URIAvailable protocols:

HTTP (which includes both HTTP and HTTPS)

dp.download.block.size

Integer

No

null

The size in Byte of the blocks used to download the DP via HTTP.

dp.download.block.delay

Integer

No

0

Delay in ms between block transfers.

dp.download.notify.block.size

Integer

No

null

The interval of Bytes between notification messages.

dp.download.timeout

Integer

No

60000

The timeout in ms to be used to download the DP via HTTP.

dp.download.resume

Boolean

No

true

Resume HTTP transfer if supported by the server.

dp.download.force

Boolean

No

true

Force the download of the file, even if it has been already downloaded and saved to the file system of the device.

dp.download.username

String

No

null

Username for password protected http download. No authentication will be tried if username is not present.

dp.download.password

String

No

null

Password for password protected http download. No authentication will be tried if password is not present.

dp.download.hash

String

No

null

The algorithm and value of the hash of the file used to verify the integrity of the download.The format is of this property is: {algorithm}:{hashValue}Available algorithm:

MD5

Examples:

MD5:46cbc7f212b94187cb6480fe9429a89c

dp.install

Boolean

No

true

Whether the package should be immediately installed after being downloaded.

dp.install.system.update

Boolean

No

false

Mark this install as a system install. The device needs to know if this is a system update rather than a bundle/package update.

dp.install.verifier.uri

String

No

null

The verifier script URI to run after the installation of the system update. If not given the device will consider the operation successfully completed if is able to run the system update.

dp.reboot

Boolean

No

false

Whether the system should be rebooted as part of the package installation process.

dp.reboot.delay

Integer

No

0

Delay in ms after which the device will be rebooted. Only meaningful if dp.reboot==true.

Software Uninstall

This Job is used to uninstall a package on all target Client IDs.
The package name must match the package name installed on the target client IDs that support DEPLOY-V1 application.
The package name must be declared in the JobProperties field. Anything set in JobAttachment field will be ignored.
Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name

Type

Mandatory

Default Value

packageName

String

Yes

Software Uninstall V2

This Job is used to uninstall a package on all target ClientIDs that support DEPLOY-V2 application.
Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name

Type

Mandatory

Default Value

Description

dp.name

String

Yes

The deployment package symbolic name to uninstall. This is used on the device to select which package will be uninstalled.

dp.reboot

Boolean

No

false

Whether the system should be rebooted as part of the package uninstall process.

dp.reboot.delay

Integer

No

0

Delay in ms after which the device will be rebooted. Only meaningful if dp.reboot==true.

Command

This Job is used to execute a remote command on the target device.
The command must be a recognized command by the OS installed on your device. The working directory of the execution will be /tmp/ of the device.
It is possible to attach a file to this job that will be uploaded to the target device into /tmp/ directory. The file attached must be in a valid .zip compressed format, and it will be
automatically decompressed by the device on receiving.

The command must be declared in the JobProperties field. The optional file attached must be specified on the JobAttachment field. Please refer to JobAttachmentCreator documentation.
Is not possible to concatenate more command using | (pipe) or > (close angular parenthesis).
For example the command "cat text.txt | grep test" does not work as concatenation of both commands, but all string except the first will be passed as parameters of the first string, that
represent the command, with the result of executing cat of four files.
To achieve concatenation of parameters or more complicated executions please create a script and add it as attachment of the job and then use the command to run the script.

Properties needs to be added to jobPropertiesMap field. Available properties for this type of job are listed below.

Name

Type

Mandatory

Default Value

command

String

Yes

Job Scheduling

There are two way to define the scheduling for a device job:

Simple scheduling: defined by a start date and a fixed retry interval (and optional end date).

Cron scheduling: defined by a Cron Expression and limited by a start date (and optional end date).

Simple scheduling

This scheduling needs:

Start Date: the time of the first execution of this device job. This field is mandatory.

End Date: the time after that the job must not be triggered anymore. This field is optional, and if not set the device job will stop when it reaches the max number of retries

Max Number Of Retries: the number of times that a job can be re-triggered. If end date is set and is passed the job will not be triggered. This field is mandatory

Retry Every: the interval in second between each retry. This field is mandatory. If set to 0 the job will be triggered only once and one time.

Cron scheduling

This scheduling needs:

Start Date: the time after that executions of this device job will be triggered. This field is mandatory.

End Date: the time after that the job must not be triggered anymore. This field is optional.

Max Number Of Retries: the number of times that a job can be re-triggered. If end date is set and is passed the job will not be triggered. This field is mandatory.

Cron Expression: this field represent the scheduling of this job following the Cron Expression syntax. Please refer to the Cron Expression Documentation.

]]>
If the flag DeviceMgmtPkisResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more pkis exist and can be read by moving the offset forward in a new request

Example of query in CURL (PLEASE note the --data-binary option):
curl -X PUT --data-binary \@DeviceMgmtPkiFile.xml -H "Content-type:application/xml" --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/deviceMgmtPkis]]>
curl -X PUT --data-binary \@DeviceMgmtPkiCreatorFile.xml -H "Content-type:application/xml" --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/deviceMgmtPkis]]>
If the flag DevicesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more devices exist and can be read by moving the offset forward in a new request

If topic is set, only messages belonging to this topic and sub-topics will be erased

If purge flag is set to true, time range is ignored and all messages are deleted.

The time range is from startYear+startWeek (included) to endYear+endWeek (included).
If startWeek is omitted (set to -1), all messages older than endYear+endWeek (included) will be deleted.
If startYear+startWeek is set then endYear+endWeek is mandatory.
If startYear+startWeek and endYear+endWeek are omitted (set to -1), all messages belonging to this account will be deleted.

Warning: If purge flag is true, all messages will be deleted as well as TopicsByAccount, TopicsByAssets and AssetsByAccount. Purge should not be true if a date is set.

Examples of topics:
* edcguest/Device_Id_01/car/route/two : delete all messages for this topic (only asset Device_Id_01 is concerned)
* edcguest/Device_Id_01/tram/# : delete all messages for asset Device_Id_01 under tram topic (including all subtopics)
* edcguest/+/car/route/one : delete all messages for all assets under car/route/one topic and delete topic car/route/one
* edcguest/+/car/# : delete all messages for all assets under car and all subtopics and delete topic car and all subtopics
* edcguest/Device_Id_01/# : delete all messages for asset Device_Id_01 and delete asset Device_Id_01
* edcguest/+/# : Delete all messages published on the account and reset account to the initial state without assets and topics (same function as messages/purge.xml).

Activity period: specify startDate and endDate to define the range to match

Client IDs: specify the list of ClientIDs to match

Provision Request Statuses: specify the list of statuses to match

These three ways are mutually exclusive and are listed in order of priority.
Pagination is available for each of the three filtering type.]]>
The flag rulesEmpty is set to true if no rules exist]]>
Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/allowedCertificates/{allowedCertificateId}.xml | xmllint --format -]]>
Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/blockedCertificates/{blockedCertificateId}.xml | xmllint --format -]]>
If the flag BlockedCertificatesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more pkis exist and can be read by moving the offset forward in a new request

Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/deviceCerts/{certificateId}.xml | xmllint --format -]]>
The number set must greater of the current retries.]]>
Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/deviceMgmtPkis/{deviceMgmtPkiId}]]>
The "fetch" query parameter can be used to control the amount of information to be loaded and returned for each device. Allowed values are "BASIC" or "FULL". With "BASIC", the core attributes
of the device and the version information of its profile are returned. With "FULL", all the additional device extended properties are loaded and returned.

The returned devices can be sorted. Allowed values for the sortField query parameter are: "clientId", "displayName", "lastEventOn". Sorting can be specified ascending or descending using the
"sort" query parameter with values: "asc" or "desc". If no sortField is specified, the returned devices will not follow any specific order.

If the flag DevicesResult.limitExceeded is set, the maximum number of entries to be returned has been reached. More data exist and can be read by moving the offset forward in a new request]]>

$EDC / account_name / client_id / app_id / verb / resource - id

$EDC: The $EDC prefix is used to mark all those topics that are used as "Control Topics" for the remote management. The prefix will distinguish control topics from data topics used in
unsolicited reports and it marks the associated messages as transient, not stored in the historical data archive if one is present.

account_name: an unique identifier that represents a group of devices and users and maps to the name of the current Everyware Cloud account.

client_id: an unique identifier within an account that represents a single gateway device. This client_id maps to the Client Identifier (Client ID) as defined in the MQTT specifications.
For a gateway, the MAC address of its primary network interface is generally used as the "client_id" of that gateway.

app_id: an identifier to denote an application running on the gateway device. We suggest to version the application identifier in order to allow multiple versions of the application to
coexist, e.g. CONF-V1, CONF-V2, etc.

verb: An optional token identifying the action to be performed on the resource. Suggested values are: GET to read the resource, PUT to create or update the resource, DEL to delete the
resource, EXEC to perform additional operations.

resource-id: An optional token identifying one or more resources owned by the application. Examples of resources are sensors, actuators, local files, or configuration options. Applications
manage resources by being able to list them, read the latest value or update them to a new value. Each resource is identified by a resource_id, which can be a hierarchical topic. For example,
"sensors/temp" or "sensors/hum" can act respectively as resource IDs for a temperature sensor and a humidity sensor.

To ensure the delivery of request messages, it is expected that each application that supports request/response
conversations via MQTT subscribe to the following topic on device startup:

$EDC/account_name/client_id/app_id/#

.
Everyware Cloud clients like Everyware Software Framework (ESF) and Eclipse Kura do offer this behavior by default.
The sendRequest method will proceed to the initiation of a request/response conversation by:

Generate a conversation identifier - "request.id" - for example by concatenating a random number to a timestamp

Subscribe to the topic where the response message will be published to, where requester.client.id is the Client ID of the requester:

.
Once the response for a given request is received, the requester should unsubscribe from the REPLY topic.
The returned response will be an EdcPayload structure with three additional well-known metrics:

In this specified case, the remote application will package the configurations of the services running in the target device in the body of the returned EdcResponsePayload. As all EdcMessage
bodies, the returned XML service configurations will be serialized as an base64-encoded inline String in the body element.]]>

$EDC / account_name / client_id / app_id / verb / resource - id

$EDC: The $EDC prefix is used to mark all those topics that are used as "Control Topics" for the remote management. The prefix will distinguish control topics from data topics used in
unsolicited reports and it marks the associated messages as transient, not stored in the historical data archive if one is present.

account_name: an unique identifier that represents a group of devices and users and maps to the name of the current Everyware Cloud account.

client_id: an unique identifier within an account that represents a single gateway device. This client_id maps to the Client Identifier (Client ID) as defined in the MQTT specifications.
For a gateway, the MAC address of its primary network interface is generally used as the "client_id" of that gateway.

app_id: an identifier to denote an application running on the gateway device. We suggest to version the application identifier in order to allow multiple versions of the application to
coexist, e.g. CONF-V1, CONF-V2, etc.

verb: An optional token identifying the action to be performed on the resource. Suggested values are: GET to read the resource, PUT to create or update the resource, DEL to delete the
resource, EXEC to perform additional operations.

resource-id: An optional token identifying one or more resources owned by the application. Examples of resources are sensors, actuators, local files, or configuration options. Applications
manage resources by being able to list them, read the latest value or update them to a new value. Each resource is identified by a resource_id, which can be a hierarchical topic. For example,
"sensors/temp" or "sensors/hum" can act respectively as resource IDs for a temperature sensor and a humidity sensor.

To ensure the delivery of request messages, it is expected that each application that supports request/response
conversations via MQTT subscribe to the following topic on device startup:

$EDC/account_name/client_id/app_id/#

.
Everyware Cloud clients like Everyware Software Framework (ESF) and Eclipse Kura do offer this behavior by default.
The sendRequest method will proceed to the initiation of a request/response conversation by:

Generate a conversation identifier - "request.id" - for example by concatenating a random number to a timestamp

Subscribe to the topic where the response message will be published to, where requester.client.id is the Client ID of the requester:

.
Once the response for a given request is received, the requester should unsubscribe from the REPLY topic.
The returned response will be an EdcPayload structure with three additional well-known metrics:

In this specified case, the remote application will package the configurations of the services running in the target device in the body of the returned EdcResponsePayload. As all EdcMessage
bodies, the returned XML service configurations will be serialized as an base64-encoded inline String in the body element.]]>
Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}.xml | xmllint --format -]]>
At present only XML is supported in the request body.]]>
Example of query in CURL :
curl --user 'clientId:client password' -X DELETE -k https://api-sandbox.everyware-cloud.com/v2/messages/purge.xml]]>
If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

If the parameter "sort" is set to "asc", messages are returned oldest first.]]>

If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

The messages returned are sorted. If the parameter "sortType" is set to "time", messages will be sorted by timestamp, if set to "value" or not set, messages will be sorted by metric value.
If the parameter "sort" is set to "asc", messages are returned oldest or smallest first.]]>

If the flag MessagesResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

If the parameter "sort" is set to "asc", messages are returned oldest first.]]>

Messages marshalled in XML or JSON format are supported as long as the Accept HTTP header is set accordingly.]]>
For each returned Metric its name and type will be returned. Value is not returned.
Please keep in mind that when supplying a Topic as a query parameter in a URL, proper URL encoding is necessary for characters like '+' (replace it with '%2B') and '#' (replace it with '%23').]]>
If the flag limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

If the parameter "sort" is set to "asc", metrics are returned smaller first.]]>

If the flag limitExceeded is set, the maximum number of entries to be returned has been reached, more data exist and can be read by moving the offset forward in a new request

If the parameter "sort" is set to "asc", metrics are returned oldest first.]]>

Only certain fields are editable after a provision request has been created.
The editable fields are:

activatesOn

expiresOn

status

provisionJob.retryMaxAttempts

]]>
When deleting a provisionRequest the associated provisionJob and all related attachment will also be deleted.]]>
Comet Long Polling session is initiated.
By default a server-side timeout of 1 minute is applied to the suspended response.
The client code is expected to handle the closing of the connection from the server side and
perform a reconnect if necessary. A maximum time out of 5 minutes can be specified.
Upon receiving a message on the subscribed topic, the message will be formatted in
XML or JSON format as requested and sent as response body to the suspended request.
Following the Long Polling protocol, the request will then be closed; it is left up
to the client to reopen a new request. JSON will be the default format if no extension is provided.
Cross Origin Request Support (CORS) is included so Java Scripts clients executed in
web browser can initiate subscribe REST calls from any domain.
Please refer to our code samples for client libraries that you can use to make Comet requests.]]>
Example of query in CURL :
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/deviceCerts/{certificateId}.xml | xmllint --format -]]>
Example to list all files in the current working directory:

Example of query in CURL:
curl --user 'username:password' -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/configurations.xml?componentId={componentId} | xmllint --format -]]>
Example of query in CURL. This example reads the configuration from file:
curl --user 'username:password' -X POST -H 'Content-type: application/xml' -d @configuration.xml -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/configurations]]>
Example of query in CURL.
curl --user 'username:password' -X POST -k https://api-sandbox.everyware-cloud.com/v2/devices/{clientId}/disconnect]]>
If the flag DeviceEventsResult.limitExceeded is set, the maximum number of entries to be returned has been reached, more events exist and can be read by moving the offset forward in a new
request