SAIF.Business.Provider operations and processes

This page is the operation catalog and cross-operation hub for SAIF.Business.Provider. The library exposes fourteen operations covering the provider aggregate (a header plus lazily loaded location and tax ID collections), a multi-criteria provider search, per-attribute maintenance of everything hanging off a provider location (address, contact, identity, tax ID, relationship, MCO membership, service/contract, ineligibility period, DCBS cost/charge, notes), read-only external API calls to ClaimCenter, and the cached provider reference/code data used throughout. 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
Retrieve provider aggregate	Load a provider header and expose its lazily loaded location and tax ID collections	clsProvider.GetProvider(dpi, providerSeqNum)	ProviderSeqNum, IDataPortalInfo	Populated clsProvider with cached Locations/TaxIds collections	—	PROVIDER, PROVIDER_LOCATION, PROVIDER_TAX_ID	SQL-018, SQL-042, SQL-066, SQL-088
Search providers	Run a multi-criteria, dynamically assembled search across location, address, tax, identity, service, and MCO data	Caller populates clsSearchCriteria and calls searchForProvider()	ProviderName, TaxId, OtherId, ProviderType, ServiceType, MCOName, address/phone fields	clsProviders collection capped at 300 rows	BR-001, BR-002	PROVIDER_LOCATION, PROVIDER_ADDRESS, PROVIDER_TAX_ID	—
Maintain provider location	Create, update, and delete a provider's practice location and sync identity to Contact Manager	Caller edits clsProviderLocation and calls Save()/Delete()	ProviderTypeCode, business/individual identity, contact numbers, approval/primary/eligibility flags	Persisted location row; Contact Manager ContactDto sync	BR-003, BR-004, BR-005, BR-006	PROVIDER_LOCATION	SQL-028, SQL-053, SQL-076, SQL-098
Maintain provider address	Persist provider address records with date-overlap validation and USPS normalization	Caller edits clsProviderAddress and calls Save()/Delete()	Address type, dates, lines, city/state/zip/country, ForeignAddressFlag	Persisted address row; standardized content; Contact Manager AddressDto sync	BR-007, BR-008, BR-026	PROVIDER_ADDRESS	SQL-019, SQL-043, SQL-067, SQL-089
Maintain provider contact	Persist named contact records requiring a type and a communication path	Caller edits clsProviderContact and calls Save()/Delete()	ProviderContactCode, Name, EmailAddress, PhoneNumber	Persisted contact row	BR-009	PROVIDER_CONTACT	SQL-021, SQL-045, SQL-069, SQL-091
Maintain provider identity	Persist alternate provider identifiers, including NPI validation, and sync to Contact Manager	Caller edits clsProviderIdentity and calls Save()/Delete()	ProviderIdentityCode, IdentityValue, IdentityName	Persisted identity row; Contact Manager IdentifierDto sync	BR-010	PROVIDER_IDENTITY	SQL-024, SQL-048, SQL-072, SQL-094
Maintain provider tax ID and sync TIN contact	Persist provider tax IDs, enforce format/uniqueness/immutability, and sync the primary TIN to Contact Manager	Caller edits clsProviderTaxID and calls Save()/Delete()	TaxID, RegisteredName, W9 dates, address fields, PrimaryTaxIDFlag	Persisted tax ID row; Contact Manager TaxDto sync for the primary TIN	BR-011, BR-012, BR-025	PROVIDER_TAX_ID, PROVIDER	SQL-036, SQL-060, SQL-084, SQL-106
Maintain provider relationship	Persist provider-to-provider relationships, block invalid/overlapping links, and protect in-use relationships from deletion	Caller edits clsProviderRelationship and calls Save()/Delete()	Child/parent ProviderLocationSeqNum, ProviderRelationshipCode, EffDate/ExpDate	Persisted relationship row; Contact Manager sync for "WRK" relationships	BR-013, BR-014, BR-024	PROVIDER_RELATIONSHIP, PROVIDER_LOCATION	SQL-030, SQL-055, SQL-078, SQL-100
Maintain provider MCO membership	Persist MCO membership periods and rates, bounded by the plan's active dates and any effective service contract	Caller edits clsProviderMCOMembership and calls Save()/Delete()	MCOPlanID, EffDate/ExpDate, admin fee flag/rate, specialty rates	Persisted membership row; Contact Manager MembershipDto sync	BR-016, BR-017, BR-018	MCO_PROVIDER, MCO_PLAN, PROVIDER_SERVICE_CONTRACT	SQL-029, SQL-054, SQL-077, SQL-099
Maintain provider service and service contract	Persist a provider location's offered services, service-type reference links, and pricing/contract terms	Caller edits clsProviderService/clsProviderServiceContract/clsProviderServiceType and calls Save()/Delete()	ProviderServiceCode, PrimaryServiceFlag, contract pricing fields, ServiceTypeCode/CBPServiceCode, MCOPlanID	Persisted service, contract, and service-type rows	BR-019, BR-020, BR-021	PROVIDER_SERVICE, PROVIDER_SERVICE_CONTRACT, PROVIDER_SERVICE_TYPE	SQL-032, SQL-034, SQL-035, SQL-080, SQL-082, SQL-083
Maintain provider location periods	Persist provider ineligibility periods and DCBS cost/charge factors, each bounded by its own date and value rules	Caller edits clsProviderIneligibilityPeriod/clsProviderDcbsCostCharge and calls Save()/Delete()	IneligibilityReasonCode, StartDate/TerminationDate; EffDate/ExpDate, CostChargeFactor	Persisted ineligibility period and DCBS cost/charge rows	BR-022, BR-023	PROVIDER_INELIG_PERIOD, PROVIDER_DCBS_COST_CHARGE	SQL-026, SQL-023, SQL-074, SQL-071
Maintain provider notes	Persist note records attached to provider, location, bill, or claim data	Caller edits clsNote and calls Save()/Delete()	NoteTypeCode, NoteCategoryCode, ActiveFlag, optional foreign keys, NoteTxt	Persisted note row	BR-015	CBP_NOTE	SQL-017, SQL-041, SQL-065, SQL-087
Retrieve ClaimCenter payment history	Call the ClaimCenter API to retrieve payment history for a provider tax ID	Caller invokes clsPaymentApi.GetPayments(dpi, taxId, ...)	TaxId, result-limit and inclusion flags	PaymentList payload; HasPayments flag	None catalogued	—	—
Provider reference data lookups	Resolve cached code/reference lists used to validate and display provider domain values	Any read of a provider code table or resolution of a code description during another operation	Code value, optional effective date	Code description; derived boolean flags	None catalogued	PROVIDER_TYPE_CODE, PROVIDER_ADDRESS_CODE, PROVIDER_CONTACT_CODE, PROVIDER_IDENTITY_CODE, PROVIDER_INELIG_REASON_CD, PROVIDER_RELATIONSHIP_CODE, PROVIDER_SERVICE_CODE, CBP_SERVICE_CODE, MCO_PLAN	SQL-015, SQL-037, SQL-061, SQL-038, SQL-016

