Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:02:25Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:32, 6 July 2026
Line 217:		Line 217:
	* Flag names are limited to entries registered in the <code>FACILITY</code> <code>FlagRegistry</code>. An unregistered name fails save validation with <code>FlagNotFoundError</code>, so clients cannot introduce arbitrary flag strings.		* Flag names are limited to entries registered in the <code>FACILITY</code> <code>FlagRegistry</code>. An unregistered name fails save validation with <code>FlagNotFoundError</code>, so clients cannot introduce arbitrary flag strings.
	* The <code>{facility, flag}</code> uniqueness holds only over non-deleted rows, so soft-deleted history is preserved and a flag can be removed then re-added.		* The <code>{facility, flag}</code> uniqueness holds only over non-deleted rows, so soft-deleted history is preserved and a flag can be removed then re-added.

			{{Navbox facility}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:02Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=facility
|title=Facility Flag
|order=3
|introduced=3.0
|model=FacilityFlag
|reference=References/Base models & conventions
}}

<code>FacilityFlag</code> binds a registered flag name to a single <code>Facility</code> to gate server-side behaviour. It is not a FHIR resource and has no Pydantic spec — no endpoint, serializer, or <code>...CreateSpec</code>/<code>...ReadSpec</code> — 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-api-schema|Resource specs]]).

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/facility/models/facility_flag.py <code>care/facility/models/facility_flag.py</code>]
* Base/flag machinery: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/utils/models/base.py <code>care/utils/models/base.py</code>]
* Flag registry & types: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/utils/registries/feature_flag.py <code>care/utils/registries/feature_flag.py</code>]
* Surfaced via Facility spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/facility/spec.py <code>care/emr/resources/facility/spec.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>FacilityFlag</code>
| Associates a registered feature flag with a single <code>Facility</code>, gating behaviour per facility
|}

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

== <code>FacilityFlag</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=FacilityFlag|section=FacilityFlag fields|name=flag|type=CharField(max_length=1024)|notes=yes}}
{{Field|model=FacilityFlag|section=FacilityFlag fields|name=facility|type=FK → facility.Facility|notes=yes}}
{{Field|model=FacilityFlag|section=FacilityFlag fields|name=external_id|type=UUIDField|notes=auto}}
{{Field|model=FacilityFlag|section=FacilityFlag fields|name=created_date|type=DateTimeField|notes=auto}}
{{Field|model=FacilityFlag|section=FacilityFlag fields|name=modified_date|type=DateTimeField|notes=auto}}
{{Field|model=FacilityFlag|section=FacilityFlag fields|name=deleted|type=BooleanField|notes=no}}
|}

The model has no <code>JSONField</code>s, so there is no opaque JSON shape to document.

=== Flag type values ===

<code>flag_type</code> is fixed to <code>FlagType.FACILITY</code>. The full <code>FlagType</code> enum (from [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/utils/registries/feature_flag.py <code>feature_flag.py</code>]):

