Skip to content

IRIS Daily Report

An automated AI-powered reporting system that generates daily strategic reports for the MEWAKA teacher development programme in Tanzania. The workflow fetches data from Google Sheets, processes it through an AI agent, and delivers personalized reports to programme stakeholders via email.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

Based on the workflow implementation, this system serves the MEWAKA programme (Mafunzo Endelevu kwa Walimu Kazini) - a teacher development initiative that trains Business Studies teachers in Tanzanian secondary schools. The workflow generates daily reports for two key stakeholders:

  • Mercy Idindili (Data Analytics Manager) - receives reports scoped to Dar es Salaam and Pwani regions
  • Nemes Umela (Senior Field Coordinator) - receives reports scoped to Morogoro and Dodoma regions

The reports provide diagnostic analysis of teacher training progress, lesson quality metrics, school visits, and photo evidence submissions to help programme managers make data-driven decisions.

How It Works

  1. Scheduled Trigger: The workflow runs automatically Monday-Friday at 9:00 AM East Africa Time
  2. Data Collection: Fetches data from 15 tabs in a Google Sheets workbook using a single batch API call
  3. Data Processing: Aggregates raw sheet data into structured metrics, calculating completion rates, regional breakdowns, and quality indicators
  4. Token Validation: Ensures the processed data doesn't exceed AI model limits (60,000 token ceiling)
  5. AI Analysis: An AI agent (Claude Sonnet 4.6) analyzes the data and generates two personalized reports following strict formatting and content guidelines
  6. Report Parsing: Extracts the structured JSON output containing both reports
  7. Format Conversion: Converts markdown reports to HTML for email rendering
  8. Email Delivery: Sends personalized reports to each recipient via Gmail

Workflow Diagram

graph TD
    A[Schedule Mon-Fri 09:00 EAT] --> C[Fetch All Tabs batchGet]
    B[Test Trigger Webhook] --> C
    C --> D[Pre-Aggregate]
    D --> E[Token Sanity Check]
    E --> F[IRIS AI Agent]
    G[OpenRouter Chat Model] --> F
    H[Reports Output Parser] --> F
    F --> I[Extract Reports]
    I --> J[Send Report Gmail]

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style F fill:#f3e5f5
    style J fill:#e8f5e8

Triggers

  • Primary: Schedule trigger runs Monday-Friday at 9:00 AM East Africa Time (0 9 * * 1-5)
  • Secondary: Webhook trigger at /webhook/iris-test for manual testing (POST requests)

Nodes Used

Node Type Purpose
Schedule Trigger Automated daily execution on weekdays
Webhook Manual testing trigger
HTTP Request Batch fetch from Google Sheets API
Code (Pre-Aggregate) Process raw sheet data into structured metrics
Code (Token Sanity Check) Validate payload size before AI processing
LangChain AI Agent Generate reports using Claude Sonnet 4.6
OpenRouter Chat Model AI language model provider
Structured Output Parser Parse AI-generated JSON reports
Code (Extract Reports) Convert markdown to HTML and format for email
Gmail Send personalized reports to recipients

External Services & Credentials Required

Google Sheets OAuth2

  • Purpose: Read-only access to MEWAKA Tracker workbook
  • Scope: Read-only permissions required
  • Workbook ID: 1ukMYNKrPLq6fWDpa5qan1Mn2OupAO-O0tbfLkfol_q8
  • Note: Mercy must share the workbook with the authenticated Google account

OpenRouter API

  • Purpose: Access to Claude Sonnet 4.6 model
  • Model: anthropic/claude-sonnet-4.6
  • Configuration: Max 32,000 tokens, temperature 0.2

Gmail OAuth2

  • Purpose: Send HTML reports via email
  • Configuration: Sender name set to "IRIS"
  • Status: Currently disabled pending project lead approval

Environment Variables

No specific environment variables are documented in the workflow, but the Gmail node references a potential IRIS_LIVE_SEND environment variable for enabling live email sending.

Data Flow

Input

  • Source: Google Sheets workbook with 15 tabs containing MEWAKA programme data
  • Tabs: Summary tables, lesson observations, coaching calls, school lists, teacher data, student surveys, stakeholder engagement, photo submissions

Processing

  • Raw sheet data → Structured metrics with completion rates, regional breakdowns, quality indicators
  • Aggregated data → AI analysis following strict reporting guidelines
  • AI output → Structured JSON with two personalized reports

Output

  • Format: HTML emails with embedded styling
  • Recipients: Two personalized reports sent to different stakeholders
  • Content: Diagnostic analysis, metrics tables, flags & risks, next steps
  • Scope: Regional filtering (Dar es Salaam/Pwani vs Morogoro/Dodoma)

Error Handling

  • Retry Logic: HTTP Request node configured with 3 retry attempts and 5-second delays
  • Token Limits: Hard ceiling of 60,000 tokens with error throwing if exceeded
  • Data Validation: Error handling for missing or malformed AI output
  • Fallback Parsing: Multiple attempts to extract reports from AI response

Known Limitations

  • Gmail sending is intentionally disabled pending project lead approval
  • Token limit of 60,000 may constrain data processing for very large datasets
  • Regional scoping limited to predefined region pairs
  • Requires manual credential setup and workbook sharing
  • Dependent on external services (Google Sheets, OpenRouter, Gmail) availability

No related workflows are mentioned in the provided context.

Setup Instructions

  1. Import Workflow: Import the JSON workflow definition into your n8n instance

  2. Configure Google Sheets Access:

    • Create Google Sheets OAuth2 credentials with read-only scope
    • Have Mercy share workbook 1ukMYNKrPLq6fWDpa5qan1Mn2OupAO-O0tbfLkfol_q8 with the authenticated account
    • Attach credentials to the "Fetch All Tabs (batchGet)" node

  3. Setup OpenRouter API:

    • Obtain OpenRouter API credentials
    • Attach to "OpenRouter Chat Model" node
    • Verify access to anthropic/claude-sonnet-4.6 model

  4. Configure Gmail (Optional):

    • Create Gmail OAuth2 credentials
    • Attach to "Send Report (Gmail)" node
    • Important: Keep the Gmail node disabled until project lead approves live sending

  5. Set Timezone: Ensure workflow timezone is set to "Africa/Nairobi"

  6. Test Setup:

    • Use the webhook trigger at /webhook/iris-test for testing
    • Monitor execution logs to verify data processing
    • Check AI agent output before enabling email sending

  7. Activate: Enable the workflow only after all credentials are configured and tested