The Business
ABC Contacts powers member data management in CHAD2. Understanding the business context helps you catch edge cases that matter to chapters and national leadership.
🏢 What ABC Contacts Is Really About
ABC Contacts is the master record system for Companies and Individuals in CHAD2. Companies represent ABC member firms — contractors, subcontractors, and affiliates. Individuals are the people connected to those companies — employees, contacts, decision-makers. The system bridges the gap between National's need for clean, uniform member data and Chapters' need for control over their local member records.
Contacts is the foundation that every other module depends on: Events registers people, Membership & Dues invoices companies, Directory publishes companies, Advocacy tracks company contacts. If contact data is wrong, everything downstream breaks. This creates interesting constraints: you can't delete a company if it has invoices. You can't delete an individual if they have role history. Validation has to be strict.
Companies can be in three states: Member (active in chapter), Prospect (interested, not yet member), or Inactive. Trade codes, market segments, and business designations enrich company profiles. Individuals are linked to companies through Contact Types (e.g., Owner, Controller, Office Manager). The Portal allows member companies to self-manage their data, while staff maintain admin-side control with more powerful tools.
👥 Permission Model: Three Tiers
Member Portal Admin (MPA) can manage the company's full profile: company info, individuals, contact types, trade codes, market segments, and contact lists. They cannot create companies or change company status — that's staff-only. Portal Individual with Registration can view and edit the company's profile but cannot add/remove individuals or manage some sensitive fields. Portal Individual with Limited has read-only view. Every portal user was invited (no self-sign-up for portal accounts).
Chapter Staff with Contacts Permission can create, edit, and delete companies and individuals at will. Staff can override portal restrictions, manually add individuals, and force data changes. Staff can also run Contact Audits (data quality checks with 31 distinct criteria) and see sensitive audit reports that portal users cannot access.
📊 Data Value: What Members Get, What Chapters Get, What National Gets
For members, the portal is simple: log in, verify your company data is correct, update contact info, add new individuals when staff invites them, export your company profile. It's self-service data stewardship without chaos — members cannot delete, reorganize, or merge records.
For chapters, Contacts is operational. They manage a portfolio of member companies and prospect companies. They track company classifications (market segments, business designations, trade codes), build targeted contact lists, verify data quality, and enable portal access for their largest members. Chapters can customize lookup tables (choosing which trade codes are available locally vs. using national standards).
For National, Contacts create a uniform member directory and reporting foundation. They see member rosters, track where companies are strongest, monitor adoption of portal features, and run compliance audits on data. National controls national-level lookup tables (trade code lists, market classifications) while chapters control chapter-level overrides.
🔗 Core Data Structure: Companies, Individuals, and Contact Types
Companies are the primary records. Each has a Name, Status (Member/Prospect/Inactive), Type, and optional rich metadata: Company Type (e.g., Contractor), Trade Codes (CSI Divisions, NAICS codes), Market Segments (Commercial, Industrial, Residential percentages), Business Designations (e.g., Certified, Union, etc.), Company Narrative (internal notes), and Related Companies (parent/subsidiary relationships).
Individuals are the people. Each has Name (First, Last, Informal), Email, Phone, and addresses (may have multiple, only one can be "Primary"). Individuals are always linked to a Company. When you move an Individual to a different company, the system creates an employment history record so you never lose the audit trail.
Contact Types define the relationship between Individual and Company. Examples: Owner, Controller, Project Manager, Office Manager. Contact Types can be flagged as "Member Portal Admin" — if an Individual gets that Contact Type AND the company has the portal enabled, they automatically get a portal invite sent. Contact Types can also be "Primary" per individual (one primary contact type per person).
How It Works
Complete workflows for managing companies, individuals, portal access, and data quality
✏️ Company Lifecycle: Create → Manage → Track
Creating a company requires just Name and Status (defaults to Member). Type, Trade Codes, Market Segments, and Business Designations are optional and can be added later. Company can immediately have individuals added to it. If you enable the portal for the company, any individual with the "Member Portal Admin" contact type gets an automatic portal invite sent.
Managing a company means updating fields, adding/removing individuals, assigning contact types, managing trade codes and market classifications, writing company narrative (internal notes), and defining related companies. All changes are tracked in change history. You can view all invoices, event registrations, and directory proofs tied to the company.
Tracking a company includes running Contact Audits to check data quality against 31 criteria (missing emails, duplicate individuals, invalid trade codes, market classification not 100%, etc.), viewing employment history, exporting company profiles, and building contact lists for outreach.
👤 Individual Lifecycle: Add → Associate → Manage → Track
Adding an individual requires linking them to a company. You provide First Name, Last Name, Email, and optionally Phone and addresses. "Informal Name" auto-populates from First Name but can be manually edited.
Associating to a company means assigning one or more Contact Types. Each contact type is a distinct role: Owner, Manager, Coordinator. An individual can have multiple contact types at the same company (e.g., both "Owner" and "Signatory"). One contact type per individual can be marked "Primary".
Managing an individual means editing name, contact info, addresses, and contact types. If you move an individual to a different company, employment history is automatically created. You cannot delete an individual if they have employment history (to preserve audit trail).
Tracking an individual includes viewing event registrations, invoices, and employment history. The system enforces email uniqueness within the same company for active individuals — you cannot have two active individuals with the same email in the same company, but you can have multiple at different companies or if one is inactive.
🔐 Portal Invitation and Access Flow
Step 1: Chapter enables portal for a company (toggle in company form). If any existing individuals have "Member Portal Admin" contact type, they are automatically invited.
Step 2: Staff invites an individual who doesn't yet have portal access. System sends email with secure link. Invite is one-time-use and expires (configurable, usually 7 days). Individual who receives invite can click link and set password, or ignore it. If ignored, staff can resend invite.
Step 3: Individual sets password and logs in. Portal account is now active. Individual can now manage company data based on their permission level (MPA, Registration, or Limited).
Step 4: Chapter disables portal (toggle off). All portal invites and active sessions for that company become invalid. Individuals cannot log in. Portal data is preserved (not deleted).
📋 Lookup Table Management and Approvals
Lookup tables control values available for Trade Codes, Business Designations, Market Classifications, and Individual Types. Some are national-only (chapters cannot add values). Some are national-approved (chapters can request new values via workflow). Some are chapter-managed (chapters control their own values). When a lookup table value is deleted, records using that value become unlinked (the value is cleared from those records).
Trade Codes have Directory Proof counts — a chapter can set max CSI codes per company, max NAICS codes per company. Exceeding these limits triggers validation errors. Market Classifications must total 100% per group (Public/Private/Federal, Commercial/Industrial/Residential) — otherwise audit fails.
🔍 Contact Audit Flow: Quality Checks at Scale
Step 1: Select audit criteria — choose from 31 defined checks: missing company email, missing individual email, duplicate individuals, invalid trade code, market classifications not 100%, company narrative exceeds limit, address missing city, etc.
Step 2: Run audit — system scans all companies and individuals against selected criteria, generates report.
Step 3: Review results — audit report shows which companies/individuals failed which criteria, details of failures, recommended fixes.
Step 4: Fix issues — staff or portal users (MPAs) fix the data, or audit rules can be suppressed if false positive. Re-run audit to verify.
Glossary
Key terms and concepts used throughout the Contacts module
Company
The master record representing an ABC member firm, prospect, or inactive organization. Contains name, status, type, and enrichment data (trade codes, market segments, business designations).
Individual
A person record linked to a company. Has name, email, phone, and addresses. Cannot exist without a company. Individuals are related to companies through Contact Types.
Contact Type
The role or relationship between an Individual and a Company. Examples: Owner, Controller, Manager. Can be flagged as "Member Portal Admin" or "Primary". One individual can have multiple contact types at same company.
Member Portal Admin (MPA)
An individual with the "Member Portal Admin" contact type. Can manage the company's full profile in the portal: individuals, contact types, trade codes, market segments. Cannot create or delete companies.
Portal Individual
A user invited to the portal to manage company data. Permission level determined by contact type assigned: Registration (full edit), Limited (read-only), or Admin (full edit including add/remove users).
Trade Code
Classification system for company specialization. Supports CSI (Construction Specification Institute) codes and NAICS (North American Industry Classification) codes. Directory Proof limits control max codes per company per type.
Market Segment
Classification of company's market focus as percentages across categories: Public/Private/Federal, Commercial/Industrial/Residential. Must total 100% for each group when enforced.
Business Designation
Labels assigned to companies indicating certifications or status, e.g., Union, Certified, Minority-Owned. Managed through lookup tables, can be national or chapter-managed.
Contact Audit
Data quality check against 31 distinct criteria. Can target specific criteria (missing email, invalid codes, percentage mismatch, etc.). Generates report of non-compliant records with recommended fixes.
Employment History
Audit trail created when an Individual is moved to a different Company. Preserves original and new company associations for compliance and reporting.
Lookup Table
Master list of valid values for a field, e.g., Trade Codes, Business Designations. Can be national-only, national-approved (with request workflow), or chapter-managed.
Directory Proof
Limit on the number of trade codes (by type: CSI or NAICS) a company can have. Set at chapter level, configurable. Exceeding limit triggers validation error or audit failure.
Related Companies
Parent/subsidiary or peer relationships between companies. Tracked for reporting and data organization. Can be used for selective reporting.
Company Narrative
Internal notes field for staff-side context about a company. Chapter-configurable character limit (default 4000). Visible to staff and MPAs in portal, not published.
BREAD Operations
Create, Read, Update, Delete operations. Core test areas for both admin and portal interfaces. Permission checks ensure users can only perform BREAD at their access level.
Selective Reporting
Ability to filter export/reports by company type, market segment, trade code, business designation, or related companies. Used for targeted outreach and analysis.
Test Strategy
How to approach Contacts testing systematically and where the highest risks live
🎯 Focus Areas and Risk Ranking
HIGHEST RISK (must test thoroughly): BREAD operations for both admin and portal sides (permission checks), portal invitation and access flow (email delivery, link expiration, password reset), company deletion constraints (preventing orphaned records), individual email uniqueness within company, portal enable/disable with active users, Contact Type assignment and auto-invites, lookup table tiers (national vs. chapter-managed).
HIGH RISK: Contact Audit accuracy (31 criteria must be correct), market classification percentage validation (must total 100% per group), employment history creation and retention, address "Is Primary" constraints (only one per record), company status transitions and side effects, trade code directory proof max enforcement.
MEDIUM RISK: Portal user permission levels (MPA vs. Registration vs. Limited enforced correctly), company narrative character limits (chapter-configurable), change history completeness, related companies linking, lookup table deletion (clearing from affected records), export and filtering functionality.
LOWER RISK (but test): UI responsiveness, form validation error messages, multi-language support (if applicable), browser compatibility, performance with large data volumes.
⚠️ Known Risk Zones and Edge Cases
Permission Escalation: MPA tries to delete company (should fail). Limited user tries to edit field (should fail). Anonymous user tries to access portal (should redirect to login). Staff member without Contacts Permission tries to create company (should fail). Test all combinations.
Data Loss on Delete: Delete company with invoices (should fail). Delete individual with history (should fail). Delete contact type in use (should fail). Delete lookup table value in use (value should be cleared from records, not deleted). Verify no orphaned records remain.
Portal Access Transitions: Enable portal, MPA auto-invited. Individual accepts invite, logs in. Disable portal, individual tries to log in (should fail). Re-enable portal, MPA gets re-invited. Invite expires (7 days default), individual tries to use expired link (should fail).
Email Uniqueness: Two active individuals at same company with same email (should fail). One active, one inactive with same email (should allow). Same email at different companies (should allow). Email changes after portal account created (portal still works). Test all variations.
Lookup Table Approval Workflows: Chapter requests new value for national-approved table. National admin approves. Value becomes available in chapter. Test request, approval, and availability steps.
Address Constraints: Add primary address, then add another primary address (should fail). Add non-primary, change to primary when primary exists (should fail or auto-flip). Delete primary address when backups exist (should allow).
📋 Test Data Strategy
Company Variety: Create companies in all states (Member, Prospect, Inactive). Create companies with and without portal enabled. Create companies with varying richness (one with all fields, one with minimal data). Create company groups (parent/subsidiary relationships) to test related companies. Create companies near and at directory proof limits.
Individual Variety: Create individuals with multiple contact types. Create individuals with multiple addresses (primary and non-primary). Create individuals in inactive state. Create individuals with employment history (moved from one company to another). Create individuals with email conflicts (to test uniqueness). Create duplicate-looking individuals (same name, different company) to test search accuracy.
Portal Scenarios: Create MPA and test portal access. Create individual with Registration permission and Limited permission. Test all three permission levels independently. Invite individuals who already have portal accounts at different companies. Test invitation expiry.
Lookup Tables: Mix national, national-approved, and chapter-managed values. Create some values that are in use (test deletion). Create some values at directory proof limits. Test cleanup when value is deleted (records should auto-unlink).
Business Rules & Gotchas
Critical business rules that have the biggest impact on testing. Expansion cards show implementation details and edge cases.
Scenario Thinking
Real-world what-if scenarios to guide exploratory testing and edge case coverage
Regression Checklists
Organized by feature area to ensure complete coverage
Environment & Data Setup
Test environment configuration and data prerequisites for comprehensive testing