{| class="wikitable"
|-
! <code>FlagType</code> member
! Value
! Used by
|-
| <code>USER</code>
| <code>"USER"</code>
| <code>UserFlag</code> ([[References/User & Skills
|-
| <code>FACILITY</code>
| <code>"FACILITY"</code>
| <code>FacilityFlag</code> (this model)
|}

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

=== Class-level configuration ===

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

{| class="wikitable"
|-
! Attribute
! Value
! Notes
|-
| <code>cache_key_template</code>
| <code>"facility_flag_cache:{entity_id}:{flag_name}"</code>
| Per-flag existence cache key
|-
| <code>all_flags_cache_key_template</code>
| <code>"facility_all_flags_cache:{entity_id}"</code>
| Cache key for a facility's full flag list
|-
| <code>flag_type</code>
| <code>FlagType.FACILITY</code>
| Registry namespace used for flag-name validation
|-
| <code>entity_field_name</code>
| <code>"facility"</code>
| Tells <code>BaseFlag</code> which FK is the owning entity; backs the <code>entity</code> / <code>entity_id</code> properties
|}

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

=== Constraints ===

<syntaxhighlight lang="text">UniqueConstraint(
fields=["facility", "flag"],
condition=Q(deleted=False),
name="unique_facility_flag",
)</syntaxhighlight>
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. <code>Meta.verbose_name = "Facility Flag"</code>.

== Methods & save behaviour ==

=== <code>save()</code> (inherited from <code>BaseFlag</code>) ===

Every save runs four steps in order:

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

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

=== Lookups ===

{| class="wikitable"
|-
! Method
! Returns
! Notes
|-
| <code>check_facility_has_flag(facility_id, flag_name)</code>
| <code>bool</code>
| Delegates to <code>BaseFlag.check_entity_has_flag</code>: validates the flag name, then <code>cache.get_or_set</code> on the per-flag key with an <code>.exists()</code> query; cached for <code>FLAGS_CACHE_TTL</code> (1 day)
|-
| <code>get_all_flags(facility_id)</code>
| <code>tuple[FlagName]</code>
| Delegates to <code>BaseFlag.get_all_flags</code>: <code>cache.get_or_set</code> on the all-flags key, materializing <code>values_list("flag", flat=True)</code> for the facility; cached for 1 day
|}

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

=== Properties (inherited) ===

* <code>entity</code> → the related <code>Facility</code> instance (<code>getattr(self, "facility")</code>)
* <code>entity_id</code> → <code>facility_id</code> (<code>getattr(self, "facility_id")</code>)

== Resource specs (API schema) ==

<code>FacilityFlag</code> has no Pydantic resource spec and no REST endpoint of its own. There is no <code>FacilityFlagCreateSpec</code> / <code>FacilityFlagUpdateSpec</code> / <code>FacilityFlagListSpec</code> / <code>FacilityFlagRetrieveSpec</code>, no serializer, and no viewset — confirmed by their absence from <code>care/emr/resources/</code> and <code>care/facility/api/</code>. 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.

{| class="wikitable"
|-
! Spec
! Field
! Role
! Behaviour
|-
| <code>FacilityRetrieveSpec</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/facility/spec.py <code>facility/spec.py</code>])
| <code>flags: list[str]</code>
| read · detail
| Populated in <code>perform_extra_serialization</code> via <code>mapping["flags"] = obj.get_facility_flags()</code>. Server-maintained and read-only; clients cannot set or mutate flags through the Facility write specs
|}

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

== Related models ==

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

=== <code>BaseFlag</code> (abstract) ===

<syntaxhighlight lang="text">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</syntaxhighlight>
Provides save-time validation, cache invalidation, and the <code>check_entity_has_flag</code> / <code>get_all_flags</code> lookups. Subclasses set <code>flag_type</code>, <code>entity_field_name</code>, and the two cache-key templates. See [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/utils/models/base.py <code>care/utils/models/base.py</code>].

=== <code>FlagRegistry</code> ===

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

{| class="wikitable"
|-
! Method
! Notes
|-
| <code>register(flag_type, flag_name)</code>
| Adds a name to a type's registry, creating the type bucket if needed
|-
| <code>register_wrapper(flag_type, flag_name)</code>
| Class-decorator form of <code>register</code>
|-
| <code>unregister(flag_type, flag_name)</code>
| Removes a name; logs a warning if absent
|-
| <code>validate_flag_type(flag_type)</code>
| Raises <code>FlagNotFoundError</code> ("Invalid Flag Type") if the type bucket is missing
|-
| <code>validate_flag_name(flag_type, flag_name)</code>
| Validates type, then raises <code>FlagNotFoundError</code> ("Flag not registered") if the name is absent
|-
| <code>get_all_flags(flag_type)</code>
| <code>list[FlagName]</code> of registered names
|-
| <code>get_all_flags_as_choices(flag_type)</code>
| <code>(value, value)</code> tuples for Django choices
|}

A flag must be registered before a <code>FacilityFlag</code> referencing it can be saved. See [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/utils/registries/feature_flag.py <code>care/utils/registries/feature_flag.py</code>].

== 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 <code>flags: list[str]</code> field on <code>FacilityRetrieveSpec</code> (see [[#resource-specs-api-schema|Resource specs]]).
* In application code, read through <code>check_facility_has_flag</code> / <code>get_all_flags</code> (or <code>Facility.get_facility_flags()</code>), which are cache-backed. Do not query the table directly for hot-path checks.
* Flag names are limited to entries registered in the <code>FACILITY</code> <code>FlagRegistry</code>. An unregistered name fails save validation with <code>FlagNotFoundError</code>, so clients cannot introduce arbitrary flag strings.
* The <code>{facility, flag}</code> uniqueness holds only over non-deleted rows, so soft-deleted history is preserved and a flag can be removed then re-added.

{{Related}}

References/Facility Flag - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed