Cloud Services
The Datalogic Connect cloud services are the part of the platform that runs outside the store: they hold the inventory of every organization, expose the REST API, carry commands down to the IoT Edge Gateway and collect the data that comes back up. The web application is one client of these services; an integration that calls the REST API is another. This page describes the main flows as they appear from the outside, without the steps to perform them: those live in the tutorials linked from each section. For the components, see Architecture.
Sign-In and Authorization
Every request to the REST API belongs to one organization, named in the request path, and carries one of two credentials: the identity of a signed-in user, or an API token. Users sign in through an external identity provider; the web application does this on the operator's behalf, as described in Sign-In and Session. A signed-in user can ask the cloud services for the profile: the organizations the user belongs to and, for each one, the role and the location it applies to.
API tokens exist for integrations that cannot sign in interactively. A user creates a token inside an organization, and the secret is shown once at creation; the integration then sends it in the API-TOKEN header of each call. A token belongs to the user who created it and to that organization.
Authorization is decided per request from three things: the organization in the path, the role of the caller, and the location the role was assigned to. A role assigned to a location applies to that location and to every location below it, so a user assigned to a region sees every store in the region and nothing outside it. The roles and what each one may do are listed under Users. A call outside the caller's organization, location or role is refused, and list calls return only the records the caller may see.
Command Lifecycle
A command is one operation on one device, such as Beep, Restart, Get Logs or Change configuration. The commands a device accepts depend on its family and on the license attached to it; the REST API lists them, with the license credit each one costs, before anything is sent. The device must be enabled and in the Provisioned status, see Device List.
The diagram shows the path of one command from the client to the device and back.
The cloud services store the command with the status CREATED and answer the client at once with the record. The command then moves without the client: the cloud services deliver it to the IoT Edge Gateway of the store, which passes it to the device over the local network, or to the POS running AladdinSDS for USB-connected scanners. The status follows the command: PENDING and IN_PROGRESS while it travels and runs, then COMPLETED or FAILED when the device answers. A device may first report that it accepted the command and is still working on it; the command stays IN_PROGRESS until the final answer arrives. A command that never receives a final answer within the time limit of the cloud services is marked FAILED.
Every status change is published to the clients listening on the notification stream (see Live Notifications), and the command record keeps the status message returned by the device. A command that produces a file, such as Get Logs, stores the file on the cloud services as a response attachment; the client asks for a short-lived download link to read it. For the screen, see Commands.
Actions and Scheduled Actions
An action is a command sent to a device group instead of a single device. When an action starts, the cloud services resolve the devices that belong to the group at that moment and create one command per device; each command then follows the Command Lifecycle on its own. The action carries progress counters (total, created, pending, in progress, completed, failed) that the cloud services update as the commands finish, and a status of its own: PENDING, IN_PROGRESS, then COMPLETED, FAILED, or PARTIAL when some devices succeeded and some did not.
A scheduled action is the definition from which actions are produced. Its schedule type decides how many.
| Schedule type | Actions produced |
|---|---|
IMMEDIATELY | One, as soon as the scheduled action is created |
ONE_TIME | One, at the start date |
DAILY | One per day at the start time, until the end date |
WEEKLY | One per week, on the chosen days, until the end date |
MONTHLY | One per month, on the chosen day, until the end date |
A scheduled action saved as a draft produces nothing until it is edited and run. A recurring one is SCHEDULED while it waits for the next occurrence, RUNNING while an occurrence executes, UNSCHEDULED when the operator disables it and COMPLETED after the last occurrence. Disabling and re-enabling are single updates on the cloud services; every occurrence stays in the run history of its scheduled action. For the concept, see Actions; for the wizard, see Actions.
The devices of an action are the members of the group when the occurrence starts. A device that joins the group later is included in the next occurrence, not in the running one.
Configuration File Distribution
Configuration and firmware files are stored on the cloud services per organization, with the device family they apply to and a description. The cloud services accept a fixed set of file types and refuse the others.
The diagram shows how a file gets from the operator's browser to a device.
- The client asks the REST API for a temporary upload address and sends the file straight to the cloud storage, so the file never passes through the web application.
- The client notifies the REST API that the upload is complete; the cloud services create the configuration record and inspect the file. The inspection reports
PROCESSING, thenCOMPLETEDorFAILED, on the notification stream. - The operator sends a Change configuration command to a device or an action to a group, choosing one of the stored files. The command references the file, not a copy of it.
- The command reaches the IoT Edge Gateway of the store as any other command.
- The device downloads the file from the IoT Edge Gateway over the local network, on the port listed under Network Requirements, and applies it.
The cloud services keep the versions of a file, and the operator can roll a file back to an earlier version. Editing changes only the record (name, family, description); deleting removes the record and the stored file. See Upload a new configuration.
Device Data Ingestion
Data flows up from the store without any request from the cloud. A device connected to the IoT Edge Gateway, directly or through AladdinSDS, reports its connection state when it goes online or offline, its properties (such as model, serial number and firmware version) and its telemetry (such as battery state). The IoT Edge Gateway forwards these reports to the cloud services, which merge them into the device record. The REST API then serves the current values, and the Device page shows them under Overview and Battery.
The diagram shows the path of one report.
The IoT Edge Gateway forwards reports only for devices the organization has approved. A device in the To be approved status is held at the gateway until an operator decides; a device in the Blocked status is ignored. Devices send their reports on their own schedule and after some commands; the values on the Device page are therefore the last received, not a live reading.
Device Approval and Enrollment
A device becomes part of an organization in one of two ways: an operator adds it by hand from the Device List, or it announces itself through an IoT Edge Gateway and waits for approval. The second path is the usual one for scanners connected to a POS running AladdinSDS and for mobile computers.
The diagram shows the self-enrollment path.
When an unknown device connects, the IoT Edge Gateway reports it to the cloud services, which create the device in the To be approved status and count it on the Device List. An Admin or Operator approves it, one at a time or in bulk, assigning a location, a device family and, optionally, a license; an unlicensed device can be approved, but it is unable to function. The cloud services then give the device its identity and the gateway lets it through: the device moves to Registered and, once it has completed provisioning, to Provisioned, from which it can exchange data and receive commands. A device the operator rejects is Blocked.
Mobile computers enroll through a Scan2Deploy profile that installs the Connect Client application and points the device to the IoT Edge Gateway of the store. When the deployment requires it, the operator first generates an Enrollment code on the IoT Edge Gateway from the web application and adds it to the profile; the device presents it to the gateway, receives a client certificate and connects over MQTT with mutual TLS instead of plain MQTT. The ports involved are listed under Network Requirements. See Enroll a Mobile Device and, for scanners on a POS, Enroll FRS/HHS device.
The IoT Edge Gateway itself is enrolled by the operator: the installation script prepared by the cloud services provisions the IoT Edge runtime, and the enrollment in the web application makes the cloud services deliver the deployment manifest that configures the gateway modules, pulled from the container registry. See Add an IoT Edge device on Ubuntu and, for the keys involved, Organizations.
The REST API also exposes approval rules, which let an organization approve devices of a given family at a given location automatically.
Live Notifications
Clients do not poll for command and action progress. A client opens one Server-Sent Events stream per organization on the REST API, and the cloud services push an event on it every time a command or an action changes status, a file inspection finishes or a user import progresses. The stream is filtered like every other call: a client receives the events of its organization and of the locations its role covers.
| Event type | Sent when |
|---|---|
COMMAND_STATUS_CHANGED | A command moves to a new status |
ACTION_STATUS_CHANGED | An action starts, finishes, or one of its commands reaches a final status |
FILE_PROCESSING_STATUS | The inspection of an uploaded file starts or ends |
USER_IMPORT_STATUS | A bulk import of users progresses |
Each event carries the record as the REST API returns it, in data, and the record as it was before the change, in previousData, so a client can render the event with the same code it uses for a read. The web application uses this stream for the COMMANDS PERFORMED box and the action counters, as described in Live Updates; an integration can use it in the same way instead of reading the command record in a loop.