UIReportReader Microservice

Overview

The UIReportReader microservice provides a secure API for generating and retrieving various types of reports for the Publisher platform's user interface. It serves as the backend service for dashboard reporting, analytics, and data visualization components in the Publisher UI.

Business Purpose

This service enables users to access real-time and historical reporting data through a secure, authenticated API. It supports multiple report types including billing reports, campaign snapshots, account history, and various analytics reports that power the Publisher platform's dashboard and reporting features.

Architecture

Service Type

Deployment: Kubernetes containerized microservice
Trigger: HTTP-triggered Azure Function
Runtime: Node.js
Authentication: JWT-based with role-based access control

Key Components

Handler: Main request processor and report orchestrator
Actions: Individual report generators for different report types
Auth Module: JWT authentication and authorization system
Helpers: Utility functions for blob storage and data processing

Data Flow

graph TD
    A[HTTP Request] --> B[Authentication]
    B --> C[Authorization Check]
    C --> D[Handler Processing]
    D --> E[Action Selection]
    E --> F[SQL Query Generation]
    F --> G[Snowflake Database]
    G --> H[Report Generation]
    H --> I[Event Hub Publishing]
    I --> J[Response Cleanup]
    J --> K[HTTP Response]

    B --> L[JWT Verification]
    C --> M[Role Authorization]
    C --> N[Publisher Authorization]

Dependencies

External Services

Azure Cosmos DB: Publisher database for vendor and campaign data
Snowflake: Data warehouse for report queries
Azure Event Hub: Report event publishing
Azure Blob Storage: Report file storage

NPM Dependencies

@azure/cosmos: Cosmos DB client
jsonwebtoken: JWT token handling
moment: Date/time manipulation
lodash: Utility functions
async: Asynchronous flow control
idgen: ID generation

Configuration

Environment-Specific Configs

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

Key Configuration Parameters

logLevel: Logging verbosity
sasToken: Snowflake SAS token for blob access
jwtSecret: JWT verification secret
Event Hub: Report event hub configuration

API Endpoints

POST /

Generates reports based on the specified action and parameters.

Authentication: Required (Bearer token) Authorization: Roles: admin, user

Request Body:

{
  "action": "GenerateReport|BillingReport|AccountHistory|...",
  "vendorId": "publisher_id",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "groupBys": ["PUBLISHER", "CAMPAIGN"],
  "campaigns": ["campaign1", "campaign2"],
  "products": ["product1", "product2"],
  "industries": ["industry1"],
  "experienceTypes": ["type1"]
}

Response:

{
  "unloadSql": "SQL query (if verbose=true)",
  "publisherkey": "publisher_id",
  "reportData": { /* report results */ }
}

Report Types

Available Reports

GenerateReport: Standard reporting with customizable grouping
GenerateReportInbound: Inbound traffic reporting
BillingReport: Financial and billing data
AccountHistory: Account activity history
RejectionReasons: Campaign rejection analysis
CampaignSnapshotReport: Campaign performance snapshots
AdvertiserSnapshotReport: Advertiser performance data
StatesSnapshotReport: Geographic performance data
ExchangeSnapshotReport: Exchange performance metrics
VendorScoreSnapshotReport: Vendor scoring analytics
AgeSnapshotReport: Age demographic analysis

Report Parameters

Date Range: startDate, endDate
Filtering: campaigns, products, industries, experienceTypes
Grouping: Configurable group-by clauses
Publisher Scope: Vendor-specific or global (admin only)

Authentication & Authorization

JWT Authentication

Bearer token required in Authorization header
Token verification using configured JWT secret
Claims extraction for user context

Role-Based Access Control

admin: Full access to all reports and publishers
user: Limited access based on publisher scope

Publisher Authorization

Users restricted to their assigned publisher organization
Global access (*) allowed for admin users
Vendor scope validation through Cosmos DB

Data Processing

SQL Query Generation

Dynamic SQL generation based on report parameters
Parameterized queries for security
Support for complex filtering and grouping

Blob Storage Integration

Configurable blob file naming patterns
SAS token authentication for Snowflake access
Support for date-based partitioning

Response Processing

SQL query removal in non-verbose mode
Sensitive data filtering
JSON response optimization

Event Publishing

Report Events

Published to 'report' Event Hub
Contains report metadata and execution details
Includes user context and request parameters

Event Structure

{
  "query": "executed_sql_query",
  "reportSource": {
    "serviceName": "UIReportReader",
    "serviceVersion": "version",
    "sourceType": "UI Report"
  },
  "reportConfig": {
    "publisherkey": "publisher_id",
    "reportId": "DynamicUIReport",
    "reportName": "report_type",
    "deliver": false
  },
  "request": {
    "uiRequest": true,
    "body": { /* request body */ },
    "user": "user_name"
  }
}

Error Handling

Authentication Errors

Invalid or missing Bearer token
JWT verification failures
Expired tokens

Authorization Errors

Insufficient role permissions
Publisher scope violations
Invalid vendor access

Processing Errors

Invalid report parameters
Database connection failures
SQL execution errors

Development

Local Setup

Install dependencies: npm install
Configure JWT secret and database connections
Set up Snowflake and Cosmos DB credentials
Run locally using Azure Functions Core Tools

Testing

Test file: test.js
Manual testing capabilities for individual reports
Authentication testing utilities

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

JWT secrets and signing keys
Database connection strings
Snowflake credentials and SAS tokens
Event Hub connection strings

Security Considerations

Token Security

JWT tokens with expiration
Secure secret management
Role-based access enforcement

Data Protection

Publisher data isolation
SQL injection prevention
Sensitive data filtering in responses

Audit Trail

Request logging and monitoring
User activity tracking
Report generation auditing

This service integrates with: - Publisher UI: Primary consumer of report APIs - ReportGenerator: Downstream report processing - DocumentCRUD: Campaign and vendor data source - Authentication Services: User identity and roles