Process flow diagram

The following diagram shows how the fourteen operations relate: a provider is retrieved or searched for, its location and everything hanging off that location is maintained through independent per-attribute operations that share the same validate/persist/sync pattern, and two operations (payment history, reference data) sit outside the persistence pipeline as read-only lookups.

flowchart TD
    Start([Caller requests provider data]) --> Retrieve[Retrieve provider aggregate]
    Start --> Search[Search providers]
    Retrieve --> Location[Maintain provider location]
    Location --> Address[Maintain provider address]
    Location --> Contact[Maintain provider contact]
    Location --> Identity[Maintain provider identity]
    Location --> Relationship[Maintain provider relationship]
    Location --> MCO[Maintain provider MCO membership]
    Location --> Service[Maintain provider service and contract]
    Location --> Periods[Maintain provider location periods]
    Retrieve --> TaxID[Maintain provider tax ID<br>and sync TIN contact]
    Location --> Notes[Maintain provider notes]
    TaxID --> Payments[Retrieve ClaimCenter<br>payment history]
    Address --> Reference[Provider reference data lookups]
    Identity --> Reference
    Service --> Reference
    MCO --> Reference
    Location --> Edit[Caller edits properties]
    Address --> Edit
    Contact --> Edit
    Identity --> Edit
    Relationship --> Edit
    MCO --> Edit
    Service --> Edit
    Periods --> Edit
    TaxID --> Edit
    Notes --> Edit
    Edit --> Validate{Business rules pass?}
    Validate -->|No| Errors([Broken rules returned;<br>changes retained in memory])
    Validate -->|Yes| Persist[Insert/update/delete via BOF data portal]
    Persist --> Concurrency{RowsAffected = 1?}
    Concurrency -->|Yes| Sync{External API sync required?}
    Concurrency -->|No| Contention([DB contention/insert error added])
    Sync -->|Yes| Api[Send Contact Manager request]
    Sync -->|No| Done([Changes persisted])
    Api --> Done

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
Retrieve provider aggregate	SQL-042, SQL-053, SQL-060	PROVIDER, PROVIDER_LOCATION, PROVIDER_TAX_ID	Read / Write
Search providers	— (dynamic SqlHelper.ResultSetQuery)	PROVIDER_LOCATION, PROVIDER_ADDRESS, PROVIDER_TAX_ID	Read
Maintain provider location	SQL-028, SQL-076, SQL-098	PROVIDER_LOCATION	Write
Maintain provider address	SQL-019, SQL-067, SQL-089	PROVIDER_ADDRESS	Write
Maintain provider contact	SQL-021, SQL-069, SQL-091	PROVIDER_CONTACT	Write
Maintain provider identity	SQL-024, SQL-072, SQL-094	PROVIDER_IDENTITY	Write
Maintain provider tax ID and sync TIN contact	SQL-036, SQL-084, SQL-106	PROVIDER_TAX_ID, PROVIDER	Write
Maintain provider relationship	SQL-030, SQL-078, SQL-100	PROVIDER_RELATIONSHIP, PROVIDER_LOCATION	Write
Maintain provider MCO membership	SQL-029, SQL-077, SQL-099	MCO_PROVIDER, PROVIDER_SERVICE_CONTRACT	Write
Maintain provider service and service contract	SQL-032, SQL-034, SQL-035	PROVIDER_SERVICE, PROVIDER_SERVICE_CONTRACT, PROVIDER_SERVICE_TYPE	Write
Maintain provider location periods	SQL-026, SQL-023	PROVIDER_INELIG_PERIOD, PROVIDER_DCBS_COST_CHARGE	Write
Maintain provider notes	SQL-017, SQL-065, SQL-087	CBP_NOTE	Write
Retrieve ClaimCenter payment history	—	—	Read (external REST call only)
Provider reference data lookups	SQL-061, SQL-038, SQL-040	PROVIDER_TYPE_CODE, CBP_SERVICE_CODE, MCO_PLAN	Read / Write (code table CRUD)

