Skip to content

IRIS Daily Report

An automated AI-powered reporting system that generates daily analytical reports for the MEWAKA teacher development programme in Tanzania. IRIS (Internal Reporting & Intelligence System) reads data from Google Sheets, processes it through Claude AI, and delivers personalized reports to programme stakeholders via email.

Purpose

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

How It Works

  1. Scheduled Trigger: Runs automatically Monday-Friday at 9:00 AM East Africa Time, or can be triggered manually via webhook
  2. Data Collection: Fetches all 14 tabs from the MEWAKA Google Sheets workbook using a single batch API call
  3. Data Processing: Aggregates and pre-processes the raw sheet data into structured metrics and summaries
  4. Token Validation: Ensures the processed data doesn't exceed AI model token limits
  5. AI Analysis: Sends the aggregated data to Claude AI (via OpenRouter) to generate two personalized reports
  6. Report Parsing: Extracts the structured JSON reports from the AI response
  7. Format Conversion: Converts markdown reports to HTML for email rendering
  8. Email Delivery: Sends personalized reports to Mercy Idindili and Nemes Umela 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

Trigger

  • Primary: Schedule trigger runs Monday-Friday at 9:00 AM East Africa Time
  • Secondary: Manual webhook trigger at /webhook/iris-test for testing purposes

Nodes Used

Node Type Node Name Purpose
Schedule Trigger Schedule (Mon-Fri 09:00 EAT) Automated daily execution
Webhook Test Trigger (Webhook) Manual testing trigger
HTTP Request Fetch All Tabs (batchGet) Retrieves data from Google Sheets
Code Pre-Aggregate Processes and structures raw sheet data
Code Token Sanity Check Validates data size for AI processing
LangChain Agent IRIS AI Agent Generates analytical reports using AI
LangChain Chat Model OpenRouter Chat Model Claude AI model interface
Output Parser Reports Output Parser Structures AI response into JSON
Code Extract Reports Converts markdown to HTML
Gmail Send Report (Gmail) Delivers reports via email
Sticky Note SETUP REQUIRED Setup instructions
Sticky Note DO NOT ENABLE Warning about disabled features

External Services & Credentials Required

Google Sheets OAuth2

  • Scope: Read-only access to Google Sheets
  • Required for: Fetching data from MEWAKA workbook
  • Workbook ID: 1ukMYNKrPLq6fWDpa5qan1Mn2OupAO-O0tbfLkfol_q8
  • Note: Mercy must share the workbook with the authenticated Google account

OpenRouter API

  • Service: OpenRouter API for Claude access
  • Model: anthropic/claude-sonnet-4-6
  • Required for: AI report generation

Gmail OAuth2

Environment Variables

No specific environment variables are documented in the workflow configuration. The workflow relies on n8n's credential system for authentication.

Data Flow

Input Data

  • 14 Google Sheets tabs containing MEWAKA programme data:
    • Summary tables
    • All Lesson Observed
    • Virtual Coaching calls (T1/2026 and T2/2025)
    • Passbook Milestone
    • School List-Cohort1
    • Student Survey
    • Teacher List Updated-Cohort1
    • WEO engagement data
    • Stakeholder Engagement
    • SLP data
    • Chatbot Submissions
    • All teachers trained roster

Processing

  • Raw sheet data converted to structured JSON
  • Metrics aggregated and pre-calculated
  • Data validated for AI token limits (60,000 token ceiling)
  • Regional scoping applied for Business Mentor data

Output

  • Two personalized HTML email reports
  • Regional scope differs by recipient:
    • Mercy: Dar es Salaam and Pwani regions
    • Nemes: Morogoro and Dodoma regions

Error Handling

  • Retry Logic: HTTP Request node has 3 retry attempts with 5-second delays
  • Token Validation: Hard ceiling of 60,000 tokens prevents AI model overload
  • Report Validation: Ensures AI generates exactly 2 reports before proceeding
  • Fallback Parsing: Multiple attempts to extract reports from AI response

Known Limitations

  • Gmail sending is currently disabled in production (node is marked as disabled)
  • Workflow depends on specific Google Sheets structure and column names
  • AI model costs accumulate with each execution
  • Regional scoping limits Business Mentor visibility per recipient

No related workflows are mentioned in the provided context.

Setup Instructions

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

  2. Configure Google Sheets Credential:

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

  3. Configure OpenRouter Credential:

    • Create OpenRouter API credential
    • Attach to "OpenRouter Chat Model" node
    • Ensure access to anthropic/claude-sonnet-4-6 model

  4. Configure Gmail Credential:

    • Create Gmail OAuth2 credential
    • Attach to "Send Report (Gmail)" node
    • Important: Keep the Gmail node disabled until approved for live sending

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

  6. Test Setup:

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

  7. Enable Production:

    • Only enable the Gmail node after project lead approval
    • Activate the workflow for scheduled execution