Protocol Builder Orientation

A protocol is the template for one exam type (e.g. Thyroid Ultrasound). Four levels:

Each finding has two report-text slots: Report text when a value is present (the default) and Report text when normal (used when the value is normal). Both accept placeholders. Whether a value counts as abnormal is decided separately (Normal Options, Normal Range, or Advanced Rules). Numeric findings use one measurement sentence; the range controls highlighting.

Below the structures sit Reference Images (diagrams shown during the exam) and Guideline References (text appended to the draft when a trigger finding is abnormal).

Open Protocols in the top bar and click a protocol. The settings row at the top controls the whole protocol. Each dropdown describes its selected option right below it.

Click Save Settings after any change. The Active / Inactive toggle decides whether sonographers can pick the protocol. The same toggle appears in the Status column of the Protocols page.

Add Structure / Organ creates a section. + Add Finding inside it creates a finding; pick a field type. Drag the handle on the left to reorder. Builder order is form and draft order.

Click Edit on a finding to open the finding editor. There you:

• Write the Report text when normal and Report text when a value is present sentences.
• Set a normal range for numeric findings.
• Add sub-fields for detail shown only when abnormal.
• Add Advanced Rules for wording that changes by value.
• Make the finding conditional on another finding's value.

Pick the type when you create the finding. Changing it later may drop old values.

Placeholders go in curly braces. The Insert buttons under each box add them at your cursor, and a live preview shows the filled sentence. Capitalization and underscores vs spaces don't matter: {Tear Type} and {tear_type} match the same sub-field.

Names may not contain { } | or :. Slashes, parentheses, and apostrophes are fine (S/D Ratio, Morton's Neuroma).

Pick lists use one template with {value} (e.g. The waveform is {value}.). Normal Options read the same way, just without highlighting. Report text when normal offers three modes for a normal pick: reuse the value text (the default), custom text, or print nothing (the pick is left out of the report draft entirely). For yes/no findings, leave the normal box blank to print nothing.

The liver measures {value} cm at the midclavicular line.

Hepatic cysts are identified, numbering {count}. The largest cyst measures
{largest_cyst_size} cm in segment {largest_cyst_segment}.

A mistyped placeholder renders a warning marker ({unrecognized placeholder name "lragest_cyst"}) so you catch it immediately.

Use a rule when the sentence itself should change at certain values. Each rule is a comparison plus a sentence. Rules run top to bottom; first match wins. No match falls back to the default slot. Highlighting still comes from the normal range. Free Text, Date, Measurement, and Multi-instance findings render values directly, so this card is hidden for them.

Example on Liver Length:

Comparison: greater than
Value:      16.0
Report:     The liver is enlarged, measuring {value} cm
            at the midclavicular line.

A rule can carry cross-conditions, added inline with + Add Condition. The rule fires only when all of them hold. They can reference any finding in the protocol.

Example: a rule on Endometrial Thickness reads "abnormally thickened" only when Menopausal Status equals "Postmenopausal".

A cross-condition can also test a sub-field, including one on the rule's own finding. Sub-fields of multi-instance findings and dimension sub-fields can't be tested.

In the sub-field editor, Show only when limits a sub-field to a specific value of a sibling. Example: Solid Component appears only when Cyst or Solid is "Cystic with solid component". While hidden, it never receives a value.

A Measurement finding captures one to three linear dimensions. Set the Unit (cm or mm), the Axis labels, and the Calculation (none, area, or volume). Both calculations use the prolate-ellipsoid formula: area = (π/4) × d1 × d2; volume = (π/6) × d1 × d2 × d3. The calculated unit is derived (cm → mL or cm²).

Individual axes are not placeholders; {value} always prints all entered axes.

Use Multi-instance when a structure can have several of one thing (cysts, masses, lymph nodes). The sub-fields become the per-item form; the sonographer hits + Add for another.

• Report text when a value is present renders once per instance. Numbered prefixes are added when there is more than one.
• Leading prose is one summary sentence above the list when there are two or more instances.
• {value} and {unit} are not available at the top level. Reference sub-fields by name ({Size::volume}).

A Calculated Classification derives a category from its sibling fields. Configure it in the finding editor's Classification panel:

The badge on the exam form recalculates live. The category is derived on every render, never stored, so the draft, worksheet, and conditions always agree.

• Reference Images: PNGs or JPEGs shown to the sonographer during the exam. Drag to reorder; optional caption.
• Guideline References: a named text block (e.g. ACR TI-RADS criteria) appended under REFERENCES in the draft, only when its trigger finding is abnormal.