1h
1health

Workflow principles

Workflows are how apps on 1health move work between people and organizations. Four terms and eight principles cover almost every recipe.

Four terms

Workflow template
A state machine definition. It lists the steps, who may perform each step (a person or an agent), and what data each step collects. It describes the sequence of data, not the data itself.
Journey
One execution of a workflow. A journey is created from a template or a campaign, starts in progress, carries its own configuration, and holds its own data without touching primary records.
Campaign
A container that runs one workflow template many times, producing many journeys. It also sets visibility: who can see the journeys inside it. A two-way file channel between two organizations is two campaigns, one per direction.
Step
A unit of work inside a journey. Steps are assigned by role, collect form fields, and can trigger notifications and webhooks when submitted.

Eight principles

  1. Copy on instantiate

    A campaign copies the template into a private copy. Each journey copies again when it starts. Editing a template never changes a journey in flight. To pick up template changes, re-sync the campaign or start a new journey.

  2. Resolve step fields by label, not by GUID

    Field identifiers differ per copy and per environment. Read the step definition first, then submit. dynamic-step-fields.md

  3. Read the current config before you write it

    A step submit can carry configuration and will overwrite the journey's copy. Never send a hardcoded config. step-config-notifications-webhooks.md

  4. Model the steps on the real process

    A step is one thing a person does and one thing an auditor can point to. Transitions of Care has five: assign the patient, receive the discharge summary, contact the patient, reconcile medications, confirm no readmission in 30 days. Every step is a line in the audit trail, and the completed journey is the evidence for the billing code.

  5. Build each workflow from one actor's point of view

    Show a party only the steps they act on. When two parties are involved, split the work into two workflows: a parent journey launches a child journey for the second party, and the child's final step fires a webhook back to the parent. Muse Bio's results release is one such child: patient, results PDF, one yes/no step for the physician.

  6. The complexity is in configuration, not node types

    The custom form node covers most steps: a field, a file upload, a yes/no. Anything the app needs beyond the form goes in custom data on the journey or on the step, which is also how you decide who can see it. No external database.

  7. Build the template before the app

    Most apps reference a workflow template that already exists in the tenant. Creating templates and campaigns at runtime is the exception, for apps whose job is to set up new channels between organizations.

  8. Webhooks are the only bridge to automation

    The platform executes nothing after a journey launches. State is discovered by re-query; webhooks on step submit are how your app or an automation tool reacts. journey-orchestration.md

Recipes