SAIF.Business.CustomerContact operations and processes

This page is the operation catalog and cross-operation hub for SAIF.Business.CustomerContact. The library exposes eleven operations covering combined customer/contact search, root customer and contact CRUD with cascading child persistence, customer-contact relationship maintenance, the standalone address/email/phone info-item types and their link rows, long-form note persistence, resolution of external agency/agent/provider and other source-system identifiers into local customer records, and the helper factories/code-map lookups that support those resolution flows. 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
Customer/contact search	Validate a combined search request and return contact and customer matches within the configured limit	Caller populates a SearchRequest and calls clsCustomerContactSearch.Search	SearchRequest criteria, split ratio, result limit	SearchResult containing customer/contact matches	BR-001, BR-002	PERSON, COMPANY, COMPANY_PERSON	SQL-031, SQL-037
Customer CRUD with child persistence	Create, retrieve, update, and delete root customer rows and coordinate child saves	clsCustomer.GetCustomer/NewCustomer followed by property edits and Save()	clsCustomer state plus child address/email/phone/note/relationship collections	Persisted COMPANY row; synchronized child BOF state	BR-009	COMPANY	SQL-008, SQL-035, SQL-068, SQL-082
Contact CRUD with child persistence	Create, retrieve, update, and delete root contact rows and coordinate child saves	clsContact.GetContact/NewContact followed by property edits and Save()	clsContact state plus child address/email/phone/note collections	Persisted PERSON row; synchronized child BOF state	BR-003, BR-009	PERSON	SQL-003, SQL-028, SQL-029, SQL-066, SQL-077
Customer-contact relationship CRUD	Persist customer-to-contact relationship rows independently from the root contact record	clsCustomerContact property edits and Save(), or a related-customer/contact lookup call	clsCustomerContact state or related-customer lookup request	Persisted or retrieved COMPANY_PERSON relationship rows	BR-004	COMPANY_PERSON, COMPANY, PERSON	SQL-010, SQL-028, SQL-038, SQL-069, SQL-084
Address info CRUD and linking	Persist standalone address rows and maintain their customer/contact link rows	Caller adds/edits/removes a clsAddressInfo in a customer's or contact's Addresses collection and the parent saves	Address fields, owning customer/contact ID, connected-phone linkage	Persisted ADDRESS row; persisted or removed COMPANY_ADDRESS/PERSON_ADDRESS link row	BR-005	ADDRESS, COMPANY_ADDRESS, COMPANY_ADDRESS_PHONE, PERSON_ADDRESS, PERSON_ADDRESS_PHONE	SQL-001, SQL-002, SQL-004, SQL-009, SQL-030, SQL-036, SQL-064, SQL-065, SQL-075, SQL-076, SQL-078, SQL-083
Email info CRUD and linking	Persist standalone email rows and maintain their customer/contact link rows	Caller adds/edits/removes a clsEmailAddressInfo in a customer's or contact's EmailAddresses collection and the parent saves	Email fields, owning customer/contact ID	Persisted EMAIL_ADDRESS row; persisted or removed COMPANY_EMAIL/PERSON_EMAIL link row	BR-006, BR-010	EMAIL_ADDRESS, COMPANY_EMAIL, PERSON_EMAIL	SQL-005, SQL-011, SQL-014, SQL-015, SQL-071, SQL-072, SQL-079, SQL-085, SQL-088, SQL-089
Phone info CRUD and linking	Persist standalone phone rows and maintain their customer/contact link rows	Caller adds/edits/removes a clsPhoneInfo in a customer's or contact's Phones collection and the parent saves	Phone fields, owning customer/contact ID	Persisted PHONE row; persisted or removed COMPANY_PHONE/PERSON_PHONE link row	BR-007	PHONE, COMPANY_PHONE, PERSON_PHONE	SQL-007, SQL-013, SQL-016, SQL-017, SQL-073, SQL-074, SQL-081, SQL-087, SQL-090, SQL-091
Long-note persistence	Persist long-form notes separately from the root customer or contact rows, deleting blank notes rather than storing them	Caller sets clsCustomer.LongNoteText/clsContact.LongNoteText and the parent saves	NoteText, owning customer/contact ID	Persisted or deleted COMPANY_NOTE/PERSON_NOTE row	BR-009	COMPANY_NOTE, PERSON_NOTE	SQL-006, SQL-012, SQL-033, SQL-040, SQL-067, SQL-070, SQL-080, SQL-086
Agency, agent, and provider customer resolution	Resolve agency, agent, and provider identifiers into local customer/contact records, creating and linking them on first use	Caller invokes GetCustomerInfoForAgent or GetCustomerIDForProvider with an external identifier	Agency/agent/provider identifier, optional create flag	Resolved AgentInfo or provider CustomerID; newly created COMPANY/PERSON rows and mapping rows when no mapping existed	BR-008	AGENCY, AGENT, CUSTOMER_AGENCY, CUSTOMER_AGENT, CUSTOMER_PROVIDER, PROVIDER, PROVIDER_TAX_ID	SQL-018, SQL-019, SQL-024, SQL-046, SQL-047, SQL-048, SQL-049, SQL-059, SQL-060, SQL-063
External identifier resolution	Resolve auditor, MCO, RTW, group, policy, and injured-worker identifiers into local customer records	Caller invokes one of the GetCustomerIDFor* resolution functions with an external source-system identifier	Auditor/MCO/RTW/group/policy/worker identifier	Resolved CustomerID (or populated WorkerInfo); newly created COMPANY row and mapping row when no mapping existed	None registered*	PA_AUDITOR, CUSTOMER_AUDITOR, CUSTOMER_SOURCE, RTW_LOAD_CODE, CUSTOMER_GROUP, GROUP_ASSOCIATION, CUSTOMER_POLICY, POLICY	SQL-020, SQL-021, SQL-022, SQL-023, SQL-025, SQL-050, SQL-051, SQL-052, SQL-053, SQL-054, SQL-055, SQL-056, SQL-057, SQL-058, SQL-061, SQL-062
Contact info helper factories and code-map lookups	Build and attach phone/email info items from raw values, and cache code-map lookups for type/description resolution	Caller invokes mdlCustomerContact.CreatePhone/CreateEmail, or any operation resolves a code/type description	Raw phone/email value, type identifier, isPrimary	Constructed clsPhoneInfo/clsEmailAddressInfo attached to the contact's collection; cached code-map lookups	None registered*	None documented*	None catalogued*

Process flow diagram

The following diagram shows how the eleven operations relate: a caller searches for or retrieves a customer/contact, maintains the root record and its info-item/relationship/note children, and — for records originating outside this system — resolves an external identifier into a local customer before that customer participates in the rest of the model.

flowchart TD
    Start([Caller requests customer/contact data]) --> Search[Customer/contact search]
    Start --> Retrieve[Retrieve or create<br>root customer/contact]
    Retrieve --> CustomerCRUD[Customer CRUD with<br>child persistence]
    Retrieve --> ContactCRUD[Contact CRUD with<br>child persistence]
    CustomerCRUD --> Children[Maintain child info items]
    ContactCRUD --> Children
    Children --> Address[Address info CRUD and linking]
    Children --> Email[Email info CRUD and linking]
    Children --> Phone[Phone info CRUD and linking]
    Children --> Note[Long-note persistence]
    CustomerCRUD --> Relationship[Customer-contact relationship CRUD]
    ContactCRUD --> Relationship
    Email --> Helper[Contact info helper factories<br>and code-map lookups]
    Phone --> Helper
    External([External identifier presented]) --> Resolve{Identifier type}
    Resolve -->|Agency/agent/provider| Agency[Agency, agent, and provider<br>customer resolution]
    Resolve -->|Auditor/MCO/RTW/group/policy/worker| ExtID[External identifier resolution]
    Agency --> CustomerCRUD
    Agency --> Relationship
    ExtID --> CustomerCRUD
    Agency --> Done([Local customer/contact<br>ready for use])
    ExtID --> Done
    Relationship --> Done
    Note --> Done
    Address --> Done
    Phone --> Done
    Search --> 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
