Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

2026-07-06T04:25:28Z

Add Navbox platform (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:55, 6 July 2026
Line 214:		Line 214:
	* The list is capped at <code>settings.MAX_FAVORITES_PER_LIST</code> (env <code>MAX_FAVORITES_PER_LIST</code>, default <code>50</code>). <code>add_favorite</code> drops the oldest entries beyond the cap.		* The list is capped at <code>settings.MAX_FAVORITES_PER_LIST</code> (env <code>MAX_FAVORITES_PER_LIST</code>, default <code>50</code>). <code>add_favorite</code> drops the oldest entries beyond the cap.
	* Never set the <code>user_favorites_lists:</code> or <code>user_favorites_list_object:</code> cache keys from a client. <code>save()</code> / <code>refresh_cache()</code> maintain them, and <code>remove_favorite</code> tears them down when a list empties.		* Never set the <code>user_favorites_lists:</code> or <code>user_favorites_list_object:</code> cache keys from a client. <code>save()</code> / <code>refresh_cache()</code> maintain them, and <code>remove_favorite</code> tears them down when a list empties.

			{{Navbox platform}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:27Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=platform
|title=Favorites
|order=7
|introduced=3.0
|model=Favorites
|reference=References/Organization
}}

<code>UserResourceFavorites</code> lets a user pin resource IDs into named lists so the owning resource's list endpoint can surface them first. It's a Care-internal personalization feature, not a FHIR resource — you touch it when you add favoriting to a resource's UI.

Each list is scoped by a <code>resource_type</code> and, optionally, a <code>facility</code>. There's no <code>EMRResource</code> serialize/de_serialize spec here. The moving parts are an enum (<code>FavoriteResourceChoices</code>), a default-list constant, a DRF filter backend (<code>FavoritesFilter</code>), and a viewset mixin (<code>EMRFavoritesMixin</code>) that wires up the read/write endpoints.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/favorites.py <code>care/emr/models/favorites.py</code>]
* Spec (enum + constant): [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/favorites/spec.py <code>care/emr/resources/favorites/spec.py</code>]
* Filter backend: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/favorites/filters.py <code>care/emr/resources/favorites/filters.py</code>]
* Viewset mixin: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/favorites.py <code>care/emr/api/viewsets/favorites.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>UserResourceFavorites</code>
| Stores a per-user, named list of favorited resource integer PKs, optionally scoped to a facility and constrained to one resource type
|}

<code>UserResourceFavorites</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, the audit fields <code>created_by</code> / <code>updated_by</code> / <code>created_date</code> / <code>modified_date</code>, and soft-delete semantics.

== <code>UserResourceFavorites</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Favorites|section=UserResourceFavorites fields|name=user|type=FK → User|notes=optional}}
{{Field|model=Favorites|section=UserResourceFavorites fields|name=favorites|type=ArrayField(IntegerField)|notes=yes}}
{{Field|model=Favorites|section=UserResourceFavorites fields|name=favorite_list|type=CharField(255)|notes=yes}}
{{Field|model=Favorites|section=UserResourceFavorites fields|name=resource_type|type=CharField(255)|notes=yes}}
{{Field|model=Favorites|section=UserResourceFavorites fields|name=facility|type=FK → Facility|notes=optional}}
|}

The tuple <code>(user, resource_type, facility, favorite_list)</code> addresses a single row: it's what the cache keys and the <code>get_or_create</code> in <code>add_favorite</code> are built from.

=== <code>resource_type</code> values — <code>FavoriteResourceChoices</code> ===

The API constrains <code>resource_type</code> to the string values of <code>FavoriteResourceChoices</code> (<code>care/emr/resources/favorites/spec.py</code>). Each viewset binds to exactly one value through its <code>FAVORITE_RESOURCE</code> attribute.

