ValidateCampaignHandler Microservice

Overview

The ValidateCampaignHandler microservice provides campaign validation services for the Publisher platform. It validates campaign IDs, checks campaign status and associated vendor information, and returns comprehensive campaign and vendor details for downstream processing systems.

Business Purpose

This service serves as a critical validation gateway for the Publisher platform by: - Validating campaign ID format and existence - Checking campaign active status - Verifying associated vendor information - Providing campaign and vendor metadata for traffic routing - Supporting real-time campaign validation for lead processing

Architecture

Service Type

Deployment: Kubernetes containerized microservice
Trigger: HTTP-triggered Azure Function
Runtime: Node.js
Database: Azure Cosmos DB (DocumentCache collection)

Key Components

Handler: Main request processor and validation orchestrator
DocumentCacheService: Document cache data access layer
PublisherService: Publisher-related data operations (legacy)
Cosmos: Database connectivity and operations

Data Flow

graph TD
    A[HTTP Request] --> B[Query Parameter Validation]
    B --> C{Valid Campaign ID?}
    C -->|No| D[Return Validation Error]
    C -->|Yes| E[Fetch Campaign Document]
    E --> F{Campaign Found?}
    F -->|No| G[Return Campaign Not Found]
    F -->|Yes| H{Campaign Active?}
    H -->|No| I[Return Campaign Paused]
    H -->|Yes| J{Vendor Found?}
    J -->|No| K[Return Vendor Not Found]
    J -->|Yes| L[Process Experience Type]
    L --> M[Return Success Response]

Dependencies

External Services

Azure Cosmos DB: DocumentCache collection for campaign and vendor data
Application Insights: Logging and monitoring

NPM Dependencies

@azure/cosmos: Cosmos DB client
async: Asynchronous flow control
axios: HTTP client for external API calls
http-errors: HTTP error handling
query-string: URL query parameter parsing

Configuration

Environment-Specific Configs

config.js: Development configuration
config.int.js: Integration environment
config.prod.js: Production environment

Key Configuration Parameters

LogLevel: Logging verbosity
PublisherCosmos: Cosmos DB connection configuration

API Endpoints

GET /?campaign={campaignId}

GET /?c={campaignId}

Validates a campaign and returns campaign and vendor information.

Query Parameters: - campaign or c: Campaign ID (required, format: C##### - e.g., C12345)

Response (200 OK):

{
  "errors": [],
  "isValidCampaign": true,
  "vendor": {
    "trackingName": "vendor_tracking_name",
    "isAffiliate": true,
    "id": "vendor_id"
  },
  "campaign": {
    "id": "C12345",
    "trafficType": "traffic_type",
    "experienceType": "fullfunnel",
    "product": "product_name",
    "campaignLevelSource": "source_info"
  }
}

Error Response:

{
  "errors": [
    {
      "error": "Error description"
    }
  ],
  "isValidCampaign": false
}

Validation Logic

Campaign ID Format Validation

Pattern: Must match ^C\d{5}$ (C followed by exactly 5 digits)
Examples: C12345 ✓, C1234 ✗, c12345 ✗, 12345 ✗

Campaign Status Validation

Active Status: Campaign must have status "active"
Paused Campaigns: Returns error if campaign is not active

Vendor Validation

Vendor Existence: Associated vendor must exist in the document
Vendor Information: Returns essential vendor metadata

Experience Type Processing

Split Experience Types: Special handling for "split" experience types
Full Funnel Priority: Prioritizes "fullfunnel" type in split configurations
Fallback Logic: Uses first available type if fullfunnel not found

Data Model

DocumentCache Collection

The service queries the DocumentCache collection with: - ID: "latest" - Partition Key: Campaign ID (e.g., "C12345")

Expected Document Structure

{
  "campaign": {
    "id": "C12345",
    "status": "active",
    "trafficType": "type",
    "experienceType": "split",
    "experienceTypeSplit": [
      {
        "type": "fullfunnel",
        "percentage": 50
      }
    ],
    "product": "product_name",
    "campaignLevelSource": "source"
  },
  "vendor": {
    "id": "vendor_id",
    "trackingName": "tracking_name",
    "isAffiliate": true
  }
}

Error Handling

Validation Errors

Missing Campaign Parameter: Empty or missing campaign/c parameter
Invalid Campaign Format: Campaign ID doesn't match required pattern
Campaign Not Found: No document found for the campaign ID
Campaign Paused: Campaign status is not "active"
Vendor Not Found: Associated vendor information missing

Error Response Format

All errors are returned in a consistent format with: - errors array containing error objects - isValidCampaign set to false - HTTP status 200 (errors are business logic, not HTTP errors)

Performance Characteristics

Response Time

Typical: Sub-second response for cached documents
Database Query: Single Cosmos DB point read operation
Minimal Processing: Simple validation and data transformation

Scalability

Stateless: No server-side session management
Cosmos DB: Scales with configured throughput
Lightweight: Minimal memory and CPU requirements

Security Considerations

Access Control

Anonymous Access: No authentication required (internal service)
Input Validation: Campaign ID format validation prevents injection
Data Exposure: Returns only necessary campaign and vendor metadata

Data Protection

Minimal Data: Only essential information returned
No Sensitive Data: No financial or personal information exposed

Development

Local Setup

Install dependencies: npm install
Configure Cosmos DB connection
Set up environment variables
Run locally using Azure Functions Core Tools

Testing

Test Script: npm test runs test.js
Manual Testing: HTTP requests with various campaign IDs
Validation Testing: Test invalid formats and missing campaigns

Build Process

Webpack configuration for bundling
Terser plugin for code minification
Copy plugin for static assets

Deployment

Kubernetes Configuration

Containerized deployment
Health check endpoints: /live and /ready
Environment-specific function.json configurations

Environment Variables

Cosmos DB connection strings
Application Insights instrumentation key
Logging configuration

Monitoring and Logging

Application Insights

Request/response logging
Error tracking and alerting
Performance monitoring

Custom Logging

Campaign validation attempts
Error conditions and reasons
Processing time metrics

Key Metrics

Validation success/failure rates
Campaign not found rates
Response time distribution
Error type breakdown

This service integrates with: - PixelHandler: Campaign validation for pixel tracking - PostResponder: Campaign validation for lead processing - DocumentCacheHandler: Source of campaign and vendor data - Traffic Routing Services: Consumers of validation results

Troubleshooting

Common Issues

High "Campaign Not Found" Rates: Check DocumentCache data synchronization
Format Validation Failures: Verify campaign ID format requirements
Cosmos DB Connection Issues: Check connection strings and permissions
Performance Issues: Monitor Cosmos DB throughput and scaling

Monitoring Points

Campaign validation success rates
Document cache hit rates
Response time percentiles
Error distribution by type

Usage Examples

Valid Campaign Request

GET /?campaign=C12345

Alternative Parameter Format

GET /?c=C67890

Invalid Campaign Format

GET /?campaign=12345
Response: {"errors": [{"error": "campaign does not match correct pattern: 12345"}], "isValidCampaign": false}

Campaign Not Found

GET /?campaign=C99999
Response: {"errors": [{"error": "Campaign not found for campaign ID C99999"}], "isValidCampaign": false}

Limitations

Current Constraints

Single campaign validation per request
No bulk validation capabilities
No campaign creation or modification
Limited to active campaign validation only

Potential Enhancements

Batch campaign validation
Campaign status history
Detailed validation reasons
Campaign metadata caching
Performance optimization for high-volume requests