Writing Flowchart Definitions

Overview

A flowchart definition is a JSON document stored on an entity’s FlowChartDefinition setting. It describes the workflow that entity moves through — its stages and transitions — and names the field that tells the Flowchart view where each live record currently sits. This page is for the person writing one.

The view draws two separate things layered together:

• The workflow — the boxes and arrows. This is authored, not derived: it comes entirely from the definition you write, one per entity type.
• The overlay — the records on the page the user is looking at. Each record is matched onto a stage, and the stages show live counts, names, and selectable badges.

The join between them is the matching rule, and it lives in the definition: graph.MatchField names the record field to compare ("Status" for Investigations), and each stage’s Value names which value of that field counts as “parked here”.

A record whose Status is "On Hold" parks on the stage whose Value is "On Hold" — exact string match.

A complete, working definition

This is the live Investigation lifecycle — every stage’s Value is one of the six values in the Status value list, verbatim. Use it as your template.

{
  "version": 1,
  "graph": {
    "Title": "Investigation Lifecycle",
    "Description": "Where each investigation sits in its lifecycle - matched on Status.",
    "MatchField": "Status",
    "Nodes": [
      { "ID": "pending",  "Label": "Pending",  "Kind": "start", "Value": "Pending",
        "Subtext": "Received - awaiting triage" },
      { "ID": "active",   "Label": "Active",   "Kind": "task",  "Value": "Active",
        "Subtext": "Under active investigation" },
      { "ID": "on-hold",  "Label": "On Hold",  "Kind": "task",  "Value": "On Hold",
        "Subtext": "Paused - awaiting information", "Badge": "Paused" },
      { "ID": "re-opened", "Label": "Re-opened", "Kind": "task", "Value": "Re-opened" },
      { "ID": "inconclusive", "Label": "Inconclusive", "Kind": "end", "Value": "Inconclusive" },
      { "ID": "resolved", "Label": "Resolved", "Kind": "end",   "Value": "Resolved" }
    ],
    "Edges": [
      { "From": "pending",   "To": "active",       "Label": "Triaged" },
      { "From": "active",    "To": "on-hold",      "Label": "Paused" },
      { "From": "on-hold",   "To": "active",       "Label": "Resumed" },
      { "From": "active",    "To": "resolved" },
      { "From": "active",    "To": "inconclusive" },
      { "From": "resolved",  "To": "re-opened",    "Label": "Re-opened" },
      { "From": "re-opened", "To": "active" }
    ]
  },
  "items": { "sourceId": "context" }
}

Everything not shown here is optional and falls back to a sensible default — the parser is deliberately tolerant, so a partial definition still renders. That tolerance is also what makes the format practical to have an AI draft: “draw me an onboarding workflow” produces JSON you can paste in and refine.

Stages (Nodes)

A decision stage usually has no Value — records don’t park on a question — and its outgoing edges carry the answers as labels.

Transitions (Edges)

Label text is polarity-aware: yes / approved / confirmed / match / passed render green; no / rejected / denied / failed / disputed / do not proceed render red; everything else neutral.

Two-way pairs are fine. A ⇄ B (like Active ⇄ On Hold) renders as two clean parallel lines with opposite arrows — you don’t need to do anything special.

Top-level fields

options

Author it against real data first

Don’t write JSON blind — the Flowchart view has a built-in preview loop:

1. Open the target entity’s list (e.g. Investigations) and switch the view to Flowchart.
2. Switch the header’s segment to JSON. You’ll see the current definition (or a near-empty one).
3. Paste your draft and press Apply. The workflow renders immediately against the page’s live records — stage counts light up if your MatchField and Values are right. The panel’s stats line (Data menu) shows how many records matched and how many didn’t.
4. Iterate until it looks right, then Copy. Applied JSON lives in memory only — leaving the page discards it. The copy is what you deploy.

Tip: “N unmatched” in the stats almost always means a Value doesn’t equal the stored field value exactly. Check the entity’s value list for the precise strings — "On Hold" with the space, not "OnHold".

Deploying the definition

There are two homes for the finished JSON:

Admin UI (per instance)

Admin → Entity Settings → the entity → Flow Chart Definition. Paste the JSON as one line.

Careful: the edit box is a plain text field with zero validation. A value that doesn’t parse as JSON is silently ignored by the view — validate before pasting (the JSON view’s Apply is your validator).

Customization model (shipped with the instance)

Add a row to the entity’s settings CSV in the instance’s business model, e.g. Model\EntityType\Investigation\Investigation_EntitySetting.csv:

fcDefI,Investigation,FlowChartDefinition,"{""version"":1,""graph"":{ ... }}",,UI

Standard CSV escaping: wrap the JSON in quotes and double every inner quote. Keep the JSON compact (no newlines).

Gotcha: never put comma-space (", ") inside a text value — the model pipeline eats the space, so “lifecycle, matched” arrives as “lifecycle,matched”. Use a dash instead: “lifecycle - matched”. Multi-word values like "On Hold" are fine; it’s only comma-then-space that breaks.

Making it live

1. CSV path only: run POST /api/v2/app/model/update to apply the model change.
2. Restart the backend. Definitions travel to the browser on the application metadata payload, which the server caches — a changed setting is invisible until the cache resets.
3. Hard-refresh the browser (clear cache) and open the entity’s list in the Flowchart view.

What users see

• Lists of an entity with a definition render the workflow with each record parked on its stage: a count pill per stage (a lone record is named outright), record links on the cards, and checkbox selection wired into the page’s Select All bar.
• Lists without one show a “no flow chart for this data” card with a button per flow-enabled entity — “View related Investigations” — which jumps the query to related records, straight into the Flowchart view. Writing a definition for a new entity automatically adds it as a button target everywhere.

The reader-facing tour of all of this is the Flowchart view page.

Checklist before you ship one

• JSON parses (Apply in the JSON view is the test).
• MatchField is a field that actually appears on the entity’s list — the overlay only sees list columns.
• Every Value is byte-for-byte a real stored value (check the value list; watch spaces, hyphens, casing).
• Every value of the field is claimed by some stage — unclaimed records count as “unmatched”.
• Edge From/To all point at real stage IDs; no self-loops.
• No ", " inside any text string (CSV path).
• No X/Y unless you’ve placed every stage on purpose.