Documentation

Appearance

Capture Product Application walkthrough screenshots #

This page is for documentation maintainers regenerating walkthrough images. It is not part of the customer Product Applications journey.

Use the merged Product Application implementation as the source of truth:

  • dataplicity-prelude commit 5305a129
  • dataplicity-prelude-ui commit bd272426

Do not capture an uncommitted frontend workspace or use the current production UI as a substitute for those refs. In particular, exclude unrelated privileged-broker work. Start from Developer > Applications and use the routed application workspace: Overview, Build, Behaviour, Access, and Release. Processes, Scenarios, Executions, and individual process workspaces have their own routed screens.

The proof screenshots use a dedicated local-Docker account, never production data. The capture refuses empty outcome tables, so voucher consumption, connection history, load tickets, and applied HVAC setpoints must exist before their screenshots are written:

bash
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 seeding command derives a deterministic password from the run ID without committing it. If the default UI ports (15173 and 15174) are busy, set PRODUCT_LOGIC_E2E_UI_URL and PRODUCT_LOGIC_E2E_CUSTOMER_PORTAL_PORT.

PolarVend images use a separate capture script:

bash
node scripts/capture-polarvend-walkthrough.mjs

Native portal operator screenshots use:

bash
npm run capture:portal-native-apps

Screenshot manifest #

Create or replace an image only after the named state is visible. Record the application key, sandbox or customer instance, tested version, viewport, and source commits with the capture. A single image can satisfy more than one item only when every required detail is legible.

  • [ ] Application Overview: the routed Overview page shows application identity, draft or published status, version, and authoring progress.
  • [ ] Process canvas: an individual process workspace shows the authored flow and selected node without an open menu obscuring the path.
  • [ ] Authoring diagnostics: a deliberately invalid process shows a concise diagnostic linked to the affected node. Capture a disposable draft, then correct it before release evidence.
  • [ ] Scenario run: Scenarios shows the fixture, scenario name, run status, assertions, and virtual-time result when time advancement is relevant.
  • [ ] Execution path and intervention: Executions or the process Runs tab shows the highlighted path, attempts, wait or failure context, correlation, and the intervention panel. Do not imply an intervention is available when the UI marks it unavailable.
  • [ ] Presentation: Access > Presentation shows configured customer pages and process-facing names.
  • [ ] Application Workspace outcomes: customer captures cover Overview, Records, Work, Exceptions, and Map when each page is actually configured and meaningful for that recipe. Do not add Map solely to satisfy the manifest.
  • [ ] Release warning acknowledgement: Release preflight shows a real non-blocking warning that requires acknowledgement, its unchecked state, and the acknowledged state before publish. Keep blocking validation errors as separate evidence.
  • [ ] Version rollout: Release shows the immutable published version, attached portal, and customer instance rollout or version outcome. Include enough context to distinguish the tested release candidate from another draft.

Capture checks #

Before accepting a refreshed set:

  1. Run the relevant scenario and confirm its assertions pass.
  2. Open the resulting execution and verify the path and correlation agree with the scenario.
  3. Run Release preflight, resolve blocking errors, and acknowledge required warnings deliberately.
  4. Publish the exact tested candidate and verify the attached portal receives the intended version.
  5. Open the customer Application Workspace and verify its visible outcomes match Access > Presentation.
  6. Check that no secrets, customer identifiers, private URLs, or unrelated browser content appear.

Existing PolarVend, walkthrough, and portal-native images remain useful domain evidence. They must not be captioned or described as showing Overview, the process canvas, Scenarios, Executions, Presentation, Release warning acknowledgement, or version rollout unless the pixels actually show that screen. Keep an old image when it still illustrates the stated domain outcome; capture a separate current image for new workspace evidence.