Apiguide
Cloud Trigger
Triggering an enVision Device Remotely
Triggers the specified enVision device to perform a measure operation by routing the request through enVision Cloud. The enVision device must be registered to enVision Cloud and compatible with remote triggering capability in order for this method to be supported.
This document describes the specifications of the API endpoint.
For testing Cloud Trigger integrations without having access to a physical device, refer to the Testing Cloud Trigger Guide
Cloud Trigger Specifications
Instructs the specified device to perform a measure operation and return the result.
/api/remotetrigger/measure
Request
curl "https://api.ece.phdsolutions.ca/api/remotetrigger/measure?deviceReference=ABCD2345&transactionReference=ORD1234" \
-X GET \
-H "Authorization: Bearer YOUR_AUTH_TOKEN"
You must include a valid Bearer token in the Authorization header of any request to enVision Cloud APIs. Tokens can be managed in the enVision Cloud Portal
Example Response
{
"transactionReference": "ORD1234",
"transactionId": "905865",
"elapsedMs": 164,
"dateTimeLocal": "2024-07-26T16:12:59.697Z",
"dateTimeUtc": "2024-07-26T16:12:59.697Z",
"errorCode": 0,
"errorMessage": "",
"objectCount": 1,
"dimsUnitOfMeasure": "in",
"weightUnitOfMeasure": "lb",
"measurementFidelity": "0.2",
"legalForTrade": false,
"weight": 12.4,
"objectId": "123456ABCD",
"measuredObjects": [
{
"trackId": 1,
"errorCode": 0,
"errorMessage": "",
"rotationAngle": 15.4,
"length": 14,
"width": 9,
"height": 18.2
}
]
}
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| deviceReference | Yes | the 8-digit Device Registration Code of the target device. Example: ABCD2345 |
| transactionReference | Yes | a host-supplied transaction reference for tracking purposes. This can be any value you wish to supply as something that will be tracked with the measure operation in enVision Cloud and returned in the response. Possible values are an Order ID, Tracking Number or Barcoded identifier. |
Optional Request Parameters
| Parameter | Description |
|---|---|
| cRef1 | optional Custom Reference 1. Whatever is passed here will be attached to the transaction as the CustomReference1 field value |
| cRef2 | optional Custom Reference 2. Whatever is passed here will be attached to the transaction as the CustomReference2 field value |
| cRef3 | optional Custom Reference 3. Whatever is passed here will be attached to the transaction as the CustomReference3 field value |
HTTP Response Status Codes
| Status Code | Description |
|---|---|
| 200 - OK | The request was successfully routed to the target device and a response was provided in the body of the HTTP response. |
| 400 - Bad Request | The device reference Id provided was not valid. |
| 401 - Unauthorized | The bearer token provided was not valid. |
| 504 - Timeout | The remote device did not respond in a timely manner. |
Response Properties
A single MeasureResult object
MeasureResult Properties
| Property | Data Type | Description |
|---|---|---|
| transactionReference | string | externally provided reference # for the transaction |
| transactionId | int | enVision System-assigned unique identifier for the transaction |
| elapsedMs | int | Count of elapsed milliseconds taken to complete the measurement result on the device. |
| dateTimeLocal | datetime | Device-local datetime of transaction |
| dateTimeUtc | datetime | UTC datetime of transaction |
| errorCode | int | Error code result. 0 indicates Success |
| errorMessage | string | error message associated with the Error Code. |
| objectCount | int | Count of objects measured. This will either be 1 or zero. |
| dimsUnitOfMeasure | string | Object dimensions unit of measure (e.g. in, cm or mm) |
| weightUnitOfMeasure | string | The Weight Unit of Measure (e.g. lb or kg) |
| measurementFidelity | string | The fidelity of the dimensions measurements. This may be whole units, half units or 1/5 units. 1.0 = whole, 0.5 = half, 0.2 = 1/5 units |
| legalForTrade | boolean | True if the device was operating in Legal for Trade mode when the measurements were captured. |
| weight | float | Total weight in WeightUnitOfMeasure units |
| objectId | string | an object Id (such as a barcode etc.) |
| measuredObjects | MeasureObjectResult[] | an array of MeasureObjectResult objects. The count of elements in the array is equal to the objectCount value |
MeasureObjectResult Properties
| Property | Data Type | Description |
|---|---|---|
| trackId | int | System-assigned trackId for the object. |
| errorCode | int | Object-level error code result. 0 indicates Success |
| errorMessage | string | error message associated with the Error Code. |
| rotationAngle | float | object angle of rotation |
| length | float | object length in unitOfMeasure units |
| width | float | object width in unitOfMeasure units |
| height | float | object height in unitOfMeasure units |