Feature Flag and Rollback Safety for AFH Software

Feature flags let adult family home software release a new medication form, pharmacy workflow, report, or dashboard to a controlled audience without deploying different code. They also create risk: two facilities can see different rules, a disabled feature can leave partial records, and a careless rollback can hide evidence already created under the new workflow.

This guide covers release engineering, not clinical or operational authority. It was reviewed on August 8, 2026. Organizations should test changes with demonstration data, document continuity procedures, and protect resident records through every rollout and rollback.

Inventory flags as production configuration

For every flag, record:

• Stable name and business purpose
• Owner and approver
• Created and expected retirement dates
• Environments
• Eligible facilities, roles, or user cohorts
• Default and fail-safe value
• Dependencies and mutually exclusive flags
• Data schema and workflow effects
• Metrics and rollback trigger
• Current rollout history

Do not hide flags in scattered environment variables or source-code conditionals. Treat changes as privileged configuration with review and audit.

Separate deployment from activation

Deploy code that can safely handle both old and new states before enabling the feature. Database changes should be additive and backward compatible during the rollout window.

Activation changes user behavior; deployment only makes that behavior available. Keep their timestamps and approvers separate so investigators can determine whether a defect came from code, configuration, or cohort selection.

Do not remove the old read path while residents or orders still use it.

Choose the correct evaluation scope

A flag may evaluate by:

• Platform environment
• Facility
• Pharmacy-facility relationship
• User role
• Specific demonstration account
• Percentage cohort
• Record version
• Capability entitlement

Clinical and tenant-sensitive features should usually use explicit facility and role allowlists before percentage rollout. A random percentage can split caregivers in the same home across incompatible workflows.

Resolve scope on the server for protected behavior. Client flags can control presentation but cannot grant access.

Keep tenant boundaries intact

A facility-specific flag must never reveal another facility's resident, configuration, or rollout status. Include tenant context in evaluation and cache keys.

When a multi-facility user switches facilities, recompute flags and cancel stale requests. Do not carry a pharmacy pilot feature from Facility Alpha into Beta because the same user remains signed in.

Audit the evaluated facility, flag version, result, and protected action using opaque identifiers.

Define a safe default

If the flag service is slow or unavailable, use a documented local default. For a new write workflow, the safe default may be disabled. For a security control or schema reader, disabling it may be unsafe; the application may need to fail closed or use a bundled configuration.

Do not assume “false” is always safe. Identify what happens to existing records, pending submissions, and offline clients under service failure.

Cache flag values for a bounded period and include version and tenant scope.

Preserve record provenance

Every record created under flagged behavior should store the workflow or schema version that interpreted it. A medication order needs its order version; a report needs its query version; a pharmacy event needs its schema version.

Do not rely on the current flag value to explain historical records. A flag may be retired years before the resident record retention period ends.

The audit trail guide explains attributable events and configuration history.

Roll out in observable stages

Use a sequence:

1. Internal synthetic accounts.
2. Dedicated demonstration facility.
3. Small named pilot facilities.
4. Broader facilities with monitored roles.
5. General availability.
6. Flag retirement after stability.

At each stage, verify success measures and reconciliation checks. Do not advance solely because error rates appear low; missing events may produce no errors.

Publish user-facing release notes and training before the behavior reaches caregivers.

Define business-level health checks

For a medication feature, check:

• Orders accepted exactly once
• Future schedules created completely
• MAR outcomes trace to the right order version
• Alerts recalculate
• Pharmacy and facility states reconcile
• No cross-facility access

For reports, compare row counts, filters, resident scope, and PDFs. For documents, compare file processing, permissions, and deleted-item states.

Technical page-load success is not enough.

Design rollback before rollout

Classify rollback types:

• Disable new entry while retaining read support
• Return users to the old interface with shared data model
• Stop a background worker
• Revert configuration only
• Deploy prior compatible code
• Activate a corrective forward fix

Never roll back by deleting records created under the new workflow. If the old interface cannot read them, keep a protected compatibility view and pause affected writes.

Document owner, trigger, maximum decision time, data reconciliation, communication, and recovery.

Handle in-flight work

When a flag changes, users may have forms open, queued offline events, pharmacy submissions awaiting acceptance, or reports rendering.

Bind each operation to the workflow version present when it began. On submission, the server can accept under that version, migrate safely, or return a clear refresh-and-review response.

