Escrow Devices and Transfers

Customers sometimes find themselves in a situation where a gateway device must be provisioned with our service pre-installed, for instance, to ship to one of their customer's locations, but before the details of the destination account are known. The transfer to the destination account to receive the final configuration must be accomplished without physical access to the device.

For this purpose, we've designed a workflow called "device transfer", whereby our EdgeIQ service may be installed in an "escrow" mode, for instance during imaging on the assembly line, and then later be transferred in the cloud to the destination account, at which point the device will receive its configuration and begin its normal lifecycle.

Workflow

Consider this workflow, from the point of view of a gateway manufacturer. Although this workflow isn't exclusively useful to this type of EdgeIQ customer, it is a typical use case.

1. At any point the manufacturer chooses, they can create an escrow device through the API or portal with a unique token, generated by them.
2. At some point, they also image the gateway with the operating system and other initial software, including the EdgeIQ local service. At this point, they place the same unique token as in the above step in a certain location on the device, /opt/escrow_token by default on Linux systems.
3. At whatever point the gateway device comes online, the EdgeIQ service will connect, in "escrow mode" and await configuration using its unique identifier and the escrow token.
4. Later, when the destination account for the device is determined, the manufacturer initiates a transfer to that account.
5. The destination account may then accept the transferred devices
6. Accepting the transfers will create devices on the destination account.
7. When a device is created, the EdgeIQ local service will receive its configuration and move out of escrow mode to begin its normal lifecycle.

Escrow Devices

Escrow devices are indications that a gateway device exists with the EdgeIQ local service installed, which will be transferred to another account at some point.

The API documentation for escrow devices is here.

Device Transfers

A device transfer request is a request to transfer an escrow device to a destination account. The request refers to a list of escrow devices to be transferred. When created, the transfer request will be visible to each account, even if the destination account is not a sub-account of the initiating account.

When the device transfer request is accepted by a user on the destination account, devices will be created on that account for each of the escrow devices referred to in the transfer request.

The API documentation for device transfer requests is here.

Device Type Behavior

It's important to understand how Device Types relate to device transfer requests. All devices in the system must have a device type assigned to them. When a device transfer request is created, a device type must be specified. This is so that it's clear what type of device the escrow device is. When the transfer request is accepted, the following logic is applied to the device type of the new device as it is created:

1. Override device type? If a device type is specified by a user on the destination account with the transfer acceptance, as an "override", the new devices will be created with that device type.
2. Previously copied device type? Otherwise, if no device type "override" is specified, if a device type exists on the destination account that was created by copying a device type from the originating account during a previous transfer request acceptance, the devices will be created effectively "re-using" that device type. The system keeps track of these associations in the background with data that is not available through the public API.
3. Copy device type. Otherwise, if no such device type relationship exists, a new device type will be created on the destination account by copying the device type from the originating account. The created device type will be associated with the originating device type so that the above step can be taken if further transfer requests are made with the same originating device type.