Flowmaker SDK [beta]Docs
search
GitHub

Integration Patterns and Real Worker Examples

This page documents practical integration patterns used in real workers under: /home/dja/dsd/dev/boxes-repo/flowmaker-workers/workers/

[NOTE!lightbulb/STATE OWNERSHIP] Keep $values as the persisted contract and use local $state only for UI helper state.

1) Source connection + multi-entry picker (most common)

Use DCSourceConnection to choose a source, then scope DCCatalogEntryPicker by sourceConnectionId.

Real examples

  • MQTT source: workers/mqtt-client/frontend/src/source/ConfigForm.svelte
  • OPC-UA source: workers/opc-ua-client/frontend/src/source/ConfigForm.svelte
  • Modbus source: workers/modbus-tcp/frontend/src/source/ConfigForm.svelte

Typical wiring

  • DCSourceConnection.onsourceselect => update $values.sourceConnectionId
  • DCCatalogEntryPicker.bind:selectedIds => persist IDs in $values
  • onSelectionChange/onRemove => maintain validity and emit updates

[WARNING!schedule/CONFIG INTEGRITY] Always clear selected entries when connection changes, otherwise stale IDs from another connection leak into saved config.

2) Single-entry dropdown workflows

For one catalog selection, DCCatalogEntry keeps UX simple and offers rich returned object access (sourceConnection, sourceParams, labels, metadata).

Real examples

  • PostgreSQL query config: workers/postgres-client/frontend/src/default/ConfigForm.svelte
  • MQTT sink catalog mode: workers/mqtt-client/frontend/src/sink/ConfigForm.svelte

3) Dynamic filtering + search flows

DCCatalogEntry supports imperative filtering with setFilters:

  • searchtext for name matching
  • datasetfilter for scoped datasets

Real example

  • Timeseries worker uses setFilters + CSV-assisted workflows: workers/timeseries-workers/frontend/src/source/ConfigForm.svelte

[NOTE!lightbulb/SURPRISING BEHAVIOR] Search miss can intentionally fall back to non-search results so users can still recover without clearing filters manually.

4) Mapping UIs with contextual selection

The picker can be reused as a right-pane selector while left-pane rows represent business entities (properties/fields).

Real example

  • DataCatalog mapper: workers/datacatalog-mapper/frontend/src/default/ConfigForm.svelte

Pattern:

  • Keep a selected row key in local state
  • Mirror selected row mapping into picker selectedIds
  • On picker selection, write selected ID into row mapping object

[WARNING!report/DEBUGGABILITY] If row selection and picker selection are not synchronized both ways, users will see "random" remapping behavior.

5) Validation strategy recommendations

  • Treat source connection and selected entries as separate validity keys.
  • Recompute validity when selection length or source connection changes.
  • Emit validity only when effective state changes to avoid noisy updates.

6) State persistence recommendations

  • Keep form canonical values in $values.
  • Keep UI helper state (selectedIds, local maps, search text) in local $state.
  • During initialization, normalize persisted values once (string CSV vs array, ids vs objects).

7) Defensive UX notes

  • Clear picker selection if source connection changes.
  • Show explicit empty-state message per source type.
  • In large catalogs, tell users to search first (server mode).

[WARNING!monitoring/SCALING BEHAVIOR] Large catalogs plus broad filters can degrade search responsiveness; use sourceConnectionId scoping aggressively.

Reference

  • sdk/config/flowbox-ui-components/src/
  • sdk/config/flowbox-ui/src/bridge.ts