Failure and edge-case behavior

• Optimistic concurrency is the dominant failure mode: nearly every persisting operation checks the affected row count and adds a DB contention error instead of throwing; several delete paths (location, tax ID, service contract, relationship, MCO membership, ineligibility period, DCBS cost/charge) omit the UPDATE_NUM check that their update paths enforce. Detailed per-operation behavior is documented on each operation page.
• External API synchronization (Contact Manager for location/address/contact/identity/tax ID/relationship/MCO membership; ClaimCenter for payment history) is best-effort*: a failed API call is logged and surfaced as an error message on the business object, but the underlying database change is never rolled back, so a provider record can end up temporarily out of sync with the external system.
• Retrieve paths generally return an unpopulated object when no row matches, rather than raising a not-found error; callers must check the populated state themselves.
• Search providers silently truncates result sets beyond 300 rows with no warning surfaced to the caller.
• Maintain provider location performs no in-use protection (payment, audit, or note history) before allowing a delete, unlike Maintain provider relationship, which blocks deletion of an in-use relationship.

Related documentation

• Index
• Overview
• Architecture
• Dependencies
• Business rules
• Database tables
• SQL catalog
• API reference
• Configuration

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.Provider\clsProvider.vb
• Business\SAIF.Business.Provider\clsProviderSearch.vb
• Business\SAIF.Business.Provider\clsProviderLocation.vb
• Business\SAIF.Business.Provider\clsProviderAddress.vb
• Business\SAIF.Business.Provider\clsProviderContact.vb
• Business\SAIF.Business.Provider\clsProviderIdentity.vb
• Business\SAIF.Business.Provider\clsProviderTaxID.vb
• Business\SAIF.Business.Provider\clsProviderRelationship.vb
• Business\SAIF.Business.Provider\clsProviderMCOMembership.vb
• Business\SAIF.Business.Provider\clsProviderService.vb
• Business\SAIF.Business.Provider\clsProviderServiceContract.vb
• Business\SAIF.Business.Provider\clsProviderIneligibilityPeriod.vb
• Business\SAIF.Business.Provider\clsProviderDcbsCostCharge.vb
• Business\SAIF.Business.Provider\clsNote.vb
• Business\SAIF.Business.Provider\Api\clsPaymentApi.vb
• Business\SAIF.Business.Provider\Api\clsTaxApi.vb