Master the referral creation workflow, company search, criteria selection, output generation, and comprehensive testing strategy for the company referrals system
Chapters receive frequent requests: "Can you recommend a roofing contractor?" "Who does MEP design?" "Need a security consultant." Historically, these inquiries were handled ad-hoc—a phone call to chapter staff, manual email searches, uncertain outcomes. This erodes the perceived value of membership.
The Referrals module formalizes this workflow. Chapter staff can rapidly generate vetted company lists based on professional criteria (CSI codes, NAICS classifications, designations, geographic regions, dues levels), export them as professional PDFs or Excel documents, and email them to requestors and referred companies. Every referral is tracked and auditable.
Business value: (1) Membership retention—members see direct benefit when their network generates leads; (2) Engagement tracking—chapters understand who asks for what, informing programming and sponsorship strategy; (3) Professional credibility—polished, consistent referral outputs reinforce chapter brand; (4) Revenue potential—future monetization of high-demand referral requests.
Every referral request flows through four sequential phases:
Chapter staff identifies WHO is asking and WHY. They search for the requesting company using type-ahead (same global company search), or add a new prospect if the company isn't yet in the database. They capture requestor individual contact info (name, phone, email) and required project information.
Staff defines the target company profile using mutually-exclusive code types (CSI, NAICS, or Directory codes), combined with business designations (multi-select), geographic regions (multi-select), and dues category range. Clicking "Generate Results" queries the database.
The system returns a table of matching active ABC member companies. Staff reviews, deselects companies as needed, and toggles the "Company Narrative" column on/off. Clicking "Compile List" finalizes the selection.
Six output pathways: three exports (PDF basic, PDF with narrative, Excel) and three email options (basic to requestor, narrative to requestor, email to all referred companies). Email outputs require confirmation modal; exports do not.
The Referrals tab appears in both chapter site company profiles and (optionally) in the member portal. Two complementary views track the lifecycle:
Requested Referrals: Shows referral requests THIS company initiated. Staff can filter, view details, and export results. Always visible in both chapter site and portal (if enabled).
Included in Referrals: Shows referral lists in which THIS company was included. Portal visibility controlled by a setting during referral creation. Chapter site always displays. This reinforces to members that their company is a valued network resource.
Verify that chapter staff can articulate the business value: "I am tracking which companies ask for what, and building professional company networks." Understand that referral outputs represent your chapter brand—they must be polished, accurate, and reliable.
Company Search: Uses type-ahead matching (identical to global company search). As user types, autocomplete returns matching company names. Matching is case-insensitive and supports partial word matching.
Add New Company: If company not found, user clicks "Add New Company" to create a prospect record on-the-fly. Required fields: Company Name, Phone Number, Email Address. New company defaults to Level=Hot, Status=Active.
Requestor Individual Fields: Full Name (required), Phone Number (required), Email Address (required). These are separate from company contact fields and enable direct follow-up with the requestor.
Project Information: Required description of the project or service being requested. Example: "Looking for MEP design-build contractor for 50,000 sq ft warehouse." This context is included in email outputs to referred companies.
Code Type Mutual Exclusivity: User selects ONE of three code hierarchies: CSI Codes, NAICS Codes, or Directory Codes. Selecting codes in one hierarchy deactivates the other two. Switching code types clears prior selections.
Hierarchical Selection: Each code type supports parent → subcategory navigation. For CSI, user might select "04 Masonry" (parent), then drill into "04 20 00 Unit Masonry" (subcategory). Multiple subcategories under the same parent, or across parents, are additive.
Business Designations: Independent multi-select checkboxes (e.g., Women-Owned, Minority-Owned, Certified, etc.). User may select zero, one, or many designations. These filter IN ADDITION to code selections.
Regions: Multi-select geography (state, zip code region, or custom regions). User may select zero, one, or many regions. Additive with designations and code criteria.
Dues Category Range: Dropdown for From Category and To Category (e.g., From "Gold" to "Platinum"). Results include companies whose dues level falls within the specified range, inclusive.
Generate Results: Click button executes the query against the database. Returns all active ABC member companies matching ALL selected criteria.
Results Table: Displays Company Name, Status, City/State, Codes, and optional Company Narrative column. All columns are sortable and filterable (at minimum by company name and city).
Company Selection: Each row has a checkbox. ALL companies are selected by default. User may individually deselect companies. A "Select All / Deselect All" header checkbox toggles the entire table.
Company Narrative Toggle: Button to show/hide the Company Narrative column (company description, capabilities overview). Toggles visibility without altering data.
Return to Criteria: User may click "Back to Criteria" to refine selections. Original selections in Step 2 are preserved and redisplay. User can modify and re-generate without losing prior work.
Compile List: Click to lock the selected companies and proceed to Step 4 outputs. After compiling, selection state is frozen—user cannot modify company selections until they create a new referral from scratch.
Export Formats (3 types):
Email Outputs (3 types):
Confirmation Modals: Email outputs display a modal showing preview of email content, recipient count, and requester confirmation button. Exports proceed immediately without modal.
Every company profile in the chapter site includes a "Referrals" tab (when Referrals module is enabled). This tab displays two sections:
Requested Referrals: All referral requests initiated by THIS company. Shows: Request Date, Project Description, Number of Companies Referred, Status (In Progress / Completed). Staff can click to view/export the original referral list.
Included in Referrals: All referral requests in which THIS company was included. Shows: Request Date, Project Description, Requesting Company, Number of Companies in List, Status. Portal display controlled by setting during referral creation.
The member portal mirrors company profile data, but with controlled visibility. When staff creates a referral and selects "Show this referral in member portal," the Included in Referrals section becomes visible to member portal users from referred companies.
Requested Referrals: Always visible in portal if module is enabled. Members can see requests their company initiated and export prior lists.
Included in Referrals: Visibility determined by per-referral setting. If enabled, referred companies see all referral lists in which they were included—reinforcing their value to the chapter network.
Test each step in isolation and in sequence. Verify Step 1 company search works identically to global search. Confirm mutual exclusivity in Step 2—if I select CSI codes and then click NAICS, CSI selections must clear. In Step 3, test that "Return to Criteria" preserves state. In Step 4, confirm all six output types generate correctly and that email confirmation modals prevent accidental sends.
A formal request from a chapter member or prospect seeking qualified contractors matching specified criteria. Referrals are tracked, auditable, and can generate multiple output formats.
The company initiating the referral request. May be a chapter member, prospect, or Hot lead. Always appears in the "Requested Referrals" tab of their company profile.
An active ABC member company included in the compiled referral list. Appears in "Included in Referrals" on their profile. May receive direct email outreach about the opportunity.
Construction Specifications Institute hierarchical code system for construction services. Supports parent-subcategory selection. Mutually exclusive with NAICS and Directory codes.
North American Industry Classification System code representing industry type. Hierarchical selection supported. Mutually exclusive with CSI and Directory codes.
Chapter-specific classification system for member services and specialties. Mutually exclusive with CSI and NAICS codes.
Certifications or classifications (e.g., Women-Owned, Minority-Owned, Certified Green, Veteran-Owned). Multi-select; filters applied in addition to code criteria.
Filter for company membership level (e.g., Bronze, Silver, Gold, Platinum). Results include companies whose dues level falls within From/To range, inclusive.
Action that locks the referral. After compiling, company selections are final. No further filtering or deselection permitted unless user creates a new referral.
Detailed company description and capability overview. Optional column in Step 3 results table. Can be toggled on/off and included in PDF narrative exports.
Non-member company added to the system during referral creation. Defaults to Level=Hot, Status=Active. Eligible as a requesting company but not as a referred company (only active members).
Final deliverable: PDF (basic or narrative), Excel spreadsheet, or email. Generated from compiled referral list. May be sent to requestor, referred companies, or exported for offline use.
Ensure these terms appear consistently across help text, error messages, and UI labels. If a new user sees "Directory Code" in a dropdown, they should be able to find its definition in the Glossary.
Company Type-Ahead Search: Test that autocomplete matches exact company names, partial matches, and case-insensitive queries. Verify search is identical to global company search implementation. Test boundary cases: empty input, single character, special characters, whitespace.
New Company Creation: Verify all three required fields (Name, Phone, Email) are mandatory. Test phone number format validation (if any). Test email format validation. Confirm new company is created with Level=Hot, Status=Active. Verify new company immediately available for selection in this referral.
Requestor Individual Fields: Verify all three requestor fields (Name, Phone, Email) are mandatory. Test that these are independent from company contact fields (i.e., you can enter different names/phones). Test email format validation for requestor email.
Project Information: Verify field is mandatory. Test with various lengths (short, medium, long text, max length). Confirm project description persists through workflow steps and appears in outputs.
Code Type Exclusivity: Test selecting CSI codes → then NAICS → confirm CSI selections clear. Test NAICS → Directory → confirm NAICS selections clear. Test that only one code type can be active at a time. Attempt to select codes from multiple hierarchies simultaneously—should fail gracefully.
Hierarchical Selection: Test parent selection (should select all children? or parent only?). Test child selection (should auto-select parent?). Test multi-level expansion. Test deselecting parent (children deselect).
Multi-Select Fields: Verify designations and regions support multi-select independently. Test selecting zero, one, and many values. Verify checkboxes are intuitive and properly labeled.
Dues Category Range: Test From/To selections. Test range validation (From ≤ To). Test generating results with range spanning multiple categories. Test empty range (no filter).
Generate Results: Confirm button is disabled until at least one criterion is selected. Test that database query completes within acceptable time. Test empty results (no companies match criteria).
Results Table Display: Verify all columns display correctly (Company Name, Status, City/State, Codes, optional Narrative). Test column sorting by company name, status, city, and code count. Test filtering/search within results.
Default Selection: Confirm all companies are pre-checked. Test "Select All" and "Deselect All" header checkbox. Test individual row checkbox toggle. Test that selection state persists during column toggle.
Company Narrative Toggle: Verify narrative column visibility can be toggled on/off without affecting data. Test that CSV export respects narrative column setting. Test UI clarity of toggle button (enabled/disabled states).
Return to Criteria: Click "Back to Criteria" from Step 3 results. Verify all Step 2 selections (code type, specific codes, designations, regions, dues range) are preserved and redisplay. Modify selections and re-generate—confirm new results reflect changes.
Compile List: Click "Compile List" with all companies selected. Verify referral enters a locked state. Verify UI prevents further selection changes. Verify "Compile List" button becomes disabled or disappears.
PDF Basic Export: Generate and validate file format. Verify header/footer branding. Verify columns are correct (Name, Status, City/State, Codes). Verify all compiled companies are listed. Verify no narrative column. Test file naming convention.
PDF Narrative Export: Same as Basic but verify Company Narrative column is included. Test that narratives display fully (check for truncation/wrapping). Test page breaks for large lists.
Excel Export: Generate and validate spreadsheet. Verify all columns present and properly formatted. Verify company data is correct (no corruption, special character handling). Verify headers are present. Test file naming.
Email to Requestor (Basic): Trigger email output. Verify confirmation modal appears. Verify modal displays email preview, recipient email address, subject line. Click confirm. Verify email is sent to requestor email (check email logs or test mailbox). Verify email body contains project description.
Email to Requestor (Narrative): Same as Basic but verify email includes company narratives in email body.
Email to Referred Companies: Trigger email output. Verify confirmation modal shows count of emails to be sent. Verify modal allows review of email template. Click confirm. Verify individual emails sent to each referred company. Verify each email includes project description and requestor contact info. Verify email asks if company is interested.
Confirmation Modal Cancellation: Trigger email output, open confirmation modal, click Cancel/Close. Verify email is NOT sent and workflow returns to referral view.
Requested Referrals Tab: Navigate to requesting company profile. Verify Referrals tab present. Verify "Requested Referrals" section shows all referrals initiated by this company. Verify table columns (Request Date, Project Description, Company Count, Status). Verify staff can click to view/export original lists.
Included in Referrals Tab: Navigate to referred company profile. Verify "Included in Referrals" section shows all referrals in which company was included. Verify staff can click to view details. Test portal visibility setting—when disabled, verify section does not appear to portal users.
Portal Display Control: Create referral with portal visibility ENABLED. Navigate to portal as member user. Verify Included in Referrals section is visible. Create new referral with portal visibility DISABLED. Verify section does NOT appear to portal users for this referral.
Portal Export: From portal, verify member users can export their Requested Referrals. Verify exports generate correct file format and content.
Module Accessibility: Verify Referrals is accessible under Contacts module in chapter site navigation. Verify permissions are tied to Contacts module permissions (users with Contacts access can create referrals).
Staff vs. Member Access: Verify chapter staff can create, view, and export all referrals. Verify member portal users can only view referrals related to their company (Requested and Included, subject to visibility setting). Test that members cannot create new referrals (or appropriate role required).
Data Isolation: Create referral for Company A. Verify Company B cannot see Company A's Requested Referrals. Verify Company B can see Included in Referrals only if visibility setting enabled.
Approach testing as a funnel: (1) Functional—do outputs generate correctly? (2) Integration—do outputs appear in company profiles and portal? (3) Edge cases—what happens with empty results, single company, max company limit? (4) Permissions—who can see what? Follow the user journey from Step 1 through Step 4 and beyond into company profile tracking.
Referrals is accessible under the Contacts module in chapter site navigation. Permissions are tied directly to Contacts permissions. Users with Contacts access can create, view, and manage referrals. Users without Contacts permissions cannot access Referrals.
The company type-ahead search in Step 1 uses the same matching logic as global company search across the platform. Matching is case-insensitive, supports partial word matching, and returns results in relevance order.
If a company is not found via type-ahead search, user can click "Add New Company" to create a prospect record on-the-fly during referral creation. This enables staff to include prospects as requesting companies without pre-populating the database.
Adding a new company requires: Company Name, Phone Number, Email Address. All three are mandatory. New company is automatically created with Level=Hot, Status=Active, and is immediately available as the requesting company for this referral.
Only ONE code type (CSI, NAICS, or Directory) can have active selections in a single referral. Selecting codes in one hierarchy deactivates the other two. Switching from one code type to another clears all prior selections in the previous type.
Each code type supports hierarchical parent → subcategory selection. Users can expand parent categories to view subcategories. Selecting a parent may auto-select children (or vice versa, depending on implementation). Deselecting a parent deselects all children.
Within the active code type, multiple specific codes are selectable. For example, user can select CSI "04 20 00 Unit Masonry" AND "05 10 00 Structural Steel." Results include companies with ANY of the selected codes.
Business Designations and Regions are independent multi-select fields. User can select zero, one, or many values in each. These filters are applied IN ADDITION to code selections. Results must match code criteria AND at least one selected designation/region (if any selected).
Dues Category Range uses From and To dropdowns. Results include companies whose dues category falls within the range, INCLUSIVE. Range is optional (no selection = no dues filter).
In Step 3 results, all generated companies are pre-checked by default. User may individually deselect companies, or use "Deselect All" to clear all selections. At least one company must remain selected before "Compile List" is allowed.
Clicking "Compile List" in Step 3 finalizes and locks the referral. After compiling, no further changes to company selections are permitted. User cannot return to Step 3 to modify the list. To change selections, user must create a new referral from scratch.
When user clicks "Return to Criteria" in Step 3, all selections from Step 2 are preserved and redisplay. User can modify criteria and re-generate without losing prior work. Selections persist until user explicitly clears them or creates a new referral.
The Company Narrative column in Step 3 results is optional and toggleable. User can show/hide narrative column without affecting underlying data or selections. Narrative column state is independent from other filters/sorts.
Email outputs (3 types) require a confirmation modal. User clicks email button → modal displays preview, recipient count, and "Confirm" button. Only after explicit confirmation is email sent. Exports (PDF, Excel) do NOT require confirmation and download immediately.
During referral creation (Step 1 or Step 4), staff can toggle a setting: "Show this referral in member portal." If enabled, the Included in Referrals section is visible to member portal users from referred companies. If disabled, section is hidden from portal but visible in chapter site.
Step 3 results (the list of companies) should ONLY include active ABC members. Archived, inactive, or deactivated members are excluded from results, even if they match all criteria. Requesting company may be a prospect (non-member), but referred companies must be active members.
Every company profile includes a Referrals tab (when module is enabled). This tab displays two sections: Requested Referrals (referral requests THIS company initiated) and Included in Referrals (referral lists in which THIS company was included).
Member portal mirrors chapter site referral data, with one exception: Included in Referrals visibility is controlled by per-referral setting. Requested Referrals are always visible in portal (if module enabled). Both environments support export of referral lists.
The "Add Note" feature (Line 6 on original requirements) is explicitly descoped from this release. Notes cannot be added to referral records in this iteration.
Three export formats available: (1) PDF Basic (Company Name, Status, City/State, Codes), (2) PDF Narrative (Basic columns PLUS Company Narrative), (3) Excel (all columns in spreadsheet format). Exports download immediately without confirmation modal.
Three email output options: (1) Email Basic to Requestor (compiled list, basic format, to requestor email), (2) Email Narrative to Requestor (compiled list, with narratives, to requestor email), (3) Email to Referred Companies (individual emails to each company with project description and requestor contact info, asking if interested). All require confirmation modal.
These 21 rules are the "contract" between QA and development. Before testing, ensure all 21 rules are implemented. During testing, validate each rule in isolation and in combination. A common gotcha: mutual exclusivity (Rule 5)—ensure switching code types truly clears prior selections. Another: rule 16 (active members only)—test that archived companies never appear in results.
Setup: Chapter staff creates a referral. A prospect company calls asking for MEP contractors, but company is not in ABC database.
Expected Flow: Staff searches for company name via type-ahead, gets no results. Staff clicks "Add New Company," enters company name, phone, email. New company created with Level=Hot, Status=Active. Staff continues to Step 2 with prospect as requesting company.
QA Checkpoints: Verify new company is not available as a "referred company" in Step 3 results (only active members referred). Verify company IS available as requesting company. Verify new company immediately available in future referrals.
Setup: Staff selects CSI codes (04 20 00 and 05 10 00), views results. Then realizes they should use NAICS codes instead.
Expected Flow: Staff clicks NAICS dropdown. CSI selections clear. Staff selects NAICS codes. Generate Results returns NAICS-based list.
QA Checkpoints: Verify CSI selections are completely cleared when user switches to NAICS. Verify UI visually indicates NAICS is now active (CSI grayed out). Verify results are NAICS-filtered, not hybrid CSI+NAICS. Test reverse (NAICS → CSI, NAICS → Directory, Directory → CSI).
Setup: Step 3 shows 15 companies. Staff clicks "Deselect All" to remove all checkmarks, intending to manually select only 3 specific companies.
Expected Flow: Staff deselects all, then checks 3 specific companies, clicks "Compile List."
QA Checkpoints: Verify "Compile List" button is disabled if ZERO companies selected. Verify error message if user attempts to compile with no selections. Verify message is user-friendly and actionable.
Setup: Staff selects companies in Step 3, clicks "Compile List," and enters Step 4 outputs. Then realizes they should have included different companies and clicks "Back to Criteria."
Expected Flow: Once a list is compiled, "Back to Criteria" should NOT be available, or should warn user that going back will reset the referral (or create a new referral).
QA Checkpoints: Verify "Back to Criteria" is disabled post-compile OR clicking it creates a new referral (not reverting to Step 2). Verify original compiled referral is preserved. Clarify in UI what happens if user tries to navigate backward after compile.
Setup: Staff creates referral with requestor info but accidentally leaves requestor email empty (or uses invalid format).
Expected Flow: Step 1 should not allow progression to Step 2 if requestor email is missing or invalid. Error message indicates field is required.
QA Checkpoints: Verify email field validation. Attempt email output (to requestor) without valid email—should fail gracefully. Verify error message is clear (don't just say "error," specify "Requestor email is required").
Setup: Staff selects very specific criteria (e.g., obscure CSI code, rare designation, specific region) that matches ZERO active members.
Expected Flow: Generate Results returns empty table with message like "No companies found matching your criteria."
QA Checkpoints: Verify empty state is user-friendly and actionable (suggests "refine criteria" or "go back"). Verify "Compile List" is disabled with zero companies. Verify "Generate Results" remains available to try different criteria.
Setup: Staff generates results in Step 3 and selects a company. Between Step 3 and Step 4, that company is archived in the main database (staff member or admin action). Staff then tries to export or email referral.
Expected Flow: System should detect archived company. Either: (A) warn user before export/email, (B) exclude archived company from output, or (C) document expected behavior clearly.
QA Checkpoints: Clarify with product owner: if company is archived after selection but before output, what should happen? Document this in business rules. Test the chosen behavior.
Scenario testing reveals usability issues, edge cases, and unclear requirements. For each scenario, identify: (1) the setup (what preconditions must be true), (2) expected flow (what SHOULD happen), (3) actual behavior (what DOES happen), (4) alignment (does actual match expected?). Use scenarios to validate that business rules are correctly implemented and user experience is intuitive.
Use these checklists as your "safety net" before each release. Run through each checklist item systematically. If an item fails, investigate: Is it a bug, a missing implementation, or a misunderstood requirement? Document failures and link to relevant ABC-XXXX tickets for triage.
Active Member Companies: Create at least 20 test companies with Status=Active and varied profile attributes (different CSI codes, NAICS codes, Directory codes, designations, regions, dues categories).
CSI Code Coverage: Ensure test companies span multiple CSI code families (e.g., 04 Masonry, 05 Metals, 06 Wood, 07 Thermal, 08 Openings, 09 Finishes, etc.). Include companies with multiple codes.
NAICS Code Coverage: Ensure test companies span NAICS hierarchies (e.g., 23 Construction, 23 21 Building Construction, 23 23 Heavy and Civil Engineering Construction, etc.).
Directory Code Coverage: If directory codes exist in your chapter, test companies should span multiple directory classifications.
Business Designations: Create companies with various designations (Women-Owned, Minority-Owned, Certified Green, Veteran-Owned, etc.). Some companies should have no designation, some should have one, some should have multiple.
Geographic Distribution: Companies should span multiple states/regions (if regional filtering exists). Include companies from 3-5 different states or geographic areas.
Dues Categories: Create companies across dues spectrum (Bronze, Silver, Gold, Platinum, or equivalent). Test range filters with companies at boundaries and within range.
Archived/Inactive Companies: Create a few inactive or archived companies to verify they are excluded from referral results.
Chapter Staff Account: Create a test user with Contacts module permissions (to create/manage referrals). Email should be valid (for testing email outputs). Use for end-to-end workflow testing.
Limited Access Account: Create a test user WITHOUT Contacts permissions. Verify Referrals module is not accessible to this user.
Portal User Account(s): Create member portal user accounts for companies in the test database. Use to verify portal-visible data (Requested Referrals, Included in Referrals with visibility setting enabled).
Admin Account: Access to archive/deactivate companies for edge case testing (Scenario 7).
Email Log Access: Ensure QA has access to email logs or test mailbox to verify emails are sent correctly. Use a dedicated test email address (e.g., qa-referrals-test@company.com) for verification.
Email Templates: Verify referral email templates are configured (requestor emails, referred company emails). Test that project description and requestor contact info are correctly inserted.
SMTP Configuration: Verify SMTP settings are correct in test environment. Configure email sending from the correct domain/address.
1. Database Seeding: Run data setup script to create 20+ test companies with varied attributes per requirements above. Verify companies are visible in global company search.
2. Code Hierarchy Verification: Verify CSI, NAICS, and Directory code hierarchies are loaded and display correctly in Step 2 dropdown.
3. User Account Creation: Create test users per section above. Assign appropriate permissions (Contacts module for staff, portal access for members).
4. Email Configuration: Test email sending by triggering a test email (e.g., from company profile). Verify email arrives in test mailbox.
5. Portal Configuration: Verify portal is accessible and portal users can view company data. If portal visibility setting exists, verify it functions.
6. Smoke Test: Run one complete referral workflow (Steps 1-4) to ensure basic functionality. Verify export and email outputs are generated.
Between Test Cycles: After completing a full test cycle, consider refreshing test data to ensure clean state for next cycle. This includes clearing test referral records and resetting company statuses (unarchive test companies if needed).
Baseline Data Preservation: Keep a baseline set of 20-30 stable test companies. Do not modify their profiles during testing (unless intentionally testing profile changes).
Dynamic Test Data: Use a separate set of "throwaway" test companies for destructive or edge case testing (e.g., archiving companies, deleting referrals).
A well-prepared test environment is the foundation of reliable testing. Invest time in setup to avoid blockers during test execution. Verify each prerequisite before starting referral workflow testing. Keep test data organized and documented so future testers can understand what data represents what scenario.