{| class="wikitable"
|-
! Value
! Bound resource
! Wired viewset
|-
| <code>activity_definition</code>
| [[References/Activity Definition
| Activity definition]]
|-
| <code>charge_item_definition</code>
| [[References/Charge Item Definition
| Charge item definition]]
|-
| <code>product_knowledge</code>
| [[References/Product Knowledge
| Product knowledge]]
|-
| <code>observation_definition</code>
| [[References/Observation Definition
| Observation definition]]
|-
| <code>questionnaire</code>
| [[References/Questionnaire]]
| <code>QuestionnaireViewSet</code>
|-
| <code>facility_organization</code>
| [[References/Organization]] (facility org)
| <code>FacilityOrganizationViewSet</code>
|}

== Resource specs (API schema) ==

Favorites skip the <code>EMRResource</code> Create/Update/List/Retrieve pattern. The spec surface is just:

{| class="wikitable"
|-
! Symbol
! Kind
! Role
|-
| <code>FavoriteResourceChoices</code>
| <code>str, Enum</code> (<code>spec.py</code>)
| Allowed <code>resource_type</code> values (table above). A viewset selects one via <code>FAVORITE_RESOURCE = FavoriteResourceChoices.<x>.value</code>
|-
| <code>DEFAULT_FAVORITE_LIST</code>
| constant (<code>spec.py</code>)
| <code>"default"</code> — the list name used when the request omits <code>favorite_list</code>
|-
| <code>FavoriteRequest</code>
| <code>pydantic.BaseModel</code> (viewset)
| Request body for write actions. One field: <code>favorite_list: str = DEFAULT_FAVORITE_LIST</code>
|-
| <code>FavoritesFilter</code>
| DRF <code>BaseFilterBackend</code> (<code>filters.py</code>)
| Read path. Adds the <code>favorite_list</code> query param to the resource's list endpoint and restricts/orders results to that user's favorites
|-
| <code>EMRFavoritesMixin</code>
| viewset mixin (<code>api/viewsets/favorites.py</code>)
| Adds the <code>favorite_lists</code>, <code>add_favorite</code>, <code>remove_favorite</code> actions
|}

=== <code>FavoriteRequest</code> ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
|-
| <code>favorite_list</code>
| <code>str</code>
| optional
| <code>"default"</code> (<code>DEFAULT_FAVORITE_LIST</code>)
|}

Favorited objects have no read schema of their own. They come back through the owning resource's list endpoint — for example, the questionnaire list serializer — filtered and ordered by <code>FavoritesFilter</code>. The <code>favorite_lists</code> action returns only <code>{"lists": [<list name>, ...]}</code>.

== Related models ==

