ProvisionRequests Resource

GET /provisionRequests

Returns the list of all the ProvisionRequest associated with the currently connected user with specified offset and limit query parameters. Is it possible to filter result for:

  • 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.

Request Parameters
name type description default constraints multivalued
clientIDs query     yes
endDate query     no
limit query 50 required no
offset query 0 required no
startDate query 0   no
statuses query   "ABANDONED" or "APPS_INSTALLED" or "APPS_INSTALLING" or "COMPLETED" or "CONF_UPDATED" or "CONF_UPDATING" or "CREATED" or "FAILED" or "RUNNING" or "SKIPPED" or "STARTED" or "STOPPED" or "STOPPING" yes
Response Body
media type data type description
application/json ProvisionRequestsResult (JSON) The list of ProvisionRequest object.
application/xml provisionRequestsResult (XML)

Example

Request
GET /provisionRequests
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "limitExceeded" : true,
  "provisionRequest" : [ {
    "id" : 12345,
    "accountId" : 12345,
    "createdOn" : 12345,
    "createdBy" : 12345,
    "modifiedOn" : 12345,
    "modifiedBy" : 12345,
    "activatesOn" : 12345,
    "expiresOn" : 12345,
    "status" : "ENABLED",
    "clientId" : "...",
    "activationKey" : "...",
    "provisionUserId" : 12345,
    "provisionJob" : {
      "status" : "COMPLETED",
      "id" : 12345,
      "accountId" : 12345,
      "jobType" : "device_certificate_revoke",
      "displayName" : "...",
      "jobProperties" : "...",
      "createdOn" : 12345,
      "createdBy" : 12345,
      "startOn" : 12345,
      "retryMaxAttempts" : 12345,
      "retryCount" : 12345,
      "optlock" : 12345
    },
    "optlock" : 12345,
    "provisionSecureURL" : true,
    "provisionedCredentialsTight" : "STRICT"
  }, {
    "id" : 12345,
    "accountId" : 12345,
    "createdOn" : 12345,
    "createdBy" : 12345,
    "modifiedOn" : 12345,
    "modifiedBy" : 12345,
    "activatesOn" : 12345,
    "expiresOn" : 12345,
    "status" : "ENABLED",
    "clientId" : "...",
    "activationKey" : "...",
    "provisionUserId" : 12345,
    "provisionJob" : {
      "status" : "APPS_INSTALLING",
      "id" : 12345,
      "accountId" : 12345,
      "jobType" : "device_provision_v3",
      "displayName" : "...",
      "jobProperties" : "...",
      "createdOn" : 12345,
      "createdBy" : 12345,
      "startOn" : 12345,
      "retryMaxAttempts" : 12345,
      "retryCount" : 12345,
      "optlock" : 12345
    },
    "optlock" : 12345,
    "provisionSecureURL" : true,
    "provisionedCredentialsTight" : "LOOSE"
  } ]
}

POST /provisionRequests

Creates a new ProvisionRequest based on the information provided in the ProvisionRequestCreator parameter.

Request Body
media type data type description
application/json ProvisionRequestCreator (JSON) Provides the information for the new ProvisionRequest to be created.
application/xml provisionRequestCreator (XML)
Response Body
media type data type description
application/json ProvisionRequest (JSON) The newly created ProvisionRequest object.
application/xml provisionRequest (XML)

Example

Request
POST /provisionRequests
Content-Type: application/json
Accept: application/json

                
{
  "accountId" : 12345,
  "activatesOn" : 12345,
  "expiresOn" : 12345,
  "clientId" : "...",
  "generateActivationKey" : true,
  "provisionUserUsername" : "...",
  "provisionUserPassword" : "...",
  "retryMaxAttempts" : 12345,
  "provisionAttachments" : [ {
    "name" : "...",
    "contentType" : "CONFIGURATION",
    "body" : "..."
  }, {
    "name" : "...",
    "contentType" : "COMMAND",
    "body" : "..."
  } ],
  "overwriteIfDuplicate" : true,
  "provisionSecureURL" : true,
  "deviceCredentialsTight" : "LOOSE"
}
Response
HTTP/1.1 201 Created
Content-Type: application/json

                
{
  "id" : 12345,
  "accountId" : 12345,
  "createdOn" : 12345,
  "createdBy" : 12345,
  "modifiedOn" : 12345,
  "modifiedBy" : 12345,
  "activatesOn" : 12345,
  "expiresOn" : 12345,
  "status" : "ENABLED",
  "clientId" : "...",
  "activationKey" : "...",
  "provisionUserId" : 12345,
  "provisionJob" : {
    "status" : "ABANDONED",
    "id" : 12345,
    "accountId" : 12345,
    "jobType" : "device_provision_v1",
    "displayName" : "...",
    "jobProperties" : "...",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "startOn" : 12345,
    "retryMaxAttempts" : 12345,
    "retryCount" : 12345,
    "optlock" : 12345
  },
  "optlock" : 12345,
  "provisionSecureURL" : true,
  "provisionedCredentialsTight" : "INHERITED"
}

GET /provisionRequests/count

Return the number of provision request used by this account. Remember that the account resources may be shared with sub-accounts of this account.

Response Body
media type data type description
application/json LongResult (JSON) the number of provision request associated with this account.
application/xml longResult (XML)

Example

Request
GET /provisionRequests/count
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "value" : 12345
}

DELETE /provisionRequests/{provisionRequestId}

Deletes the ProvisionRequest specified by the "provisionRequestId" path parameter.
When deleting a provisionRequest the associated provisionJob and all related attachment will also be deleted.

Request Parameters
name type description constraints
provisionRequestId path The id of the ProvisionRequest to be deleted. required

Example

