Poppy field guide · 04
API and automation boundaries
A practical control model for moving material into and out of Poppy without pretending every interface is a stable contract.
Repeatable capture and production handoffs where a human can own exceptions and verify the result.
The workflow reports technical success while content is duplicated, misrouted, incomplete, or delivered against a changed interface.
Contract first
Define the operation before choosing the automation surface.
‘Send this to Poppy’ is not a complete operation. The system needs to know what was captured, which board is authoritative, how the user selected it, what metadata must survive, what counts as delivered, and what should happen when the destination disappears. These decisions belong in a payload and state contract before they belong in Make, Zapier, a mobile client, or custom code.
The contract should distinguish preparation from delivery. Text may need normalization, a URL may need preservation, and media may exceed a transport limit. When transformation and remote side effects are fused into one opaque step, a retry can change content or duplicate the destination item.
- Assign a stable operation ID before the first remote attempt.
- Persist the original capture separately from transformed payloads.
- Record destination identity, adapter version, attempt count, and remote result where available.
State model
Queued is not delivered, and a timeout is not proof of failure.
A credible workflow exposes state: prepared, queued, sending, delivered, failed, and needs review. A request that times out may have reached the remote system even though the client did not receive confirmation. Blind retry turns uncertainty into duplicates.
Reconciliation is the missing step in many no-code and custom workflows. Before retrying an uncertain side effect, the system should use the strongest available evidence to determine whether the operation already happened. If the upstream surface provides no safe lookup or idempotency mechanism, the user needs an explicit review path.
- Do not display success before the workflow reaches its documented success state.
- Separate retryable transport failures from validation and authorization failures.
- Put uncertain outcomes in a review queue instead of looping indefinitely.
Fragile surfaces
An interface is not an API simply because code can drive it.
A WebView or browser-driven integration may be the only available path for a useful experiment, but it inherits navigation changes, authentication state, renamed controls, rendering timing, and undocumented behavior. The failure often arrives as a missing click or wrong destination rather than a clean contract error.
Treat that adapter as replaceable and observable. Keep it isolated from durable business state, record where it fails, and preserve a manual route that lets the user finish the job. A fragile dependency can support an experiment; it should not be disguised as a maintenance-free foundation.
- Centralize selectors and interface assumptions in one adapter.
- Monitor completion evidence, not only whether the automation ran.
- Prefer a supported API as soon as it can satisfy the required operation.
Security boundary
Convenient automation still needs controlled identity.
Do not embed shared service secrets in a distributable Android application or expose them through a client-side workflow. Use a controlled backend, narrowly scoped user-owned credentials, or another identity design appropriate to the system. Minimize the content and metadata sent through every intermediary.
Connected accounts need owners, transfer paths, and revocation. When a workflow becomes operationally important, a personal login and an undocumented recovery ritual are not sufficient. The automation inventory should show who can change it, what data it can reach, and how the business continues when that identity fails.
Continue the field guide