Facility administration

Facility Flag

FacilityFlag binds a registered flag name to a single Facility to gate server-side behaviour. It is not a FHIR resource and has no Pydantic spec — no endpoint, serializer, or ...CreateSpec/...ReadSpec — so everything below comes from the Django…

3.1 · versioned documentation · 6 min read

FacilityFlag binds a registered flag name to a single Facility to gate server-side behaviour. It is not a FHIR resource and has no Pydantic spec — no endpoint, serializer, or ...CreateSpec/...ReadSpec — so everything below comes from the Django storage model. Clients never write flags; they read them as a derived array on the Facility resource (see Resource specs).

Source:

• Model: care/facility/models/facility_flag.py
• Base/flag machinery: care/utils/models/base.py
• Flag registry & types: care/utils/registries/feature_flag.py
• Surfaced via Facility spec: care/emr/resources/facility/spec.py

Models

FacilityFlag extends BaseFlag, which extends BaseModel — the MANSOQ EMR base providing external_id (UUID), created_date/modified_date audit timestamps, and soft-delete via deleted. BaseModel is leaner than EMRBaseModel (see Base model): no created_by/updated_by, no history, no meta JSON. BaseFlag adds the flag value and the per-entity machinery: cache invalidation and validation against the flag registry.

FacilityFlag fields

The model has no JSONFields, so there is no opaque JSON shape to document.

Flag type values

flag_type is fixed to FlagType.FACILITY. The full FlagType enum (from feature_flag.py):

The flag values themselves are not enumerated in source. They are registered at runtime via FlagRegistry.register(FlagType.FACILITY, "<name>"), and a name absent from the FACILITY registry raises FlagNotFoundError on save.

Class-level configuration

These class attributes wire FacilityFlag into the generic BaseFlag caching and validation logic. They are not database fields.

Module-level constants mirror these templates: FACILITY_FLAG_CACHE_KEY ("facility_flag_cache:{facility_id}:{flag_name}"), FACILITY_ALL_FLAGS_CACHE_KEY ("facility_all_flags_cache:{facility_id}"), and FACILITY_FLAG_CACHE_TTL (60 * 60 * 24, 1 day).

Constraints

UniqueConstraint(
    fields=["facility", "flag"],
    condition=Q(deleted=False),
    name="unique_facility_flag",
)

A facility holds a given flag at most once among non-deleted rows. The condition excludes soft-deleted rows, so a flag can be removed and re-added. Meta.verbose_name = "Facility Flag".

Methods & save behaviour

save() (inherited from BaseFlag)

Every save runs four steps in order:

1. validate_flag(self.flag) calls FlagRegistry.validate_flag_name(FlagType.FACILITY, flag), which validates the flag type, then checks that the name is registered. An unknown type or unregistered name raises FlagNotFoundError (a subclass of Django ValidationError) and the row is not written.
2. The per-flag cache key (facility_flag_cache:{facility_id}:{flag}) is deleted.
3. The all-flags cache key (facility_all_flags_cache:{facility_id}) is deleted.
4. The row is persisted via super().save().

Deletes use the BaseModel soft-delete: delete() sets deleted = True and saves update_fields=["deleted"]. It does not purge cache entries, so they expire by TTL or are rebuilt on the next miss.

Lookups

Both wrap the generic BaseFlag methods using entity_field_name="facility". Facility.get_facility_flags() is a thin wrapper over FacilityFlag.get_all_flags(self.id).

Properties (inherited)

• entity → the related Facility instance (getattr(self, "facility"))
• entity_id → facility_id (getattr(self, "facility_id"))

Resource specs (API schema)

FacilityFlag has no Pydantic resource spec and no REST endpoint of its own. There is no FacilityFlagCreateSpec / FacilityFlagUpdateSpec / FacilityFlagListSpec / FacilityFlagRetrieveSpec, no serializer, and no viewset — confirmed by their absence from care/emr/resources/ and care/facility/api/. Flags are administered through Django admin or registration/management code, not the public API.

Flags reach API clients in exactly one place: the Facility resource exposes them as a derived read-only field.

The flags array is the materialized list of registered flag names attached to the facility, from FacilityFlag.get_all_flags (cache-backed, 1-day TTL). No value set is bound to it — entries are the runtime FACILITY registry names, not a coded concept. The User resource mirrors this, exposing flags via obj.get_all_flags() backed by UserFlag (see User).

Related models

FacilityFlag defines no secondary models. Its behaviour comes from two utilities in care/utils.

BaseFlag (abstract)

flag → CharField(max_length=1024)
(abstract base — no table of its own)
class attrs: cache_key_template, all_flags_cache_key_template, flag_type, entity_field_name

Provides save-time validation, cache invalidation, and the check_entity_has_flag / get_all_flags lookups. Subclasses set flag_type, entity_field_name, and the two cache-key templates. See care/utils/models/base.py.

FlagRegistry

An in-process, class-level registry (_flags: dict[FlagType, dict[FlagName, bool]]) of valid flag names per FlagType. Key methods:

A flag must be registered before a FacilityFlag referencing it can be saved. See care/utils/registries/feature_flag.py.

API integration notes

• There is no CRUD endpoint. Manage flags via Django admin or registration/management code; clients only observe them through the read-only flags: list[str] field on FacilityRetrieveSpec (see Resource specs).
• In application code, read through check_facility_has_flag / get_all_flags (or Facility.get_facility_flags()), which are cache-backed. Do not query the table directly for hot-path checks.
• Flag names are limited to entries registered in the FACILITY FlagRegistry. An unregistered name fails save validation with FlagNotFoundError, so clients cannot introduce arbitrary flag strings.
• The {facility, flag} uniqueness holds only over non-deleted rows, so soft-deleted history is preserved and a flag can be removed then re-added.

Related

• Reference: Facility
• Reference: Facility Config
• Reference: User — the USER flag counterpart of the same BaseFlag machinery
• Reference: Base model
• Source: facility_flag.py on GitHub

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/facility/facility-flag.mdx:1 · f6e9f05f