Skip to content

Form XML Conventions

Reference for .ftpackage structure, form XML conventions, and formula patterns used when editing forms directly as XML.

.ftpackage Format

An .ftpackage is a ZIP file. It always contains exactly these 4 entries:

Forms/<FormName>_<Version>.form     The form XML (main content)
Manifest/manifest.xml               Form metadata (name, version, comment)
_rels/.rels                         Package relationship declarations
[Content_Types].xml                 MIME type declarations

To build a .ftpackage from a modified .form file, use PowerShell with System.IO.Compression.ZipFile. See the copilot-instructions.md Section 8 pattern, or ask the agent.

Form XML Conventions

  • Each layout element has a unique <Property name="id"><Value>UUID</Value></Property>.
  • UUIDs are the only guaranteed unique identifier — use them as anchors when patching, not FormItem name (which can repeat across pages/sections).
  • <FormItem name="X" /> at the end of an element block links it to its data item.
  • Formula IDs must be 32 lowercase hex characters with no dashes (e.g. c0b1a2d3e4f5678901234567890abc01). Any other format causes an import error: "Invalid Formula Element: invalid Id format".

z_ Prefix Convention

Form items prefixed z_ are temporary/working fields — not saved to the Data Warehouse. Use this prefix for: - Debug/testing helper fields - Intermediate calculation fields - Fields that should not appear in reports

Dynamic ReadOnly Formula Pattern

Used to make a field editable under a condition. The <Value> fallback is the default static value (True = read-only by default):

<Property name="readOnly">
  <Value>True</Value>
  <Formula id="c0b1a2d3e4f5678901234567890abc01" propertyName="ReadOnly" type="Boolean" enabled="true">
    <Calculations />
    <Conditions>
      <Condition name="IsOther" type="String">
        <Operand type="FormItem">Other_Component</Operand>
        <Operator>Equal</Operator>
        <Value type="Constant">Other</Value>
      </Condition>
    </Conditions>
    <Summaries>
      <Summary isStart="true" isFinal="false">
        <Expression>IsOther</Expression>
        <Value type="Constant">False</Value>   <!-- editable when condition is true -->
      </Summary>
      <Summary isStart="false" isFinal="true">
        <Expression></Expression>
        <Value type="Constant">True</Value>    <!-- read-only otherwise -->
      </Summary>
    </Summaries>
  </Formula>
</Property>

This same structure is used for Visible and Caption properties — change propertyName and type accordingly.

Visibility Formula Pattern (Three-Tier Debug)

Standard debug visibility used across forms:

  1. Explicit debug: user is in DebugUsersList resource → show
  2. Implicit debug: user has "All Forms" permission → show
  3. Otherwise (live) → hide

Reference: Asbestos+reassign+review_1.form or Void First Person Checklist form.

Standard Form Items (Every Form)

Include these in every new form: - Debugger element - Testing button - Bypass Validation button - Abandon Form button

Building a .ftpackage (PowerShell)

Key points: - Copy _rels/.rels and [Content_Types].xml verbatim from the original package — relationship IDs must match. - To read the original metadata: use ZipFile::OpenRead on the existing package and StreamReader on each entry. - Formula IDs: 32 lowercase hex chars, no dashes. Any other format → "Invalid Formula Element: invalid Id format" on import.

For the full PowerShell script pattern, see .github/copilot-instructions.md Section 8.