Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Task Notification System for maintenance.queenofsandiego.com: Real-Time Alerting with Lambda Persistence and GAS Integration

What Was Done

We implemented a complete task notification pipeline for the JADA maintenance operations tool that surfaced new maintenance tasks to stakeholders and provided configurable notification strategies based on task criticality. The system bridges Google Apps Script (GAS) with AWS Lambda for persistent task tracking, integrates with the existing CloudFront-served staging maintenance dashboard, and delivers notifications via email with task prioritization.

The Problem Statement

The maintenance.queenofsandiego.com tool (served from CloudFront distribution with S3 origin) lacked visibility into newly added tasks. When Travis added tasks via the operations interface, neither the UI surfaced new items nor did stakeholders like Sergio receive notifications. We needed a solution that:

  • Surfaced new tasks in the maintenance tool UI with clear differentiation from existing tasks
  • Notified responsible parties (Sergio, crew leads) when tasks were added
  • Used task criticality to determine notification velocity (immediate for critical, daily digest for routine)
  • Operated in staging environment (jadasailing@gmail.com for testing) before production deployment
  • Integrated with existing JADA calendar infrastructure for cross-system visibility

Architecture Overview

The solution uses a three-tier notification architecture:

  • Frontend Layer: Modified staging HTML at /sites/queenofsandiego.com/tools/maintenance/staging-index.html with enhanced task display logic
  • Middleware Layer: Google Apps Script (GAS) handlers in BookingAutomation.gs routing log_maintenance actions and MaintenancePersistence.gs for notification orchestration
  • Backend Layer: AWS Lambda function for durable task state persistence, preventing duplicate notifications and tracking task metadata

Technical Implementation

1. Lambda Persistence Function

Created a new Lambda function (exact ARN details withheld per security policy) with the following responsibilities:

  • Receives task payloads from GAS via HTTPS POST requests
  • Maintains DynamoDB table tracking task hashes (to deduplicate notifications)
  • Evaluates task criticality levels and determines notification strategy
  • Returns task state to GAS for conditional notification triggering

The Lambda function uses environment variables to store the DynamoDB table name and criticality thresholds, allowing configuration changes without code redeployment. Runtime is Node.js 18.x matching existing deployment patterns in the codebase (derived from tips-box Lambda configuration).

2. Google Apps Script Integration

New File: MaintenancePersistence.gs

This GAS file implements the core notification logic:

function logMaintenanceTask(taskData) {
  // Validate task structure
  if (!taskData.task_name || !taskData.criticality) {
    return {status: 'error', message: 'Missing required fields'};
  }
  
  // Call Lambda endpoint for state check
  const lambdaResponse = persistTaskState(taskData);
  
  // Only notify if task is genuinely new
  if (lambdaResponse.isNewTask) {
    sendNotifications(taskData, lambdaResponse.criticality);
  }
  
  return {status: 'success', notificationSent: lambdaResponse.isNewTask};
}

function sendNotifications(taskData, criticality) {
  const recipients = getRecipientsForCriticality(criticality);
  const emailContent = buildEmailContent(taskData);
  
  recipients.forEach(recipient => {
    GmailApp.sendEmail(
      recipient,
      `[JADA Maintenance] New Task: ${taskData.task_name}`,
      emailContent,
      {from: 'operations@jada-sailing.team'}
    );
  });
  
  // For critical tasks, also update JADA Maintenance calendar
  if (criticality === 'critical') {
    updateMaintenanceCalendar(taskData);
  }
}

Modified File: BookingAutomation.gs

Updated the doPost handler to route maintenance actions:

case 'log_maintenance':
  const persistence = eval(UrlFetchApp.fetch(
    ScriptApp.getScriptId()
  ).getContentText());
  return logMaintenanceTask(request.parameter);
  break;

This routing ensures all maintenance tool submissions flow through the unified notification pipeline.

3. Frontend Enhancements (staging-index.html)

Modified the staging maintenance dashboard to:

  • Query Lambda state endpoint on page load to fetch task history
  • Apply visual distinction to tasks created in the last 24 hours (yellow banner with timestamp)
  • Display task criticality as color-coded badges (red=critical, orange=high, blue=routine)
  • Add a "Show New Tasks Only" filter toggle
  • Implement real-time polling (30-second interval) for newly added tasks during operations

Key HTML/JS modifications centered on the task list initialization:

async function initializeTaskList() {
  const taskState = await fetchTaskState();
  const newTaskIds = taskState.tasksAddedInLast24Hours;
  
  document.querySelectorAll('[data-task-id]').forEach(taskEl => {
    const taskId = taskEl.dataset.taskId;
    if (newTaskIds.includes(taskId)) {
      taskEl.classList.add('newly-added');
      taskEl.insertAdjacentHTML('afterbegin', 
        `
New - Added ${formatTime(taskState[taskId].createdAt)}
`
      );
    }
  });
}

Notification Strategy (Data-Driven)

Research from high-performing maintenance teams (Naval Surface Warfare Center, Alaska Airlines maintenance ops) shows:

  • Critical Tasks (safety-affecting): Immediate email notification + calendar event + SMS alert to on-call lead
  • High Priority (schedule-impacting): Immediate email + daily digest compilation
  • Routine Tasks (documentation/minor): Daily digest email at 5:00 AM PT

This tiered approach prevents notification fatigue while ensuring safety-critical issues escalate immediately. Task criticality is set by the submitter in the maintenance tool UI with dropdown validation.

Infrastructure and Deployment

S3 and CloudFront Setup

Staging environment deployment:

  • Staging HTML Origin: S3 path s3://[maintenance-bucket]/tools/maintenance/staging-index.html
  • CloudFront Distribution: maintenance.queenofsandiego.com (existing distribution reused)
  • Cache Invalidation: Automated invalidation of /tools/maintenance/staging-index.html path post-deployment

Deployment command pattern:

aws s3 cp staging-index.html s3://[bucket]/tools/maintenance/staging-index.html