Integration and API Spec

Integration and API Spec

Quality Control Checklist Automation

Acts as the entry point for all inspection data. The automation platform listens for new form submissions via the Google Forms trigger (polling the linked Google Sheet responses tab or via Apps Script webhook relay). Each submission must carry a batch or unit identifier, inspector name, timestamp, and one response row per checklist item.

// Output to QC Review Agent
form_response {
  batch_id: string,
  inspector_name: string,
  inspection_type: string,
  inspection_date: ISO8601 string,
  checklist_items: [ { item_id: string, label: string, result: 'pass'|'fail'|'na' } ],
  raw_row_index: integer
}

Serves as the central data store for inspection records and corrective actions. Two tables are required: QC_Log (one record per inspection submission) and Corrective_Actions (linked to QC_Log via a linked record field). Both agents read from and write to this base. The Reporting Agent queries QC_Log with date filters; the QC Review Agent creates records in both tables.

// Input from QC Review Agent (write to QC_Log)
POST /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_TABLE_QC_LOG}
fields: { batch_id, inspector_name, inspection_type, inspection_date,
          failed_items (JSON string), severity, status: 'Open' }

// Input from QC Review Agent (write to Corrective_Actions)
POST /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_TABLE_CORRECTIVE_ACTIONS}
fields: { linked_inspection: [record_id], defect_description,
          severity, assignee (collaborator user_id), due_date, status: 'Open' }

// Input from Reporting Agent (read QC_Log with filter)
GET /v0/{AIRTABLE_BASE_ID}/{AIRTABLE_TABLE_QC_LOG}
  ?filterByFormula=AND(IS_AFTER({inspection_date}, '{7_days_ago}'),
                       IS_BEFORE({inspection_date}, '{today}'))
  &fields[]=batch_id,inspection_type,severity,status,inspector_name,inspection_date

Used by the QC Review Agent to send two distinct message types: a channel alert to the operations manager channel when a critical or major failure is detected, and a direct message to the assignee when a corrective action is created and assigned. The Slack app must be installed in the workspace with the required bot scopes before build.

// Output: channel alert (chat.postMessage)
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
body: {
  channel: SLACK_OPS_CHANNEL_ID,
  text: 'QC Failure Alert: {batch_id}',
  blocks: [ header, section(failed_items, severity),
            section(assignee, due_date), actions(link_to_ca) ]
}

// Output: DM to assignee (chat.postMessage)
POST https://slack.com/api/chat.postMessage
body: {
  channel: {assignee_slack_user_id},
  text: 'You have been assigned a corrective action for {batch_id}.',
  blocks: [ section(defect_description, due_date, ca_link) ]
}

Used exclusively by the Reporting Agent to send the weekly QC summary email every Monday at 07:00. The email is sent from a designated operations sender address to a management distribution list. The message is constructed from an HTML template with placeholder substitution performed by the automation platform before sending.

// Output: weekly summary email (Gmail API)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer {access_token}
body (RFC 2822 encoded, base64url):
  From: ops-reports@[YourCompany.com]
  To: {GMAIL_RECIPIENT_LIST}
  Subject: Weekly QC Summary - w/c {week_label}
  Content-Type: text/html; charset=utf-8
  [rendered HTML from template with substituted placeholders]

// Credential store contents (automation platform encrypted store)
// Key                          Type            Used by

GOOGLE_OAUTH_CLIENT_ID          OAuth client    Google Forms, Gmail
GOOGLE_OAUTH_CLIENT_SECRET      OAuth secret    Google Forms, Gmail
GOOGLE_FORMS_REFRESH_TOKEN      OAuth token     Google Forms (Sheets polling)
GMAIL_REFRESH_TOKEN             OAuth token     Gmail send
GMAIL_SENDER_ADDRESS            String          Gmail send (From address)
GMAIL_RECIPIENT_LIST            String          Gmail send (To, comma-separated)

AIRTABLE_PAT                    PAT token       All Airtable reads and writes
AIRTABLE_BASE_ID                String          All Airtable requests
AIRTABLE_TABLE_QC_LOG           String          QC Review Agent, Reporting Agent
AIRTABLE_TABLE_CORRECTIVE_ACTIONS String        QC Review Agent

SLACK_BOT_TOKEN                 OAuth token     Slack channel alert, Slack DM
SLACK_OPS_CHANNEL_ID            String          Slack channel alert

FORMS_WEBHOOK_SECRET            HMAC secret     Webhook signature validation

// Platform config (non-secret, environment variables)
REPORT_TIMEZONE                 String          'Australia/Sydney' (adjust per client)
SEVERITY_RULES_JSON             JSON string     QC Review Agent classification logic
ASSIGNEE_CATEGORY_MAP_JSON      JSON string     Failure category -> Airtable user ID map
CA_DUE_DATE_BUSINESS_DAYS       Integer         2 (days after inspection date)
AIRTABLE_BASE_URL               String          'https://airtable.com/{AIRTABLE_BASE_ID}'
GMAIL_EMAIL_TEMPLATE_HTML       String          Full HTML template with placeholders