Customer/contact search	SQL-031, SQL-037	PERSON, COMPANY, COMPANY_PERSON	Read
Customer CRUD with child persistence	SQL-008, SQL-035, SQL-068, SQL-082	COMPANY	Read / Write
Contact CRUD with child persistence	SQL-003, SQL-028, SQL-029, SQL-066, SQL-077	PERSON	Read / Write
Customer-contact relationship CRUD	SQL-010, SQL-028, SQL-038, SQL-069, SQL-084	COMPANY_PERSON, COMPANY, PERSON	Read / Write
Address info CRUD and linking	SQL-001, SQL-002, SQL-004, SQL-009, SQL-030, SQL-036, SQL-064, SQL-065, SQL-075, SQL-076, SQL-078, SQL-083	ADDRESS, COMPANY_ADDRESS, COMPANY_ADDRESS_PHONE, PERSON_ADDRESS, PERSON_ADDRESS_PHONE	Read / Write
Email info CRUD and linking	SQL-005, SQL-011, SQL-014, SQL-015, SQL-071, SQL-072, SQL-079, SQL-085, SQL-088, SQL-089	EMAIL_ADDRESS, COMPANY_EMAIL, PERSON_EMAIL	Read / Write
Phone info CRUD and linking	SQL-007, SQL-013, SQL-016, SQL-017, SQL-073, SQL-074, SQL-081, SQL-087, SQL-090, SQL-091	PHONE, COMPANY_PHONE, PERSON_PHONE	Read / Write
Long-note persistence	SQL-006, SQL-012, SQL-033, SQL-040, SQL-067, SQL-070, SQL-080, SQL-086	COMPANY_NOTE, PERSON_NOTE	Read / Write
Agency, agent, and provider customer resolution	SQL-018, SQL-019, SQL-024, SQL-046, SQL-047, SQL-048, SQL-049, SQL-059, SQL-060, SQL-063	AGENCY, AGENT, CUSTOMER_AGENCY, CUSTOMER_AGENT, CUSTOMER_PROVIDER, PROVIDER, PROVIDER_TAX_ID	Read / Write
External identifier resolution	SQL-020, SQL-021, SQL-022, SQL-023, SQL-025, SQL-050, SQL-051, SQL-052, SQL-053, SQL-054, SQL-055, SQL-056, SQL-057, SQL-058, SQL-061, SQL-062	PA_AUDITOR, CUSTOMER_AUDITOR, CUSTOMER_SOURCE, RTW_LOAD_CODE, CUSTOMER_GROUP, GROUP_ASSOCIATION, CUSTOMER_POLICY, POLICY	Read / Write
Contact info helper factories and code-map lookups	None catalogued*	None documented*	Read (cached reference data)

Failure and edge-case behavior

• Search execution is blocked until callers satisfy BR-001 and BR-002.
• Contact deletion is blocked by BR-003 while relationship rows still exist.
• Relationship maintenance fails until callers satisfy BR-004; a suspected defect in the relationship update statement may cause a relationship-code change to match zero rows rather than update the intended row.*
• Address, email, and phone save paths apply BR-005, BR-006, and BR-007 before persistence; removing an info item from a collection deletes only the customer/contact link row, never the standalone ADDRESS/EMAIL_ADDRESS/PHONE row.*
• A blank long note is deleted rather than persisted as empty text (BR-009); changing an email's value clears its verified flag (BR-010).
• Agency, agent, and provider conversion flows can create inactive records according to BR-008; CreateAgent's existing-mapping lookup is suspected to bind the wrong identifier, and provider address creation is present in source as dead, commented-out code.*
• GetCustomerIDForMCO is the only external-identifier resolution function that never creates a customer when no mapping is found; the injured-worker path depends on an external REST API (CCClaimDataApi) rather than another SAIF library.*
• mdlCustomerContact.CreateEmail has no validity gate before attaching a new email to a contact's collection, unlike the equivalent CreatePhone helper, which only attaches phones that are already valid.*

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

Related documentation

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

Sources

• Business\SAIF.Business.CustomerContact\clsCustomerContactSearch.vb
• Business\SAIF.Business.CustomerContact\mdlCustomerContact.vb
• Business\SAIF.Business.CustomerContact\mdlCodeMaps.vb
• Business\SAIF.Business.CustomerContact\AgentInfo.vb
• Business\SAIF.Business.CustomerContact\WorkerInfo.vb
• Business\SAIF.Business.CustomerContact\Customer\clsCustomer.vb
• Business\SAIF.Business.CustomerContact\Customer\clsCustomerContact.vb
• Business\SAIF.Business.CustomerContact\Customer\clsCustomerAddressCollection.vb
• Business\SAIF.Business.CustomerContact\Customer\clsCustomerEmailCollection.vb
• Business\SAIF.Business.CustomerContact\Customer\clsCustomerPhoneCollection.vb
• Business\SAIF.Business.CustomerContact\Customer\clsCustomerNote.vb
• Business\SAIF.Business.CustomerContact\Contact\clsContact.vb
• Business\SAIF.Business.CustomerContact\Contact\clsContactAddressCollection.vb
• Business\SAIF.Business.CustomerContact\Contact\clsContactEmailCollection.vb
• Business\SAIF.Business.CustomerContact\Contact\clsContactPhoneCollection.vb
• Business\SAIF.Business.CustomerContact\Contact\clsContactNote.vb
• Business\SAIF.Business.CustomerContact\InfoItems\clsAddressInfo.vb
• Business\SAIF.Business.CustomerContact\InfoItems\clsEmailAddressInfo.vb
• Business\SAIF.Business.CustomerContact\InfoItems\clsPhoneInfo.vb
• Business\SAIF.Business.CustomerContact\InfoItems\clsInfoCollection.vb