Product Applications

A Device Class defines one hardware product: what its devices publish, what they can do, and how they appear to a customer. A Product Application adds the customer-specific data and business workflow around that hardware.

Use a Product Application when the product needs more than a device page. Good examples include:

• a paid Wi-Fi session that reserves value in the Product Logic resource ledger, activates a gateway, waits, and revokes access
• a fuel authorisation that reserves credit, commands a pump, settles the amount dispensed, and reconciles after lost connectivity
• HVAC schedules edited by a customer and distributed to controllers for offline use
• silo records with customer thresholds and alerts derived from device streams
• one application that uses the same camera class in two different roles

Product Applications are beta-gated and require Standard+. Confirm the product_applications capability before designing a customer commitment.

Read implementation status consistently

The worked guides use the same four labels:

Label	Meaning
Platform-provided and proven	Implemented in Prelude and exercised by an automated test through the production code path named in the guide
Worked reference / test-mode	Supplied example code or configuration that is useful for evaluation, but still needs production credentials, qualification, and operating controls
Simulated in the proof harness	Test software stands in for equipment or an external system while using the real Prelude boundary
Customer-supplied	Deliberately outside Prelude: the OEM or customer implements, qualifies, and operates it in production

“Proven” applies only to the boundary the test crosses. For example, the Product Logic end-to-end harness sends real commands through the backend and Prelude Agent Product Runtime, but its OEM Unix-socket handler simulates the pump or Wi-Fi gateway. That proves command transport and process response; it does not prove that a network rule changed or fuel moved.

Understand the layers

Layer	Owns
Device Class	Hardware compatibility, streams, actions, settings, level inputs, software, and device-page layout
Binding	The role a Device Class plays in one application, such as gateway, pump, or entry_camera
Application draft	Models, fields, rules, operations, commands, processes, pages, integrations, and offline datasets
Product version	An immutable snapshot published from the draft
Product instance	One version running for one downstream customer

A binding does not copy, rename, or reclassify devices. It gives a class a stable role inside the application. One Camera Device Class can be bound twice as entry_camera and lobby_camera; one fuel application can bind separate classes as pump and gateway.

Define the hardware contract first. Product Applications refer to Device Classes by role instead of duplicating their device contract.

Author one application

Open Developer > Product Applications, create the draft, then work through these tabs in order.

Overview

Use Overview to understand readiness, load a starter where one matches the product, and move between the application layers. A starter is an editable draft, not a production-certified integration.

Overview reports the application journey and published state using live data from the seeded local backend.

Build

1. In Hardware, connect each Device Class and give it a stable role alias.
2. In Models, define customer configuration and operational records.
3. Add typed fields, including references to native devices where a record belongs to a physical unit.
4. Make customer create, read, update, and delete permissions explicit.

Use a configuration model for long-lived customer choices such as credentials or schedules. Use an operational model for sessions and transactions. A stream-derived field can present the latest value from a class channel without copying each sample into a customer record.

A published application becomes a separate Product Instance for each downstream customer rather than one shared data set.

The Customer Portal remains the tenant boundary. Product Application records and operations add to this customer-safe workspace; they do not expose the OEM console.

Behaviour

Behaviour connects a trigger to work:

• Rules react immediately to stream, record, or custom events. They do not wait.
• Operations are deliberately invoked by a portal user, API client, rule, or process. They do not wait.
• Processes are durable multi-step executions. They can wait for time, a command result, or another event.
• Commands give a product-level name to work requested from a device role.

Processes can create or update records, reserve and settle resources, invoke commands, branch, wait, compensate, emit events, raise alerts, and call integrations. Use a process whenever correctness depends on what happens after the first request.

Command delivery uses Prelude Agent Product Runtime. After a device is authenticated, the agent discovers its product instances, polls pending commands, hands them to the OEM Unix-socket handler, then acknowledges and reports results. Leave PRODUCT_LOGIC_STUB_COMMAND_DELIVERY unset or false in Docker and staging; do not complete commands from the OEM console.

Access

