Visit Flow Builder
Complete reference for designing, saving, and publishing visit schedule templates in Clinical Study Manager
URL
/visit-flow-builder— fullscreen visit flow builder
Sidebar entry: Study Workflows.
Purpose
This page is where you design the visit schedule template for your license: a graph of visits and connections that research studies can later assign. You drag visits onto the canvas, configure each visit (including attached published eCRFs), save drafts, open workflows you created, and publish a final version when the structure is ready.
Visit flows are license-scoped. You do not need an open research study to author one. Only published visit flows can be assigned to studies. Publishing is final in v1—there is no unpublish.
What you can do
- Start a new unsaved workflow (blank canvas, or New Workflow from Open)
- Resume the last workflow you edited in this browser tab
- Open a saved visit workflow you created (draft or published)
- Drag Visit nodes from the palette onto the canvas and connect them in a single path
- Configure each visit: title, icon, description, first-visit flag, and ordered eCRF slots
- Label connections (optional)
- Save a draft (first save names it; later saves and auto-save update it)
- Toggle read-only mode while editing a draft
- Auto-layout the diagram, or switch between left-to-right and top-to-bottom
- Export or import diagram JSON from the menu (power-user backup)
- Publish a saved draft when structural rules pass (published workflows are final and read-only)
- Exit back to Clinical Study Manager home
Permissions
Page access — Requires a signed-in user with Clinical Study Manager access and Configure Visit Structure. Without that permission you are redirected away from this route.
| Permission | Purpose |
|---|---|
Configure Visit Structure | Opens this page and enables save, open, new workflow, publish, and edit controls on draft workflows you own. |
There is no separate publish permission for visit flows—the same Configure Visit Structure permission covers publishing.
Without that permission, the route is blocked. If it is missing while you are already on a draft, lifecycle controls disable with Unauthorized: insufficient permissions, and edit mode locks to read-only.
Published workflows open in forced read-only mode and cannot be saved or republished. You can only open and update workflows you created; other users’ workflows do not appear in Open and behave as not found.
Workspace
Three panels plus an app bar. Details for save, open, publish, and read-only live in the sections after this map.
| Area | Role |
|---|---|
| App bar | Exit, save, open, title, edit mode, layout, menu, help, publish |
| Palette | Visit types you can drag onto the canvas |
| Canvas | Arrange and connect visits |
| Properties | Edit the selected visit or connection |
App bar
Left to right:
| Control | What it does |
|---|---|
| Exit | Returns to Clinical Study Manager home (/). |
| Save | Saves the draft — see Save. |
| Open | Opens or starts a workflow — see Open and New Workflow. |
| Title (center) | Untitled Flow before first save; then the saved name (not edited here). |
| Read-only toggle | Checked = read-only. Free on drafts with permission; forced when published or unauthorized — see Read-only mode. |
| Auto layout | Repositions visits for the current flow direction. |
| Switch layout | Toggles left-to-right ↔ top-to-bottom, then re-runs layout. |
| Menu (⋯) | Export / Import diagram JSON — see Export and Import. |
| Help | Contact Support and Take Tour. |
| Publish | Publishes a ready draft (label becomes Published) — see Publish readiness. |
Layout controls are disabled when the canvas is empty, read-only, or a layout is already running. Failure snackbar: Auto layout could not be applied. Default direction is left-to-right.
Palette
Left panel: Workflow Palette. Dragging is disabled in read-only mode.
| Item | Description | Available? |
|---|---|---|
| Visit | Collect forms during a visit | Yes — drag onto the canvas |
| Action | Perform actions based on triggers | Coming soon |
| Conditional | Branch the workflow | Coming soon |
| Decision | Route the workflow | Coming soon |
| Notification | Send alerts or notifications | Coming soon |
Only Visit creates nodes. Default new visit: title Visit, description Collect forms during a visit, icon calendar-check, First visit off, no forms.
Canvas
- Add — drag Visit from the palette
- Connect — drag from a visit’s outgoing handle to another’s incoming handle
- Select — click a visit or edge to open Properties
- Move — drag visits (disabled in read-only)
- Delete — Backspace/Delete, or Delete node / Delete edge in Properties (confirm: Delete Selection?)
Connection rules (while drawing and on publish):
- At most one incoming and one outgoing connection per visit
- The graph must be a single path (no branches, cycles, or disconnected visits)
- First visit hides the incoming handle and removes any incoming edge
Properties
Right panel: Properties. Empty state: No selection — select a node or edge on the canvas.
Visit — General Settings
| Field | Meaning |
|---|---|
| Title | Display name. Required to publish. Placeholder: Node Title... |
| Icon | Visit card icon (default calendar-check). |
| Description | Supporting text on the card. |
| First visit | Mark exactly one visit as the path start. |
Visit — Form Settings — attach published eCRFs; see Attaching eCRFs. Footer: Delete node.
Edge
| Field | Meaning |
|---|---|
| Label | Optional connection text. Disabled in read-only. |
Footer: Delete edge. No conditions or delays on edges in v1.
Welcome dialog
Shown when the license has zero published eCRFs (blocking; Escape / outside click do not dismiss).
- Explains that visit flows assign published forms to visits
- Go to Visit Form Builder →
/visit-form-builder
If any published form exists, the dialog does not appear. Publish an eCRF first — Create an eCRF form.
Attaching eCRFs
Only published eCRFs for the current license appear in the form select.
Per visit:
- Use Add form (in Properties Form Settings, or on the visit card under Forms)
- Each slot is labeled Form #1, Form #2, …
- Choose a published form for every slot
- Reorder with the drag handle when there are two or more slots
- Remove a slot with the trash control
Rules:
- Publish requires at least one form slot on every visit, and every slot must have a form selected
- On a single visit, each published form may be used at most once (you cannot add more slots than unused published forms remain for that visit)
- The same published form may be used on different visits
- While forms are still loading, Add form is disabled; removing slots stays available
Assigned forms on the canvas card show the published form title (or Form #N if empty).
When the same field Key appears on more than one attached form in the flow, those definitions must agree (type, required, validation, options). Conflicts fail study activation later—design Keys carefully when reusing forms across visits.
Save
| Situation | Behavior |
|---|---|
| Empty canvas | Save disabled / blocked — need at least one visit |
| First save | Save workflow dialog: enter a unique Name for this license |
| Later saves | Updates the same draft immediately (no rename dialog) |
| Auto-save | After first save only: silent updates ~10s after changes; also attempts save on browser unload when allowed |
| Published | Save disabled — Published workflows cannot be edited. |
| No permission | Unauthorized: insufficient permissions |
Save workflow dialog:
- Description: names must be unique for this license
- Errors include: A workflow with this name already exists., Cannot save a workflow with no nodes., Workflow title is required.
- Uniqueness is case-sensitive after trimming whitespace
Success messages: Workflow saved successfully (first create) or Saving diagram successfully (update).
Open and New Workflow
Open dialog columns: Name, Created, Updated, Status (Draft / Published). A Current badge marks the workflow already loaded.
| Action | Result |
|---|---|
| Open Workflow | Loads the selected workflow you created |
| New Workflow | Clears the session and canvas → blank Untitled Flow |
| Empty list | No saved workflows found. |
If the canvas already has at least one node, replacing it asks Replace current diagram? with Continue / Cancel.
Session resume: the same browser tab restores the last workflow id for this license from session storage. A new browser tab starts as blank Untitled Flow. Failed resume: Could not restore your last workflow. Starting a new diagram.
You only see workflows you created. Opening another user’s id fails with Workflow not found.
Export and Import
From the app bar Menu (⋯):
| Action | Notes |
|---|---|
| Export | Always available. Copies diagram JSON (Content copied to clipboard). |
| Import | Replaces the diagram from JSON. Disabled in read-only (including published). |
Power-user backup only — not a substitute for Save / Open.
Read-only mode
| Cause | Effect |
|---|---|
| You toggle the pencil switch on a draft | Editing, drag-from-palette, delete, and import are blocked until you turn it off |
| Workflow is published | Forced read-only; tooltip Published workflows cannot be edited. |
Missing Configure Visit Structure | Forced read-only; tooltip Unauthorized: insufficient permissions |
Publish readiness
Hover Publish when disabled to see blocking reasons. Client and server share these structural checks:
| Check | Message |
|---|---|
| No visits | Add at least one visit node. |
| Empty visit title | Name every visit node. |
| Visit with zero form slots | Add at least one form to every visit node. |
| Slot without a selected form | Select a form for every visit form slot. |
| Not exactly one First visit | Mark exactly one visit as the first visit. |
| Node with more than one in or out | Each node can have at most one incoming and one outgoing connection. |
| Cycle, branch, or disconnected graph | Connect all nodes in a single path with no branches or cycles. |
Also required before Publish enables:
- Workflow already saved — Save the workflow before publishing.
Configure Visit Structure— Unauthorized: insufficient permissions- Not already published — This workflow is already published.
Publish workflow confirmation
- Warns that publishing is final and the workflow cannot be changed afterward
- Type the workflow title exactly, then confirm Publish
- Success: Workflow published. It can no longer be changed.
Extra server checks
If structure passes but publish still fails, snackbars may report missing/unpublished forms, invalid form definitions, or conflicting field Keys across attached forms.
Lifecycle summary
- Untitled Flow — unsaved blank or in-progress canvas; no auto-save until first save
- Draft — editable (with permission); manual + auto-save; appears in Open for you only
- Published — immutable; forced read-only; assignable to research studies on the Visit Workflow step
- Same-tab resume — restores your last workflow for this license; use New Workflow for a blank canvas in that tab
Expert tips
- Linear schedules only — branching palette types are visible but not usable; publish requires a single path.
- Mark exactly one first visit (usually the start of the path).
- Publish eCRFs before you need them here; the Welcome dialog blocks an empty published-forms library.
- Plan names and structure before publish—there is no unpublish in v1.
- Reusing the same form Key across visits is powerful for EDC continuity, but definitions must stay compatible.
- Auto-save only runs after the first named save—don’t close an unsaved tab expecting persistence.
- Collaboration model is “publish, then assign to a study,” not shared live editing of the same draft.
Related guides
- Create a visit flow — step-by-step design, save, and publish
- Create an eCRF form — publish eCRFs before attaching them to visits
- Visit Form Builder — eCRF authoring reference
- Create a research study — assign a published visit flow to a study