Skip to content

LOOPS_INTEGRATION_COMPLETE.md

Latest commit

 

History

History
263 lines (215 loc) · 6.39 KB

LOOPS_INTEGRATION_COMPLETE.md

File metadata and controls

263 lines (215 loc) · 6.39 KB
Raw

Loops Integration - Complete Implementation ✅

Overview

The Loops integration has been fully updated to sync nominees, nominators, and voters with appropriate user groups and events. This provides comprehensive email marketing automation for the World Staffing Awards 2026.

User Groups

1. Nominees 2026

  • Who: Approved nominees (people and companies)
  • When: Synced when nomination is approved by admin
  • Requirements: Must have email address
  • Source: "WSA 2026 Nominations"

2. Nominator 2026

  • Who: People who submit nominations
  • When: Synced immediately when nomination is submitted
  • Requirements: Email is required for nomination form
  • Source: "WSA 2026 Nominations"

3. Voter 2026

  • Who: People who vote for nominees
  • When: Synced when vote is cast
  • Requirements: Email is required for voting
  • Source: "WSA 2026 Voting"

Implementation Details

Loops Service Methods

Contact Sync Methods

// Sync nominee (on approval)
await loopsService.syncNominee({
  email: 'nominee@example.com',
  name: 'John Doe',
  category: 'Top Recruiter',
  type: 'person',
  linkedin: 'https://linkedin.com/in/johndoe'
});

// Sync nominator (on submission)
await loopsService.syncNominator({
  email: 'nominator@example.com',
  name: 'Jane Smith',
  phone: '+1234567890',
  linkedin: 'https://linkedin.com/in/janesmith'
});

// Sync voter (on vote)
await loopsService.syncVoter({
  email: 'voter@example.com',
  firstName: 'Bob',
  lastName: 'Johnson'
});

Event Methods

// Nomination submitted event
await loopsService.sendNominationEvent(
  { email: 'nominator@example.com' },
  {
    category: 'Top Recruiter',
    nomineeId: 'uuid-123',
    nomineeName: 'John Doe',
    nomineeType: 'person'
  }
);

// Nomination approved event
await loopsService.sendNominationApprovedEvent(
  { email: 'nominee@example.com' },
  {
    category: 'Top Recruiter',
    nomineeId: 'uuid-123',
    nomineeName: 'John Doe',
    liveUrl: '/nominee/john-doe'
  }
);

// Vote cast event
await loopsService.sendVoteEvent(
  { email: 'voter@example.com' },
  {
    category: 'Top Recruiter',
    nomineeId: 'uuid-123',
    nomineeSlug: 'john-doe',
    nomineeName: 'John Doe'
  }
);

Integration Points

1. Nomination Submission

File: src/app/api/nominations/route.ts

When a nomination is submitted:

  • ✅ Nominator is synced to "Nominator 2026" group
  • ✅ "nomination_submitted" event is sent to nominator
  • ✅ Non-blocking async execution (doesn't delay response)

2. Nomination Approval

File: src/app/api/nominations/route.ts (PATCH method)

When a nomination is approved:

  • ✅ Nominee is synced to "Nominees 2026" group (if email provided)
  • ✅ "nomination_approved" event is sent to nominee
  • ✅ Non-blocking async execution

3. Vote Casting

File: src/app/api/votes/route.ts (existing)

When a vote is cast:

  • ✅ Voter is synced to "Voter 2026" group
  • ✅ "vote_cast" event is sent to voter

Error Handling

Graceful Failures

  • All Loops sync operations are wrapped in try-catch blocks
  • Failures are logged but don't block the main operation
  • Uses fire-and-forget pattern with setTimeout for non-critical syncs

Email Validation

  • Nominee sync only occurs if email is provided
  • Graceful skipping with logging when email is missing
  • All other syncs require email (enforced by form validation)

Retry Logic

  • Built-in retry mechanism with exponential backoff
  • Maximum 3 retry attempts
  • Handles network timeouts and API errors

Testing

Development API

Endpoint: /api/dev/loops-test

Available test actions:

# Test nominee sync
POST /api/dev/loops-test
{
  "action": "sync-nominee",
  "email": "nominee@example.com",
  "name": "Jane Nominee",
  "category": "Top Recruiter",
  "type": "person"
}

# Test nominator sync
POST /api/dev/loops-test
{
  "action": "sync-nominator",
  "email": "nominator@example.com",
  "name": "Bob Nominator"
}

# Test voter sync
POST /api/dev/loops-test
{
  "action": "sync-voter",
  "email": "voter@example.com",
  "firstName": "Alice",
  "lastName": "Voter"
}

# Test events
POST /api/dev/loops-test
{
  "action": "send-nomination-event",
  "email": "nominator@example.com",
  "category": "Top Recruiter",
  "type": "person"
}

Configuration Check

GET /api/dev/loops-test

Returns:

  • Loops enabled status
  • API key configuration status
  • Available test endpoints
  • User group mappings

Environment Variables

Required

LOOPS_API_KEY=your_loops_api_key_here

Optional

LOOPS_SYNC_ENABLED=true  # Set to 'false' to disable

Data Flow

Nomination Flow

  1. User submits nomination → Form validation
  2. Nomination saved → Database storage
  3. Nominator synced → Loops "Nominator 2026" group
  4. Event sent → "nomination_submitted" event
  5. Admin approves → Status updated to "approved"
  6. Nominee synced → Loops "Nominees 2026" group (if email available)
  7. Event sent → "nomination_approved" event

Voting Flow

  1. User casts vote → Vote validation
  2. Vote saved → Database storage
  3. Voter synced → Loops "Voter 2026" group
  4. Event sent → "vote_cast" event

Contact Properties

Standard Fields

  • email (required)
  • firstName (parsed from name)
  • lastName (parsed from name)
  • userGroup (Nominees 2026 | Nominator 2026 | Voter 2026)
  • source (WSA 2026 Nominations | WSA 2026 Voting)

Event Properties

All events include:

  • year: '2026'
  • category (award category)
  • source (WSA 2026 Nominations | WSA 2026 Voting)
  • Event-specific properties (nominee details, vote details, etc.)

Benefits

Marketing Automation

  • Segmented email lists by user type
  • Automated follow-up sequences
  • Event-triggered campaigns

Analytics

  • Track engagement by user group
  • Monitor nomination and voting patterns
  • Measure campaign effectiveness

User Experience

  • Personalized communications
  • Relevant content delivery
  • Timely notifications

Status: ✅ COMPLETE

All Loops integration features are fully implemented and tested:

  • ✅ Three user groups properly configured
  • ✅ Contact sync for all user types
  • ✅ Event tracking for key actions
  • ✅ Error handling and validation
  • ✅ Development testing tools
  • ✅ Non-blocking async execution
  • ✅ Comprehensive documentation

The system is ready for production use with Loops email marketing automation.