Skip to content

B-7 · Word Templates and Document Setup

Book B — Agency Administrator Guide · draft v1 (2026-08-29)

Where: Settings ▸ Word Documents (registry) · Program Documents / Coded Names · Document Paths · Printing Options. Owner: the agency administrator (Housing Programs also edits on request).

How documents work — the 60-second version

Every letter, form or contract is a Word template in the agency's templates folder. HousingOS knows each template by a coded name (Approval Letter, SOW Review Letter, Construction Contract …) registered per program (and, for closing sets, per program × funding source). When a user clicks a document button, HousingOS finds the template for that coded name and program, fills its HousingOS Fields from the project, saves the result in the project's subfolder (by folder key), and previews or emails it. If a slot has no template you get "No Document Set-Up For This Coded Name …"; if the file is missing, "This document is missing. It needs to be added to the templates folder."

1. Templates folder (Document Paths)

Find File Path picks the shared folder ("SELECT the Folder to store DATABASE WORD DOCUMENTS"); every workstation must see the same UNC path. Open Templates Folder opens it in Explorer.

2. Registry (Word Documents)

One row per template: List name (what users see in Printing Options), coded name (the slot buttons look for — a warning fires if you change a coded name that code depends on), program, funding source (closing sets), file (Select File browses the templates folder; Open checks it exists), the folder key (which project subfolder the output goes to — Application, Documents, Correspondence, Bidding …), and the default print/email options (▸ 4). Add missing document types on the Program Documents form creates the empty slots for a new program so you can see what's still unassigned.

3. Editing a template safely

  • Open the .docx from the templates folder, change wording, save in place. Don't rename.
  • Never delete or overtype a HousingOS Field or bookmark — the field is what HousingOS fills. If you remove one, its value silently disappears and whatever text you typed there prints on every document ("$0.00", "Sample Text", an old client's name).
  • HousingOS Fields look like [Applicant Name] boxes (Word's own name for them is content controls; Developer ▸ Design Mode shows them). List sections use Word bookmarks (Field1 … FieldN); Word ▸ Insert ▸ Bookmark lists those.
  • Need a field the template doesn't have? Copy it from the HousingOS Fields reference document (▸ 3a) — never type a box by hand.
  • Test on the Demo project: produce the document, check every field, then tell users.
  • Housing Programs' shipped defaults are in the registry with a default flag; your edited copies are kept on updates.

3a. HousingOS Fields reference documents

Need to see every field HousingOS can fill, or add a field your template does not have yet? Both document setup pages carry HousingOS Fields buttons:

  • Settings ▸ Program Documents — header buttons a Template and c Template, plus a HousingOS Fields button on each card that opens the set that card uses (c_ Template cards use the c document too).
  • Settings ▸ Additional Documents (Additional Merge Documents) — the same two header buttons.

Each button opens the reference document for that template set read-only in Word, straight from the HousingOS web site, so you always see the current list of fields. Each field is a box with a friendly title; Developer ▸ Design Mode shows the tags.

To add a field to your template

  1. Click the button. Word opens HousingOS Fields - a Template (updated ) (or c Template). Word may show a yellow Protected View bar the first time — click Enable Editing; the file stays read-only.
  2. Click the box you want (its title tab appears) and copy it (Ctrl+C).
  3. Open your template from the templates folder, click where the value goes, paste (Ctrl+V), and save the template in place.
  4. Test on the Demo project (▸ 3).

Watch-outs

  • Do not Save As a copy of the reference document. Housing Programs updates it whenever fields are added or renamed; a saved copy goes stale without warning. Always open it from the HousingOS button — the title carries the date it was last updated.
  • Pick the right set. A card's HousingOS Fields row shows which set it uses (a Template / c Template). A field pasted from the wrong set stays empty when the document merges.
  • Use desktop Word. Copying from Word in the browser loses the field and pastes plain text.
  • You cannot save over the reference document — if Word offers Save As, you are in the reference file, not your template.

4. Printing Options (defaults per document)

For each document set which choices users get in Printing Options: Preview, Email, Print, Word document only; default CC ticks (applicant / contractor / loan coordinator / rehab specialist / supervisor); whether the letter text is copied into the email body or the agency's standard email body is used; applicant-related vs contractor-related; and whether the document includes an envelope. Users see only what you allow (▸ C-18).

5. Email letter templates (bid invitations, thank-you, homeowner notice)

These are email-only texts, not Word: Manage Letters… in the Bid Letters dialog (▸ C-12) — subject + body with [bracket] placeholders, per area (Bidding now). Shipped defaults have a Restore Default; user-added letters are yours. Placeholders are filled by the same engine (ReplaceBrackets); the suggestion popup lists them when you type [.

Watch-outs

  • One coded name per program per slot. Two rows with the same coded name for one program → the wrong one may merge.
  • "$0.00" complaints from users are always template text, never data (▸ C-18 watch-outs).
  • Templates opened by a user block the merge ("This document is currently open"); keep the templates folder read-only for staff if you can.
  • Word Documents backend empty at onboarding (blank Printing Options list) — Housing Programs seeds it; tell them (▸ A-3).

Screenshot shot list

Shot What
B07-01 Word Documents registry
B07-02 Program Documents / Coded Names
B07-03 Printing Options setup
B07-04 a template in Word with Design Mode on
B07-05 Program Documents header + card HousingOS Fields buttons
B07-06 the reference document open read-only in Word (title bar shows Read-Only)

Open items for John

  • Exact captions of the three setup forms and their buttons.
  • Your rule of thumb for agencies: may they edit any template, or only correspondence letters (the "safe subset")?