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

2026-07-06T04:02:02Z

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

Admin: OHC identity seed

2026-07-04T22:45:00Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=facility
|title=Facility Config
|order=2
|introduced=3.0
|model=FacilityConfig
|reference=References/Base models & conventions
}}

Holds one facility's billing configuration: a discount-code catalog, discount component definitions, a discount-stacking rule, and the invoice-number template. The Django model <code>FacilityMonetoryConfig</code> stores all of it, but three fields are plain <code>JSONField</code>s whose shape, enums, and validation live in the Pydantic specs that drive the API. Both layers are documented here.

'''Sources:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/facility_config.py <code>care/emr/models/facility_config.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/facility/spec.py <code>care/emr/resources/facility/spec.py</code>]
* Monetary types: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/monetary_component.py <code>care/emr/resources/common/monetary_component.py</code>]
* Coding: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/coding.py <code>care/emr/resources/common/coding.py</code>]
* Expression evaluator: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/invoice/default_expression_evaluator.py <code>care/emr/resources/invoice/default_expression_evaluator.py</code>]
* API viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/facility.py <code>care/emr/api/viewsets/facility.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>FacilityMonetoryConfig</code>
| Per-facility billing config: facility-scoped discount codes, discount monetary component definitions, a discount-stacking rule, and the invoice-number expression
|}

<code>FacilityMonetoryConfig</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], so it inherits <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and the <code>history</code>/<code>meta</code> JSON fields.

== <code>FacilityMonetoryConfig</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=FacilityConfig|section=FacilityMonetoryConfig fields|name=facility|type=OneToOneField → Facility|notes=yes}}
{{Field|model=FacilityConfig|section=FacilityMonetoryConfig fields|name=discount_codes|type=JSONField → list[Coding]|notes=no}}
{{Field|model=FacilityConfig|section=FacilityMonetoryConfig fields|name=discount_monetary_components|type=JSONField → list[MonetaryComponentDefinition]|notes=no}}
{{Field|model=FacilityConfig|section=FacilityMonetoryConfig fields|name=discount_configuration|type=JSONField → DiscountConfiguration | null|notes=no}}
{{Field|model=FacilityConfig|section=FacilityMonetoryConfig fields|name=invoice_number_expression|type=CharField(1000)|notes=no}}
|}

<blockquote><code>discount_codes</code>, <code>discount_monetary_components</code>, and <code>discount_configuration</code> are declared as plain <code>JSONField</code>s. The database accepts any JSON — their structure is enforced only at the API layer by the Pydantic specs below.
</blockquote>
== JSON field shapes ==

=== <code>Coding</code> shape ===

Each <code>discount_codes[]</code> entry is a <code>Coding</code> object (<code>model_config = extra="forbid"</code>, so unknown keys are rejected).

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=FacilityConfig|section=Coding shape|name=system|type=str | null|notes=no}}
{{Field|model=FacilityConfig|section=Coding shape|name=version|type=str | null|notes=no}}
{{Field|model=FacilityConfig|section=Coding shape|name=code|type=str|notes='''yes'''}}
{{Field|model=FacilityConfig|section=Coding shape|name=display|type=str | null|notes=no}}
|}

=== <code>MonetaryComponentDefinition</code> shape ===

Each <code>discount_monetary_components[]</code> entry subclasses <code>MonetaryComponent</code> and adds <code>title</code>. Definition mode overrides or disables the base duplicate-code and amount-or-factor checks, but rejects a <code>base</code>-typed component outright.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=title|type=str|notes='''yes'''}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=monetary_component_type|type=MonetaryComponentType enum|notes='''yes'''}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=code|type=Coding | null|notes=no}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=factor|type=Decimal | null|notes=no}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=amount|type=Decimal | null|notes=no}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=tax_included_amount|type=Decimal | null|notes=no}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=global_component|type=bool|notes=no}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=conditions|type=list[EvaluatorConditionSpec]|notes=no}}
|}

<code>EvaluatorConditionSpec</code> (each <code>conditions[]</code> entry):

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=metric|type=str|notes='''yes'''}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=operation|type=str|notes='''yes'''}}
{{Field|model=FacilityConfig|section=MonetaryComponentDefinition shape|name=value|type=dict | str|notes='''yes'''}}
|}

=== <code>DiscountConfiguration</code> shape ===

The <code>discount_configuration</code> object.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=FacilityConfig|section=DiscountConfiguration shape|name=max_applicable|type=int (ge=0)|notes='''yes'''}}
{{Field|model=FacilityConfig|section=DiscountConfiguration shape|name=applicability_order|type=DiscountApplicability enum|notes='''yes'''}}
|}

== Enum values ==

=== <code>MonetaryComponentType</code> values ===

From <code>care/emr/resources/common/monetary_component.py</code>. String enum.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>base</code>
| Base price (not allowed in a <code>MonetaryComponentDefinition</code>)
|-
| <code>surcharge</code>
| Additional charge
|-
| <code>discount</code>
| Discount line item
|-
| <code>tax</code>
| Tax line item
|-
| <code>informational</code>
| Informational-only component
|}

=== <code>DiscountApplicability</code> values ===

From <code>care/emr/resources/common/monetary_component.py</code>. String enum.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>total_asc</code>
| Apply discounts in ascending order of total
|-
| <code>total_desc</code>
| Apply discounts in descending order of total
|}

== Resource specs (API schema) ==

These Pydantic specs build on [[References/Base models & conventions|<code>EMRResource</code>]] (<code>serialize</code>/<code>de_serialize</code>, the <code>perform_extra_serialization</code>/<code>perform_extra_deserialization</code> hooks, <code>__model__</code>, <code>__exclude__</code>) and define how monetary config is written and read. There is no standard CRUD endpoint for it — writes go through dedicated facility detail actions, and reads come back inside the facility retrieve payload.

{| class="wikitable"
|-
! Spec
! Role
! Bound to
! Notes
|-
| <code>FacilityMonetaryCodeSpec</code>
| write · set monetary config
| <code>FacilityMonetoryConfig</code>
| Validates and persists <code>discount_codes</code>, <code>discount_monetary_components</code>, <code>discount_configuration</code> in one payload. <code>de_serialize</code>d onto the get-or-created config row
|-
| <code>FacilityInvoiceExpressionSpec</code>
| write · set invoice expression
| (plain <code>BaseModel</code>)
| Single field <code>invoice_number_expression</code>; validated by dry-run before save
|-
| <code>FacilityRetrieveSpec</code>
| read · facility detail
| <code>Facility</code>
| Surfaces the facility's monetary config plus instance-level catalogs in <code>perform_extra_serialization</code>
|-
| <code>MonetaryComponentDefinition</code>
| nested (write)
| —
| Shape of each <code>discount_monetary_components[]</code> entry
|-
| <code>DiscountConfiguration</code>
| nested (write)
| —
| Shape of <code>discount_configuration</code>
|-
| <code>Coding</code>
| nested (write)
| —
| Shape of each <code>discount_codes[]</code> entry
|}

=== <code>FacilityMonetaryCodeSpec</code> ===

<code>__model__ = FacilityMonetoryConfig</code>, <code>__exclude__ = []</code>. Write schema for the <code>set_monetary_config</code> action.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=FacilityConfig|section=FacilityMonetaryCodeSpec|name=discount_codes|type=list[Coding]|notes=Facility-defined codes}}
{{Field|model=FacilityConfig|section=FacilityMonetaryCodeSpec|name=discount_monetary_components|type=list[MonetaryComponentDefinition]|notes=Selectable discount definitions}}
{{Field|model=FacilityConfig|section=FacilityMonetaryCodeSpec|name=discount_configuration|type=DiscountConfiguration | null|notes=Stacking rule}}
|}

Model validators run on write:

* '''Count limits''' — <code>discount_codes</code> and <code>discount_monetary_components</code> must each hold fewer than 100 entries (<code>DISCOUNT_CODE_COUNT_LIMIT</code> / <code>DISCOUNT_MONETARY_COMPONENT_COUNT_LIMIT = 100</code>; the check rejects <code>>= 100</code>).
* '''No duplicate codes''' — <code>code</code> values within <code>discount_codes</code> must be unique.
* '''No redefining system codes''' — a facility code may not reuse a <code>[code, system]</code> pair already in instance <code>settings.DISCOUNT_CODES</code>.
* '''All component codes must be defined''' — every <code>discount_monetary_components[i].code</code> (when present) must match a <code>[code, system]</code> pair from either <code>settings.DISCOUNT_CODES</code> (instance) or the facility's <code>discount_codes</code>.

=== <code>FacilityInvoiceExpressionSpec</code> ===

Plain <code>BaseModel</code>, not an <code>EMRResource</code>. Write schema for the <code>set_invoice_expression</code> action.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=FacilityConfig|section=FacilityInvoiceExpressionSpec|name=invoice_number_expression|type=str|notes=Validated via <code>evaluate_invoice_dummy_expression(v)</code>; any exception raises <code>"Invalid Expression"</code>. An empty value skips validation}}
|}

The dry-run context supplies <code>invoice_count=1234</code>, <code>current_year_yyyy=2025</code>, <code>current_year_yy=25</code>. At runtime, <code>evaluate_invoice_identifier_default_expression(facility)</code> evaluates the stored expression against the live invoice count and current year.

=== <code>FacilityRetrieveSpec</code> (read path) ===

<code>FacilityRetrieveSpec</code> (extends <code>FacilityReadSpec</code> + <code>FacilityPermissionsMixin</code>) injects the monetary config into the facility detail response from <code>perform_extra_serialization</code>, calling <code>FacilityMonetoryConfig.get_monetory_config(obj.id)</code> (get-or-create). The monetary-config-derived fields on the read payload:

{| class="wikitable"
|-
! Field
! Source
|-
| <code>invoice_number_expression</code>
| config row
|-
| <code>discount_codes</code>
| config row (<code>list[dict]</code>)
|-
| <code>discount_monetary_components</code>
| config row (<code>list[dict]</code>)
|-
| <code>discount_configuration</code>
| config row (<code>dict | null</code>)
|-
| <code>instance_discount_codes</code>
| <code>settings.DISCOUNT_CODES</code>
|-
| <code>instance_discount_monetary_components</code>
| <code>settings.DISCOUNT_MONETARY_COMPONENT_DEFINITIONS</code>
|-
| <code>instance_tax_codes</code>
| <code>settings.TAX_CODES</code>
|-
| <code>instance_tax_monetary_components</code>
| <code>settings.TAX_MONETARY_COMPONENT_DEFINITIONS</code>
|-
| <code>instance_informational_codes</code>
| <code>settings.INFORMATIONAL_MONETARY_CODES</code>
|-
| <code>flags</code>
| <code>obj.get_facility_flags()</code>
|-
| <code>patient_instance_identifier_configs</code>
| <code>PatientIdentifierConfigCache.get_instance_config()</code>
|-
| <code>patient_facility_identifier_configs</code>
| <code>PatientIdentifierConfigCache.get_facility_config(obj.id)</code>
|}

<blockquote>Facility codes layer on top of instance-level catalogs. The read payload returns both the facility's own <code>discount_*</code> fields and the <code>instance_*</code> settings-derived catalogs, while write-time validation stops a facility from redefining instance codes.
</blockquote>
== API integration ==

Both writes are detail actions on the facility viewset and require update authorization on the facility.

{| class="wikitable"
|-
! Action
! Method
! Request spec
! Behaviour
|-
| <code>set_monetary_config</code>
| <code>POST</code> (detail)
| <code>FacilityMonetaryCodeSpec</code>
| <code>model_validate</code> with context <code>{is_update: True, object: <config>}</code>, then <code>de_serialize</code> onto the get-or-created config, set <code>updated_by</code>, <code>save()</code>. Returns the facility retrieve payload
|-
| <code>set_invoice_expression</code>
| <code>POST</code> (detail)
| <code>FacilityInvoiceExpressionSpec</code>
| Sets <code>invoice_number_expression</code> on the get-or-created config, sets <code>updated_by</code>, <code>save()</code>. Returns the facility retrieve payload
|}

== Invoice number expression ==

<code>invoice_number_expression</code> is a string template evaluated by <code>care.emr.utils.expression_evaluator.evaluate_expression</code>. It can reference:

{| class="wikitable"
|-
! Variable
! Source
|-
| <code>invoice_count</code>
| count of <code>Invoice</code> rows for the facility
|-
| <code>current_year_yyyy</code>
| four-digit current year
|-
| <code>current_year_yy</code>
| two-digit current year (<code>year % 100</code>)
|}

A <code>null</code>/empty expression evaluates to <code>""</code>, producing no number.

== Methods & save behaviour ==

<code>FacilityMonetoryConfig</code> caches derived data in the Django cache and rebuilds it on every write.

=== Cache keys ===

{| class="wikitable"
|-
! Key
! Built by
|-
| <code>facility:{facility_id}:monetory_component</code>
| <code>get_monetory_component_cache_key(facility_id)</code>
|-
| <code>facility:{facility_id}:discount_configuration</code>
| <code>get_discount_configuration_cache_key(facility_id)</code>
|}

=== Class methods ===

* <code>get_monetory_config(facility_id)</code> — returns the facility's config, creating an empty one if none exists. This get-or-create entry point backs both write actions and the retrieve serializer.
* <code>get_component_key(component)</code> — derives a component's lookup key as <code>code.system + "/" + code.code</code>.
* <code>calculate_monetory_components(components)</code> — folds a component list into a dict keyed by <code>get_component_key</code>.
* <code>get_monetory_component(facility_id)</code> — returns the cached component dict, computing it from <code>discount_monetary_components</code> and caching it on a miss.
* <code>get_discount_configuration(facility_id)</code> — returns the cached <code>discount_configuration</code> (default <code>{}</code>), caching it on a miss.

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

<code>save()</code> deletes both cache keys for the facility before calling <code>super().save()</code>. The next call to <code>get_monetory_component()</code> or <code>get_discount_configuration()</code> recomputes from the persisted row, so the cache invalidates on write and rebuilds lazily on the next read.

== API integration notes ==

* One config exists per facility. Read or auto-create it through <code>get_monetory_config(facility_id)</code> rather than querying the table directly — the <code>set_monetary_config</code> / <code>set_invoice_expression</code> actions and <code>FacilityRetrieveSpec</code> all route through this get-or-create.
* <code>discount_codes</code>, <code>discount_monetary_components</code>, and <code>discount_configuration</code> are opaque <code>JSONField</code>s at the DB layer; their shape and validation come from <code>FacilityMonetaryCodeSpec</code> and the nested <code>Coding</code> / <code>MonetaryComponentDefinition</code> / <code>DiscountConfiguration</code> specs.
* Monetary components are keyed by a FHIR-style <code>code.system</code>/<code>code.code</code> pair (<code>get_component_key</code>); match on that derived key.
* <code>get_monetory_component()</code> / <code>get_discount_configuration()</code> results are cache-backed and platform-maintained. Don't write to the cache keys directly — write the model and let <code>save()</code> invalidate them.

{{Related}}

References/Facility Config - Revision history

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

Admin: OHC identity seed