Skip to content

B-2a · Updating Your Backend (the Backend Updater)

Draft page

Captions marked [confirm] and the "Open items" section are still being verified against the live product.

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

When: a release note says backend update required, HousingOS shows "Backend update required", or a new feature does nothing after an update. Who: the agency administrator (or Housing Programs with you on a call). Time: 2–5 minutes; everyone else must be out of HousingOS.

What it does

The Backend Updater is a small separate program that opens your data file and adds whatever the new release needs — new tables, new columns, indexes, default rows (status lists, fee types, letter texts, IDIS codes). It never deletes or overwrites your data; every step checks whether it already exists, so running it twice is harmless. It writes a log of what it did.

Steps

  1. Ask all users to close HousingOS (the updater cannot change a file that is open — you'll get a file in use error).
  2. Back up the backend first (copy the .accdb with today's date in the name — ▸ B-14).
  3. Run HousingOS Backend Updater (from the release download or C:\HousingOS\Updater\ [confirm location]).
  4. Point it at the backend (Browse), then click Start. Watch the log: lines like EmailLetters: inserted 3 or Column already exists are normal. It finishes with Done [confirm wording].
  5. Now let the front ends update (Update Now on each workstation, ▸ B-2). Order matters: updater first, front ends second — a new front end against an old backend shows blank fields or "table not found".
  6. Open HousingOS and spot-check the feature named in the release note.

Watch-outs

  • New tables need a new front end. The updater creates the table in the data file; the linked table only appears in the front end shipped with the same release. Don't try to link tables by hand.
  • Run it on the live backend, not a copy — then copy nothing back. (Copying a backend you updated on your desk over the server file loses everyone's work in between.)
  • Errors starting with "Ensure…" name the step that failed; send the log to Housing Programs (▸ B-15).
  • Do not rename the backend file as part of an update; front ends remember the path.

Coming: automatic backend updates

Housing Programs is designing a version that applies backend changes automatically the first time the new front end runs, so this chapter becomes a single line. Until then, follow the steps above.

Screenshot shot list

Shot What
B02a-01 Backend Updater start form with the log after a run

Open items for John

  • Where the updater ships (inside the setup, separate download?), its exact window title and finish message.
  • Whether the updater can run while a user is still in HousingOS (I've said no).