Overview

Every entity in the FutureFund Connect hierarchy — state, district, council, and unit — carries a set of attributes that drive document generation. Some attributes are first-class fields on the record (name, EIN, address, corporate number, etc.). Others live in a flexible metadata bag attached to each entity, which lets you store additional values without changing the database schema.

When a file generator runs (for example, when a unit produces its bylaws PDF), Connect reads attributes from the relevant entities, applies override rules where appropriate, and substitutes the values into the template. Understanding how attributes, metadata, and overrides work together is essential when configuring file generators — particularly bylaws — that span multiple levels of the hierarchy.

How Metadata Works

Each entity (PtaState, District, Council, Unit) has a metadata field that stores arbitrary key/value pairs. Metadata is the right place to put values that:

• Vary from one entity to another but aren’t part of the standard schema (e.g., custom assessment fees, council-specific deadlines).
• Need to be referenced in Liquid templates inside a file generator’s formulas, ask_when, hide_when, or addendum rules.
• Should be editable by administrators without requiring a code change.

Inside Liquid templates, metadata is exposed automatically through entity drops:

• {{ unit.<key> }} reads from the Unit’s metadata if <key> is not a built-in attribute.
• {{ council.<key> }} reads from the Council’s metadata.
• {{ district.<key> }} reads from the District’s metadata.

Built-in attributes (name, legalname, ein, address, city, state, postalcode, corporate_number, etc.) are always returned first; metadata only fills in keys that aren’t already defined as methods on the drop.

Unit Overrides for Council Attributes

Councils typically define values that all of their units inherit — for example, a council-wide assessment fee or a uniform dues deadline. Occasionally a single unit needs to deviate from the council default. Connect supports this through a controlled unit override mechanism.

When a file generator field is configured with a council data source, Connect first checks whether the field is in the override allowlist and whether the unit has a value set in its metadata for that field. If both are true, the unit value wins; otherwise the council value is used.

The override allowlist currently includes:

• assessment_fee
• assessment_fee_deadline_on
• delegates
• dues_deadline_on

To override a council value for a single unit:

1. Open the unit and edit its metadata.
2. Add a key matching the field name above (for example, assessment_fee).
3. Set the value you want that unit to use.
4. Re-run any affected file generators — the unit’s value will now appear instead of the council’s.

If the unit’s metadata key is missing or blank, Connect falls back to the council value, so overrides are always opt-in. Fields outside the allowlist are not overridable through unit metadata; council values flow through unchanged.

Note: This override applies to file generator fields whose data source is set to “council.” Liquid expressions that explicitly read {{ council.<key> }} always read from the council’s metadata and do not consult unit metadata. If a template should prefer the unit value, write the expression as {{ unit.<key> | default: council.<key> }}.

How Document Generators Use Attributes

File generators combine a base PDF template with a set of file fields that are overlaid onto the page. Each file field declares a data source that tells Connect where to pull its value:

When the PDF is rendered, Connect walks every file field, resolves the value through the appropriate source, formats it according to the field’s data type (text, amount, amounttext, date, numbertext, checkbox, etc.), and overlays it on the correct page at the configured coordinates. Calculated fields and conditional rules (ask_when, hide_when, addendum include_addendum?) all use the same Liquid drops, so any attribute reachable as unit.x, council.x, or district.x — including metadata keys — is available throughout the generator.

Tips

• Prefer first-class fields over metadata when a value is universal. Metadata is best for sparse, entity-specific data.
• Match key names exactly. Metadata keys are strings; assessment_fee and Assessment_Fee are different keys.
• Test overrides on a single unit before rolling out a council-wide change so you can confirm the override flows through to the generated PDF.
• Use {{ unit.foo | default: council.foo }} in custom Liquid formulas when you want a unit metadata value to override a council value outside the built-in allowlist.
• Keep the allowlist intentional. Adding a new field to the unit/council override list requires a code change — coordinate with engineering before promising new override behavior to administrators.
• Document custom metadata keys for your state organization so future administrators understand what each key drives in the generated documents.