* [[References/User & Skills|<code>User</code>]] — owner of every favorites row (<code>user</code> FK)
* [[References/Facility|<code>Facility</code>]] — optional scope (<code>facility</code> FK); <code>null</code> = instance-wide
* Each <code>resource_type</code> binds to one favoritable resource — see the [[#resource_type-values--favoriteresourcechoices|<code>FavoriteResourceChoices</code> table]]

== Methods & save behaviour ==

Every row is mirrored into a Django cache, kept in sync by <code>save()</code> and <code>refresh_cache()</code>.

=== Cache keys ===

Two module-level helpers build the keys, encoding a missing facility as <code>-</code>:

<syntaxhighlight lang="text">favorite_lists_cache_key(user, resource_type, facility)
→ "user_favorites_lists:{user.id}:{resource_type}:{facility.id|-}"

favorite_list_object_cache_key(user, resource_type, facility, favorite_list)
→ "user_favorites_list_object:{user.id}:{resource_type}:{facility.id|-}:{favorite_list}"</syntaxhighlight>
* The lists key holds the ordered, deduplicated set of <code>favorite_list</code> names a user has for a <code>(resource_type, facility)</code>.
* The list-object key holds the <code>favorites</code> integer array for one named list.

=== <code>refresh_cache(refresh_list=False)</code> ===

* Always writes the current <code>favorites</code> array under the list-object key.
* With <code>refresh_list=True</code>, also recomputes the deduplicated, <code>modified_date</code>-descending set of <code>favorite_list</code> names for the <code>(user, resource_type, facility)</code> and writes it under the lists key.

=== <code>save()</code> side effects ===

<code>save()</code> sets <code>refresh_list = not self.pk</code> (true only on insert), calls <code>super().save()</code>, then <code>refresh_cache(refresh_list=refresh_list)</code>. So:

# Creating a new list refreshes both the lists cache and the list-object cache.
# Updating an existing list refreshes only the list-object cache — the set of list names hasn't changed.

Treat these keys as platform-maintained. Write through the model or the endpoints so the cache stays consistent.

== API integration notes ==

There's no standalone favorites endpoint. Favorites ride on the owning resource's viewset through <code>EMRFavoritesMixin</code>. A viewset opts in by mixing in <code>EMRFavoritesMixin</code>, setting <code>FAVORITE_RESOURCE</code>, and adding <code>FavoritesFilter</code> to <code>filter_backends</code>:

<syntaxhighlight lang="python">class QuestionnaireViewSet(EMRModelViewSet, EMRFavoritesMixin):
filter_backends = [filters.DjangoFilterBackend, FavoritesFilter]
FAVORITE_RESOURCE = FavoriteResourceChoices.questionnaire.value</syntaxhighlight>
=== Endpoints (relative to the owning resource) ===

{| class="wikitable"
|-
! Action
! Method · route
! Body
! Behaviour
|-
| <code>add_favorite</code>
| <code>POST {resource}/{id}/add_favorite/</code>
| <code>FavoriteRequest</code>
| <code>get_or_create</code> the <code>(user, favorite_list, resource_type, facility)</code> row, <code>insert(0, obj.id)</code> (newest-first), dedupe, trim to <code>MAX_FAVORITES_PER_LIST</code>, save. Returns <code>{}</code>
|-
| <code>remove_favorite</code>
| <code>POST {resource}/{id}/remove_favorite/</code>
| <code>FavoriteRequest</code>
| Pops <code>obj.id</code> from the list. Emptying the list deletes the row and both cache keys. 404/validation error if the list does not exist. Returns <code>{}</code>
|-
| <code>favorite_lists</code>
| <code>GET {resource}/favorite_lists/</code>
| —
| Returns <code>{"lists": [<name>, ...]}</code> (cache-first, falls back to DB). Resolves <code>facility</code> from the <code>facility_external_id</code> kwarg or <code>?facility=</code> query param
|-
| list (filtered)
| <code>GET {resource}/?favorite_list=<name></code>
| —
| <code>FavoritesFilter</code> restricts the resource list to <code>id__in=favorites</code> and orders by favorite position (<code>sort_index</code>). Empty/unknown list → empty queryset
|}

What's server-maintained or validated:

* <code>resource_type</code> is never client-supplied — each viewset fixes it via <code>FAVORITE_RESOURCE</code>. The client only sends <code>favorite_list</code>.
* <code>facility</code> is derived server-side via <code>retrieve_facility_obj(obj)</code> (defaulting to <code>obj.facility</code>), so favorites inherit the favorited object's facility scope. A <code>null</code> <code>facility</code> is an instance-wide list; a set one is facility-scoped.
* <code>favorites</code> holds integer primary keys, not <code>external_id</code>s. Order is newest-first; <code>add_favorite</code> re-inserts at position 0 and dedupes.
* The list is capped at <code>settings.MAX_FAVORITES_PER_LIST</code> (env <code>MAX_FAVORITES_PER_LIST</code>, default <code>50</code>). <code>add_favorite</code> drops the oldest entries beyond the cap.
* Never set the <code>user_favorites_lists:*</code> or <code>user_favorites_list_object:*</code> cache keys from a client. <code>save()</code> / <code>refresh_cache()</code> maintain them, and <code>remove_favorite</code> tears them down when a list empties.

{{Related}}

References/Favorites - Revision history

Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed