--- title: SAIF.Business.Claim.MedicalBill operations and processes summary: Operation catalog and cross-operation hub for the medical-bill business objects. status: draft owner: SAIF Doc Gen last_reviewed: 2026-07-30 library: SAIF.Business.Claim.MedicalBill reference_type: package --- # SAIF.Business.Claim.MedicalBill operations and processes This page is the operation catalog and cross-operation hub for `SAIF.Business.Claim.MedicalBill`. The library exposes six operations covering API-based medical bill retrieval (with confidentiality masking and pending-bill suppression), search-criteria validation, stored-procedure-based audit service/adjustment retrieval, EOB note retrieval, direct-SQL adjustment-code reference lookup, and full CRUD for national drug pricing data. Each operation's detailed, step-by-step logic lives in its own page under `operations/`. ## Operation catalog | Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL | | --- | --- | --- | --- | --- | --- | --- | --- | | [Medical bill retrieval](operations/medical-bill-retrieval.md) | Load a single bill or a security-aware collection of bills through the medical billing API | `clsMedicalBill.GetMedicalBill(billID)`; `clsMedicalBillCollection.GetMedicalBills(searchCriteria[, security])` | `billID`, or `MedicalBillSearchRequest` and `clsSecurityPrincipal` | Populated bill(s); print link; masked/unmasked worker name; suppressed/computed pending-bill total | [BR-MB-001](business-rules.md#br-mb-001-exposure-claims-require-exposureclaim-ad-resource-authorization), [BR-MB-002](business-rules.md#br-mb-002-collateral-health-claims-require-collateralhealthclaim-ad-resource-authorization), [BR-MB-003](business-rules.md#br-mb-003-saif-employee-status-affects-data-visibility), [BR-MB-019](business-rules.md#br-mb-019-pending-bill-payment-totals-are-suppressed-during-a-medical-bill-search), [BR-MB-020](business-rules.md#br-mb-020-audit-and-eob-detail-retrieval-is-suppressed-for-bulk-print-views), [BR-MB-021](business-rules.md#br-mb-021-worker-name-is-masked-for-confidential-claims) | None (API-based) | None (API-based) | | [Bill search criteria validation](operations/bill-search-criteria-validation.md) | Validate a medical bill search request before it is submitted for retrieval | Caller reads `clsBillSearchCriteria.IsValid` (or a bound `IDataErrorInfo` property) | Claim/provider/worker/date/identifier search fields | Boolean validity; broken-rule error messages; resolved `ProviderID` | [BR-MB-005](business-rules.md#br-mb-005-bill-search-claim-number-must-resolve-to-a-valid-saif-claim), [BR-MB-006](business-rules.md#br-mb-006-bill-search-provider-location-must-be-valid-when-entered), [BR-MB-007](business-rules.md#br-mb-007-bill-search-worker-last-name-is-required-when-a-first-name-is-entered), [BR-MB-008](business-rules.md#br-mb-008-bill-search-service-begin-and-end-dates-must-both-be-entered-together), [BR-MB-009](business-rules.md#br-mb-009-bill-search-service-begin-date-may-not-be-in-the-future), [BR-MB-010](business-rules.md#br-mb-010-bill-search-service-end-date-may-not-precede-the-begin-date), [BR-MB-011](business-rules.md#br-mb-011-bill-search-date-range-may-not-exceed-six-months-unless-an-identifier-is-given), [BR-MB-012](business-rules.md#br-mb-012-bill-search-service-end-date-may-not-be-in-the-future), [BR-MB-013](business-rules.md#br-mb-013-bill-search-worker-birth-date-may-not-be-in-the-future), [BR-MB-014](business-rules.md#br-mb-014-internal-bill-search-requires-a-claim-number-bill-number-or-provider-number), [BR-MB-015](business-rules.md#br-mb-015-bill-search-by-check-number-requires-a-provider-number), [BR-MB-016](business-rules.md#br-mb-016-bill-search-starts-with-option-requires-at-least-three-characters), [BR-MB-017](business-rules.md#br-mb-017-medical-bill-search-requires-exactly-one-of-worker-id-or-provider-location) | None (in-memory validation) | None (in-memory validation) | | [Audit service and adjustment retrieval](operations/audit-service-and-adjustment-retrieval.md) | Load audited service lines for a bill and the adjustments applied to each service | `clsMedicalBill.AuditServices` (lazy); `clsAuditService.ServiceAdjustments` (lazy) | `BillID`; `AuditSeqNum` and `BillID` | Populated audit-service and service-adjustment collections; `IsIMEService` flag; resolved adjustment descriptions | [BR-PROC-001](business-rules.md#br-proc-001-service-adjustments-are-sorted-so-code-ft-appears-first-pa-appears-last-and-all-othe), [BR-PROC-002](business-rules.md#br-proc-002-service-descriptions-prefer-bill-service-description-text-and-fall-back-to-generic-drug-na), [BR-MB-020](business-rules.md#br-mb-020-audit-and-eob-detail-retrieval-is-suppressed-for-bulk-print-views) | [CBP_AUDITED_SERVICE](database-tables.md#cbp_audited_service), [CBP_SERVICE_DESCRIPTION](database-tables.md#cbp_service_description), [CBP_NATIONAL_DRUG](database-tables.md#cbp_national_drug), [CBP_AUDITED_SERVICE_ADJUSTMENT](database-tables.md#cbp_audited_service_adjustment) | [SQL-006](sql/SQL-006.md), [SQL-013](sql/SQL-013.md) | | [EOB note retrieval](operations/eob-note-retrieval.md) | Load explanation-of-benefits notes recorded against a bill | `clsMedicalBill.EOBNotes` (lazy) | `BillID` | Populated EOB note collection scoped to the bill | [BR-PROC-003](business-rules.md#br-proc-003-eob-note-retrieval-is-always-restricted-to-the-requested-bill-identifier), [BR-MB-020](business-rules.md#br-mb-020-audit-and-eob-detail-retrieval-is-suppressed-for-bulk-print-views) | [CBP_EOB_NOTE](database-tables.md#cbp_eob_note) | [SQL-007](sql/SQL-007.md) | | [Adjustment code lookup](operations/adjustment-code-lookup.md) | Resolve audit adjustment type reference data by code or in full | `clsAdjustmentCode.GetAdjustmentCode(code)`; `clsAdjustmentCodeCollection.GetCodes()` | `code`, or none | Populated single code or full reference collection | None catalogued* | [CBP_AUDIT_ADJUSTMENT_TYPE](database-tables.md#cbp_audit_adjustment_type) | [SQL-004](sql/SQL-004.md), [SQL-005](sql/SQL-005.md) | | [Drug pricing data management](operations/drug-pricing-data-management.md) | CRUD for national drug reference records, effective-dated prices, and price-history archival | `clsNationalDrug.NewCbpNationalDrug`/`GetNationalDrug`/`Save()`; `clsNdcPriceHistory.NewNdcPriceHistory`/`GetNdcPriceHistory` | National drug code and fields; price effective/expiration dates and amounts | Persisted drug and price rows; inserted history rows; resolved `ActivePrice` | [BR-MB-004](business-rules.md#br-mb-004-optimistic-concurrency-on-all-crud-operations), [BR-MB-018](business-rules.md#br-mb-018-active-drug-price-selection-prefers-an-unexpired-row-falling-back-to-the-most-recent-effective-date) | [CBP_NATIONAL_DRUG](database-tables.md#cbp_national_drug), [CBP_NATIONAL_DRUG_PRICE](database-tables.md#cbp_national_drug_price), [CBP_NDC_PRICE_HISTORY](database-tables.md#cbp_ndc_price_history) | [SQL-001](sql/SQL-001.md), [SQL-002](sql/SQL-002.md), [SQL-003](sql/SQL-003.md), [SQL-008](sql/SQL-008.md), [SQL-009](sql/SQL-009.md), [SQL-010](sql/SQL-010.md), [SQL-011](sql/SQL-011.md), [SQL-012](sql/SQL-012.md), [SQL-014](sql/SQL-014.md), [SQL-015](sql/SQL-015.md), [SQL-016](sql/SQL-016.md) | ## Process flow diagram The following diagram shows how the six operations relate: a bill search is validated, submitted, and retrieved through the API; each returned bill lazily loads audit services (with their own child adjustments), EOB notes, and adjustment-code descriptions from Oracle; drug pricing data is managed independently as reference/CRUD data. ```mermaid flowchart TD Start([Caller wants medical bill data]) --> Validate{Search or direct ID?} Validate -->|Search| Criteria[Bill search criteria validation] Criteria --> Valid{IsValid?} Valid -->|No| Errors([Broken rules returned;
search not submitted]) Valid -->|Yes| Retrieve[Medical bill retrieval:
API search] Validate -->|Direct ID| RetrieveSingle[Medical bill retrieval:
API single-bill route] Retrieve --> Bills[Populated bill collection] RetrieveSingle --> Bills Bills --> Mask[WorkerName masking,
TotalPaidAmt suppression on read] Mask --> Detail{SuppressAuditDetail?} Detail -->|Yes| Suppressed([Audit/EOB detail skipped]) Detail -->|No| Audit[Audit service and
adjustment retrieval] Detail -->|No| EOB[EOB note retrieval] Audit --> CodeLookup[Adjustment code lookup] EOB --> Done([Bill data fully populated]) CodeLookup --> Done Drug([Drug pricing data management
maintained independently]) ``` ## Database interactions The following table summarizes which operations read from or write to the database. Per-step SQL and table citations live in each operation's detail page under `operations/`. | Operation | SQL | Tables | Type | | --- | --- | --- | --- | | [Medical bill retrieval](operations/medical-bill-retrieval.md) | None (API-based) | None (API-based) | Read (external API) | | [Bill search criteria validation](operations/bill-search-criteria-validation.md) | None (in-memory validation) | None (in-memory validation) | N/A | | [Audit service and adjustment retrieval](operations/audit-service-and-adjustment-retrieval.md) | [SQL-006](sql/SQL-006.md), [SQL-013](sql/SQL-013.md) | [CBP_AUDITED_SERVICE](database-tables.md#cbp_audited_service), [CBP_SERVICE_DESCRIPTION](database-tables.md#cbp_service_description), [CBP_NATIONAL_DRUG](database-tables.md#cbp_national_drug), [CBP_AUDITED_SERVICE_ADJUSTMENT](database-tables.md#cbp_audited_service_adjustment) | Read (stored procedure) | | [EOB note retrieval](operations/eob-note-retrieval.md) | [SQL-007](sql/SQL-007.md) | [CBP_EOB_NOTE](database-tables.md#cbp_eob_note) | Read (stored procedure) | | [Adjustment code lookup](operations/adjustment-code-lookup.md) | [SQL-004](sql/SQL-004.md), [SQL-005](sql/SQL-005.md) | [CBP_AUDIT_ADJUSTMENT_TYPE](database-tables.md#cbp_audit_adjustment_type) | Read | | [Drug pricing data management](operations/drug-pricing-data-management.md) | [SQL-001](sql/SQL-001.md), [SQL-002](sql/SQL-002.md), [SQL-003](sql/SQL-003.md), [SQL-008](sql/SQL-008.md), [SQL-009](sql/SQL-009.md), [SQL-010](sql/SQL-010.md), [SQL-011](sql/SQL-011.md), [SQL-012](sql/SQL-012.md), [SQL-014](sql/SQL-014.md), [SQL-015](sql/SQL-015.md), [SQL-016](sql/SQL-016.md) | [CBP_NATIONAL_DRUG](database-tables.md#cbp_national_drug), [CBP_NATIONAL_DRUG_PRICE](database-tables.md#cbp_national_drug_price), [CBP_NDC_PRICE_HISTORY](database-tables.md#cbp_ndc_price_history) | Read / Write | ## Stored procedure operations Operations implemented in Oracle stored procedures referenced by this library. | Operation | Description | Source | Link | | --- | --- | --- | --- | | Retrieve audit services | Returns audited bill service lines with effective-dated description enrichment. | `PK82396_MEDICAL_BILLS.GetAuditServices` | [Details](procedures/pk82396_medical_bills.md#getauditservices) | | Retrieve service adjustments | Returns audited service adjustment rows for one bill/audit sequence pair. | `PK82396_MEDICAL_BILLS.GetServiceAdjustments` | [Details](procedures/pk82396_medical_bills.md#getserviceadjustments) | | Retrieve EOB notes | Returns explanation-of-benefits note rows for one bill. | `PK82396_MEDICAL_BILLS.GetEOBNotes` | [Details](procedures/pk82396_medical_bills.md#geteobnotes) | ## Failure and edge-case behavior - Medical bill retrieval depends on an external medical billing API rather than direct SQL; a missing bill row is returned as an unfilled object rather than an explicit not-found error, and the `IsMedicalBillSearch`-only collection overload silently returns `Nothing` for non-medical-bill-search criteria. - Bill search criteria validation makes live claim-security and provider-location lookups as part of rule evaluation, so repeated validation during interactive data entry issues repeated dependency calls rather than caching results.* - `SuppressAuditDetail`, set at the bill or collection level, uniformly skips audit-service, service-adjustment, EOB-note, and adjustment-description retrieval for affected bills, which is used to avoid per-bill round trips during bulk print report generation. - All drug-pricing CRUD paths (`clsNationalDrug`, `clsNationalDrugPrice`, `clsNdcPriceHistory`) rely on optimistic-concurrency rows-affected checks; a value other than `1` adds an error message rather than throwing. - Price-history archival (`clsNdcPriceHistory.NewNdcPriceHistory`) is not automatically triggered by deleting or overwriting a `clsNationalDrugPrice` row; it must be invoked explicitly by the caller.* ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Architecture](architecture.md) - [Dependencies](dependencies.md) - [Business rules](business-rules.md) - [Database tables](database-tables.md) - [SQL catalog](sql/index.md) - [Procedures](procedures/index.md) - [Security and authorization](security-authorization.md) - [API reference](api/index.md) > **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.MedicalBill\clsMedicalBill.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsMedicalBillCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsBillSearchCriteria.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsAuditServiceCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsAuditService.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsServiceAdjustmentCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsServiceAdjustment.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsEOBNoteCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsEOBNote.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsAdjustmentCode.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsAdjustmentCodeCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrug.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrugPrice.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrugPriceCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNdcPriceHistory.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNdcPriceHistoryCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\clsNationalDrugCollection.vb` - `Business\SAIF.Business.Claim.MedicalBill\MedicalBillSearchRequest.vb` - `Business\SAIF.Business.Claim.MedicalBill\MedicalBillResult.vb`