Do not reinterpret a medication order mid-form under a newer required-field schema. Preserve entered data and show what changed.

Protect background jobs and queues

Workers should receive an explicit feature or schema version rather than consulting a mutable global flag after dequeue. Otherwise an event created under the pilot can be processed differently after rollback.

For each job, define whether disabling the flag stops new enqueue, stops processing, or changes output. Drain or quarantine incompatible items deliberately.

Reconcile queue items with business records after every rollout change.

Avoid permanent flag debt

Once a feature is fully stable, remove obsolete branches, tests, configuration, and evaluation calls in a planned release. Preserve historical version names in record schemas and audit dictionaries.

Temporary flags without retirement become untestable combinations. Track age, last evaluation, owner, and cleanup issue.

Do not remove a permission or kill switch that serves an ongoing security purpose merely to reduce count; classify long-lived operational controls separately.

Control flag administration

Require strong authentication and least privilege to change production flags. Use two-person approval for broad medication, authorization, billing, or data-lifecycle changes where risk warrants it.

Show an exact preview of facilities, roles, and capabilities affected. Bulk percentage changes need a named cohort snapshot so later review can reproduce it.

Record request, approver, old and new values, scope, reason, activation, metrics, and rollback.

Communicate without exposing pilots

Tell affected facility users what changed, when, how to get help, and what to expect on rollback. Avoid exposing other facilities' enrollment or performance.

Support tools should show the flag evaluation for the current case through authorized tenant context. General logs use opaque facility references.

A “feature unavailable” message should distinguish planned disablement from lost authorization or system failure.

Test flag combinations and failure

Connect release controls to a secure development process

Feature flags should sit inside the same evidence trail as code review, automated testing, dependency review, deployment approval, and incident response. NIST Secure Software Development Framework SP 800-218 organizes secure development practices around preparing the organization, protecting software, producing well-secured releases, and responding to vulnerabilities. For an AFH platform, a practical release record can identify the reviewed change, flag owner, affected facility cohort, test evidence, activation time, health thresholds, rollback decision, and retirement task. This prevents a flag console from becoming a parallel release system with weaker governance.

The release reviewer should also distinguish technical success from care-workflow success. A deployment can have low error rates while producing duplicate medication prompts, delayed notifications, or facility-context confusion. Capture those operational measures before activation, compare them during the pilot, and make them part of the rollback decision. When a rollback occurs, record which software behavior changed and which resident records or queued events still require reconciliation. That evidence makes the next release safer without erasing what actually happened.

Use demonstration tenants to verify:

1. Default value with flag service unavailable.
2. Alpha enabled and Beta disabled.
3. User switches facilities during a request.
4. Role changes while a page is open.
5. Old and new clients read the same records.
6. Form begins before activation and submits after.
7. Pharmacy event waits during rollback.
8. Background worker receives explicit version.
9. Offline event reconnects after disablement.
10. New schedule is preserved after UI rollback.
11. Repeated flag update is idempotent.
12. Unauthorized user cannot change configuration.
13. Percentage cohort remains reproducible.
14. Rollback health checks reconcile data.
15. Flag retirement removes dead paths.
16. Historical report retains workflow provenance.

Test APIs and workers directly, not only visible toggles.

Frequently asked questions

Is a feature flag an authorization control?

No. It can gate rollout, but server authorization must still enforce role, facility, resident, and action permissions.

Should rollback delete new records?

No. Preserve records and provenance, stop incompatible writes, support reading, and reconcile or correct through versioned workflows.

Can percentage rollout include caregivers in one facility differently?

It can, but that may create unsafe workflow inconsistency. Prefer named facility cohorts for interconnected care processes.

What happens when the flag service fails?

Use a documented, cached or bundled fail-safe behavior selected per feature risk; do not assume false is universally safe.

When should a flag be removed?

After general availability is stable, rollback no longer needs the branch, and data compatibility is verified. Preserve historical schema and audit meanings.

Release improvements without rewriting resident history

Safe feature rollout uses explicit scope, backward-compatible code, tenant-aware evaluation, record provenance, business reconciliation, planned rollback, in-flight handling, and controlled retirement.

Explore AFH Manager to test facility pilots, medication workflow versions, background jobs, rollback, offline events, flag administration, and release reconciliation with synthetic data.