Skip to content

Attending physician retrieval

Attending physician retrieval is the only operation in this library that sources its data from an external REST service rather than the database. The collection factory configures a route to the claim-contacts endpoint, deserializes the returned contact list, and maps each contact into a read-only physician object. The one database read in this operation is a lazily cached lookup of termination reason codes, used to turn a stored code into display text. The collection cannot be saved.

Field Value
Operation ID OP-CM-12
Trigger Caller invokes clsAttendingPhysicianCollection.GetAttendingPhysicians(inDataportal, inClaimID); separately, any read of a physician's termination reason or the termination-reason list triggers the code lookup*
Inputs Data-portal info (session and portal context) and ClaimID (Decimal)
Outputs A populated collection of attending-physician objects, one per contact returned as an attending physician, each carrying termination reason code, start date, termination date, provider location identifier, and claim identifier; the resolved termination reason text
Primary components clsAttendingPhysicianCollection (GetAttendingPhysicians, Criteria.ConfigureRoutes, BeforeRetrieve, AfterRetrieve, AlternateCareProviders), clsAttendingPhysician (Load, Fill, GetTerminationReasonCodes, IsAlternateCareProvider, GetAlternateProviderTreatmentDaysRemaining)
Entry point Business\SAIF.Business.Claim.Maintenance\clsAttendingPhysicianCollection.vb

Steps

  1. Request the physicians for a claim. GetAttendingPhysicians(inDataportal, inClaimID) constructs a criteria carrying the portal info and claim identifier, calls the API data-access layer's retrieve, and casts the result to the physician collection.
  2. Configure the REST route. The criteria's route configuration resolves the claim-data API client and general claim-data controller and registers a retrieve route whose pattern targets the claim-contacts endpoint with the claim identifier as its parameter. No SQL is involved.
  3. Bind the claim identifier. BeforeRetrieve formats the registered route with the criteria's claim identifier.
  4. Call the external service. The API access layer issues the outbound HTTP GET to the claim-contacts endpoint and receives a JSON response.*
  5. Deserialize the response. AfterRetrieve deserializes the response envelope and reads the attending-physician list nested inside the claim-contacts response data.
  6. Map each contact. When the list is present and non-empty, iterate the contacts; for each, create a physician object, assign the cached claim data, and call Load with the portal info, the contact, and the claim identifier.
  7. Sub-step: assigning the claim data lazily retrieves the claim record if it is not already cached, which is the only claim-side database access in this flow.

Origin: clsClaimData.GetData is implemented in SAIF.Business.Claim and executed on behalf of this operation. That library is documented in the previous format, so no per-operation page exists; see Operations and processes in the SAIF.Business.Claim documentation set. 7. Fill the physician object. Load initializes the update info from the current user if needed, then Fill maps the contact's termination reason, valid-from date, valid-to date, provider location sequence number, and the claim identifier into the business object — a pure field mapping with no SQL. 8. Mark the object persisted. Load assigns a criteria keyed by the physician identifier and calls MarkOld(), flagging the object as previously persisted. 9. Build the collection. Each populated physician is appended to the collection, and once every contact is processed the populated collection is returned. 10. Resolve termination reasons on demand. Any read of a physician's termination reason or the termination-reason list calls the shared code lookup. On the first call per application domain it builds a request whose inline text selects the code and description from the reason-code table ordered by description, executes it, and loads the rows into a dictionary keyed by code (SQL-028, ATTENDING_PHYS_EXP_REASON_CODE). Later calls reuse the cached dictionary and perform no further SQL. 11. Classify the provider. The alternate-care and typical-provider tests compare the physician's provider-location provider type against fixed code lists, triggering a lazy provider-location retrieval when that data is not already cached.* - Sub-step: the provider-location retrieval resolves the provider location and its provider type used by both classification tests.

> **Origin**: `clsProviderLocation.GetProviderLocation` is implemented in `SAIF.BOF.Business.View.Provider` and executed on behalf of this operation. That library is documented in the previous format, so no per-operation page exists; see [Operations and processes](../../saif-business-view-provider/operations-processes.md) in the `SAIF.BOF.Business.View.Provider` documentation set.
  1. Compute remaining alternate-care treatment days. Reading the treatment-days-remaining value on an alternate-care provider subtracts the span between the earliest start date and the latest end date across the collection's alternate care providers from a sixty-day window, floored at zero — a purely in-memory calculation over already-retrieved members.*

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([GetAttendingPhysicians claimID]) --> Route[Criteria configures the<br>claim contacts REST route]
    Route --> Bind[BeforeRetrieve formats<br>the route with the claim id]
    Bind --> Http[API layer issues HTTP GET<br>to the claim contacts endpoint]
    Http --> Parse[AfterRetrieve deserializes<br>the response envelope]
    Parse --> Any{Attending physician<br>list present and non-empty?}
    Any -->|No| Empty([Empty collection returned;<br>no exception raised])
    Any -->|Yes| Loop[For each contact: create object,<br>assign claim data, Load and Fill]
    Loop --> Old[Assign criteria; MarkOld]
    Old --> Ret([Populated collection returned])
    Ret --> Use{Consumer request}
    Use -->|Termination reason| Cache{Reason cache populated?}
    Cache -->|No| Sql[Read reason codes<br>from the code table]
    Cache -->|Yes| Lookup[Look the code up<br>in the cached dictionary]
    Sql --> Lookup
    Lookup --> Text([Reason text, or empty<br>when the code is unknown])
    Use -->|Provider classification| Prov[Lazily resolve provider location<br>and compare provider type codes]
    Prov --> Days[Compute alternate care<br>treatment days remaining]
    Days --> Val([Value floored at zero])
    Use -->|Save| Save([Save always returns false;<br>collection is read only])

Failure and edge-case behavior

  • If the response data, the attending-physicians wrapper, or the physician list is absent, or the list is empty, the mapping loop is skipped entirely and an empty but non-null collection is returned; no exception is raised for a claim with no attending physicians.
  • The collection's save is hard-coded to return false: this is a read-only, retrieve-only projection of the external claim-contacts service and cannot be persisted back through this class.
  • The single-item physician factory marks the retrieved object read-only, and its own route configuration registers no route, so single-item retrieval by identifier is not wired to a live service call in this version of the code; collection-level retrieval is the functioning path.*
  • The termination reason resolves to an empty string when the stored code is not a key in the cached list — for example an unrecognized or blank code — rather than throwing.
  • The reason-code dictionary is cached in a shared variable, so changes to the underlying code table are not reflected until the process restarts.*
  • A physician with no termination date is always treated as currently active, because an empty termination date satisfies the active test.
  • The qualifying-termination-reason filter restricts qualifying reasons to a fixed set of four codes; physicians terminated with any other code are silently excluded from whatever downstream logic consumes that filter.
  • The alternate-care treatment-days calculation returns zero both when the physician is not an alternate care provider and when the computed remaining days would be negative, so the two cases cannot be distinguished from the returned value alone.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Business\SAIF.Business.Claim.Maintenance\clsAttendingPhysicianCollection.vb
  • Business\SAIF.Business.Claim.Maintenance\clsAttendingPhysician.vb