Request
DELETE /provisionRequests/{provisionRequestId}
Content-Type: */*

                
...
Response
HTTP/1.1 204 No Content

GET /provisionRequests/{provisionRequestId}

Returns the ProvisionRequest and its associated ProvisionJob, specified by the provisionRequestId path parameter.

Request Parameters
name type description constraints
provisionRequestId path The id of the ProvisionRequest requested. required
Response Body
media type data type description
application/json ProvisionRequest (JSON) The requested ProvisionRequest object.
application/xml provisionRequest (XML)

Example

Request
GET /provisionRequests/{provisionRequestId}
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "id" : 12345,
  "accountId" : 12345,
  "createdOn" : 12345,
  "createdBy" : 12345,
  "modifiedOn" : 12345,
  "modifiedBy" : 12345,
  "activatesOn" : 12345,
  "expiresOn" : 12345,
  "status" : "ENABLED",
  "clientId" : "...",
  "activationKey" : "...",
  "provisionUserId" : 12345,
  "provisionJob" : {
    "status" : "FAILED",
    "id" : 12345,
    "accountId" : 12345,
    "jobType" : "device_software_install",
    "displayName" : "...",
    "jobProperties" : "...",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "startOn" : 12345,
    "retryMaxAttempts" : 12345,
    "retryCount" : 12345,
    "optlock" : 12345
  },
  "optlock" : 12345,
  "provisionSecureURL" : true,
  "provisionedCredentialsTight" : "LOOSE"
}

PUT /provisionRequests/{provisionRequestId}

Updates the ProvisionRequest specified by the "provisionRequestId" path parameter based on the information provided in the ProvisionRequest parameter.
Only certain fields are editable after a provision request has been created.
The editable fields are:

  • activatesOn
  • expiresOn
  • status
  • provisionJob.retryMaxAttempts

Request Parameters
name type description constraints
provisionRequestId path The id of the ProvisionRequest to be updated. required
Request Body
media type data type description
application/json ProvisionRequest (JSON) The modified ProvisionRequest whose attribute need to be updated.
application/xml provisionRequest (XML)
Response Body
media type data type description
application/json ProvisionRequest (JSON) The updated provision request.
application/xml provisionRequest (XML)

Example

Request
PUT /provisionRequests/{provisionRequestId}
Content-Type: application/json
Accept: application/json

                
{
  "id" : 12345,
  "accountId" : 12345,
  "createdOn" : 12345,
  "createdBy" : 12345,
  "modifiedOn" : 12345,
  "modifiedBy" : 12345,
  "activatesOn" : 12345,
  "expiresOn" : 12345,
  "status" : "DISABLED",
  "clientId" : "...",
  "activationKey" : "...",
  "provisionUserId" : 12345,
  "provisionJob" : {
    "status" : "CONF_UPDATED",
    "id" : 12345,
    "accountId" : 12345,
    "jobType" : "billing_report",
    "displayName" : "...",
    "jobProperties" : "...",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "startOn" : 12345,
    "retryMaxAttempts" : 12345,
    "retryCount" : 12345,
    "optlock" : 12345
  },
  "optlock" : 12345,
  "provisionSecureURL" : true,
  "provisionedCredentialsTight" : "INHERITED"
}
Response
HTTP/1.1 204 No Content
Content-Type: application/json

                
{
  "id" : 12345,
  "accountId" : 12345,
  "createdOn" : 12345,
  "createdBy" : 12345,
  "modifiedOn" : 12345,
  "modifiedBy" : 12345,
  "activatesOn" : 12345,
  "expiresOn" : 12345,
  "status" : "ENABLED",
  "clientId" : "...",
  "activationKey" : "...",
  "provisionUserId" : 12345,
  "provisionJob" : {
    "status" : "CONF_UPDATED",
    "id" : 12345,
    "accountId" : 12345,
    "jobType" : "device_command",
    "displayName" : "...",
    "jobProperties" : "...",
    "createdOn" : 12345,
    "createdBy" : 12345,
    "startOn" : 12345,
    "retryMaxAttempts" : 12345,
    "retryCount" : 12345,
    "optlock" : 12345
  },
  "optlock" : 12345,
  "provisionSecureURL" : true,
  "provisionedCredentialsTight" : "LOOSE"
}

GET /provisionRequests/{provisionRequestId}/executions

Return the list of the executions for the specified Provision Request

Request Parameters
name type description constraints
provisionRequestId path required
Response Body
media type data type description
application/json ProvisionRequestExecutionsResult (JSON)
application/xml provisionRequestExecutionsResult (XML)

Example

Request
GET /provisionRequests/{provisionRequestId}/executions
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "provisionRequestExecution" : [ {
    "status" : "STOPPED",
    "accountId" : 12345,
    "jobId" : 12345,
    "executionId" : 12345,
    "startedOn" : 12345,
    "endedOn" : 12345,
    "log" : "...",
    "optlock" : 12345
  }, {
    "status" : "CREATED",
    "accountId" : 12345,
    "jobId" : 12345,
    "executionId" : 12345,
    "startedOn" : 12345,
    "endedOn" : 12345,
    "log" : "...",
    "optlock" : 12345
  } ]
}

POST /provisionRequests/{provisionRequestId}/executions/{ProvisionJobExecutionId}/sendStopSignal

Send a stop signal to the provisioning execution. The stop signal will be captured only at next step, so is not possible to stop the device job during the current step processing.

Be careful that stopping a provision request can be harmful for the target device.

Request Parameters
name type description constraints
ProvisionJobExecutionId path required
provisionRequestId path required

Example

Request
POST /provisionRequests/{provisionRequestId}/executions/{ProvisionJobExecutionId}/sendStopSignal
Content-Type: */*

                
...
Response
HTTP/1.1 201 Created