Use Access to:

• generate customer list and detail pages for published models
• expose deliberate operations to the Customer Portal or Product API
• bind HTTPS webhook integrations
• define application roles and permissions

Keep the OEM support surface separate. Customer pages should expose business records and safe operations, not Remote Shell, fleet-wide logs, release controls, or engineering diagnostics.

Release

1. Run Validate and resolve every error.
2. Publish an immutable version.
3. Attach the version to the intended Customer Portal.
4. Provision or select the customer instance.
5. Use Sandbox to seed a record, invoke an operation, simulate a reading, tick process timers, or preview an offline dataset.
6. Move existing instances only after a compatibility check.

Publishing does not silently upgrade running customer instances. Each instance stays pinned to its assigned version until an explicit rollout changes it.

Choose a complete proof

Product workflow	What it proves	Guide
Silo monitoring	Stream-derived fields, customer configuration, and threshold alerts	Build a customer-operated level monitor
Camera access	One class in two roles and ordered command waits	Camera and CCTV
Paid Wi-Fi	Internal resource reservation, real command transport to a simulated gateway handler, timed access workflow, revocation, and compensation	Build a paid Wi-Fi application
Fuel management	Internal credit reservation, real command and event transport to a simulated pump handler, walk-away release, partial settlement, and reconciliation	Build a fuel management application
HVAC schedules	Customer configuration projected into an offline dataset	Build an HVAC scheduling application

The camera and level guides begin with the physical product and Device Class. The Wi-Fi, fuel, and HVAC guides begin with the Product Application because their proof is the customer workflow around the hardware.

Verify the customer boundary

For every application:

1. provision an instance for Customer A
2. create representative records and run the happy path
3. exercise timeout, rejection, duplicate, and reconnection paths that apply
4. sign in as customer viewer, operator, and administrator
5. confirm Customer B cannot read Customer A's instance, records, executions, commands, datasets, or activity
6. confirm OEM-only diagnostics remain outside the customer application

What ships with the platform

• Product Applications remain beta-gated on Standard+.
• Prelude Agent Product Runtime polls /api/product-runtime/ for instance discovery, commands, offline datasets, and authority grants. Enable it by installing the current Prelude Agent; after device authentication it starts unless product_runtime.enabled is explicitly false.
• Local Docker sets PRODUCT_LOGIC_STUB_COMMAND_DELIVERY=false. Staging and production use the same poll/ack/result path.
• Offline dataset keys are advertised on instance discovery. The agent stages, verifies, activates, and reports applied generations. Last-known-good is retained on hash or activate failure.
• Resource reservations are workflow primitives. They are not a payment processor, merchant account, tariff engine, or financial ledger of record.
• HTTPS integrations are synchronous and are not retried automatically.
• The customer still owns physical safety, device-side validation, secure storage, network enforcement, and reconciliation with the system of record.

Follow the worked examples on a device running the current Prelude Agent. Do not use sandbox “complete command” shortcuts; those are not part of the customer or OEM workflow.

Reproduce the walkthrough screenshots locally

Use the dedicated local-Docker account and never substitute production data:

cd /path/to/dataplicity-prelude
export PRODUCT_LOGIC_E2E_RUN_ID=docs-walkthrough
./scripts/product_logic_e2e/up.sh
./scripts/product_logic_e2e/seed.sh --reset
./scripts/product_logic_e2e/wait.sh
./scripts/product_logic_e2e/test.sh

cd /path/to/dataplicity-documentation
PRODUCT_LOGIC_E2E_RUN_ID=docs-walkthrough npm run capture:product-application-proofs
npm run build

The deterministic password is derived from the run ID inside the seeding command and is never committed. Override the documented UI ports with PRODUCT_LOGIC_E2E_UI_URL and PRODUCT_LOGIC_E2E_CUSTOMER_PORTAL_PORT when the defaults (15173 and 15174) are unavailable.

Related

• Device Classes
• Streams, actions, and settings
• Customer Portal
• Production limits and service behaviour
• Device data and control contract