Integration and API Spec

Integration and API Spec

Risk Register Management

Provides the new-risk intake trigger. Each form submission creates a new row event that the orchestration layer listens to via a push notification subscription. The form structure must match the field mapping defined in Section 03.

// Output payload (on new response)
{
  "formId": "<FORMS_FORM_ID>",
  "responseId": "<string>",
  "createTime": "<ISO 8601>",
  "answers": {
    "<fieldId_title>": { "textAnswers": { "answers": [{ "value": "<risk_title>" }] } },
    "<fieldId_description>": { "textAnswers": { "answers": [{ "value": "<risk_description>" }] } },
    "<fieldId_category>": { "textAnswers": { "answers": [{ "value": "<risk_category>" }] } },
    "<fieldId_submitter_email>": { "textAnswers": { "answers": [{ "value": "<email>" }] } },
    "<fieldId_submitter_name>": { "textAnswers": { "answers": [{ "value": "<name>" }] } }
  }
}

Acts as the central risk register. All three agents read from and write to the same spreadsheet. The register schema is fixed; column order must not be altered after go-live without a coordinated schema migration.

// Write new risk row (Agent 1 -> Sheets)
POST /v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values/{SHEETS_SHEET_NAME}!A:T:append
Body: { "values": [[risk_id, risk_title, risk_description, risk_category,
  submitter_email, submitter_name, date_raised, owner_email, review_due_date,
  likelihood_proposed, impact_proposed, risk_score_proposed, "", "", "",
  "Pending", "", "", "false", ""]] }

// Update confirmed scores (Agent 2 -> Sheets)
POST /v4/spreadsheets/{SHEETS_SPREADSHEET_ID}/values:batchUpdate
Body: { "valueInputOption": "RAW", "data": [
  { "range": "<row_range>", "values": [[likelihood_confirmed, impact_confirmed,
    risk_score_confirmed, "Confirmed", reviewer_name, reviewer_timestamp]] }
]}

Used exclusively by Agent 2 to deliver owner review prompts and 48-hour overdue nudges. Messages are sent to individual users by email lookup via the Slack users.lookupByEmail method before posting.

// Review prompt message (Agent 2 -> Slack)
POST https://slack.com/api/chat.postMessage
Headers: { "Authorization": "Bearer <SLACK_BOT_TOKEN>" }
Body: {
  "channel": "<resolved_user_id>",
  "text": "Risk review required: <risk_title> (ID: <risk_id>). Please confirm or update your likelihood and impact score by <review_due_date>. Register link: <SHEETS_ROW_URL>"
}

Used by Agent 3 to create the monthly leadership risk report as a new Notion page inside a designated parent database. Each month's report is a discrete page; the database view shows all monthly reports in chronological order.

// Create monthly report page (Agent 3 -> Notion)
POST https://api.notion.com/v1/pages
Headers: { "Authorization": "Bearer <NOTION_API_TOKEN>",
           "Notion-Version": "2022-06-28" }
Body: {
  "parent": { "database_id": "<NOTION_PARENT_DATABASE_ID>" },
  "properties": {
    "Report Month": { "title": [{ "text": { "content": "<YYYY-MM>" } }] },
    "Status": { "select": { "name": "Draft" } },
    "Risk Count": { "number": <total_risk_count> },
    "Critical Count": { "number": <critical_count> },
    "Created By": { "rich_text": [{ "text": { "content": "FullSpec Automation" } }] },
    "Distribution Sent": { "checkbox": false }
  }
}

Used by Agents 2 and 3 for escalation emails and report distribution respectively. All outbound email is sent from a designated automation sender address configured in Google Workspace. Replies from recipients are not processed by the automation.

// Escalation email (Agent 2 -> Gmail)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Headers: { "Authorization": "Bearer <GOOGLE_SHEETS_TOKEN>" }
Body: {
  "raw": "<base64url(RFC2822 MIME message)>"
}
// MIME structure:
// From: <GMAIL_SENDER_ADDRESS>
// To: <GMAIL_RISK_MANAGER_EMAIL>
// CC: <dept_head_email resolved from GMAIL_DEPT_HEAD_MAP>
// Subject: [ACTION REQUIRED] Overdue Risk: <risk_title> (ID: <risk_id>)
// Body: risk_title, risk_id, owner_email, review_due_date, risk_score_proposed, register_url

// Credential store contents (orchestration platform environment variables)
// Google (shared service account, domain-wide delegation enabled)
GOOGLE_SERVICE_ACCOUNT_JSON   = <base64-encoded service account JSON key>
GOOGLE_IMPERSONATION_EMAIL    = risk-automation@[YourCompany.com]

// Google Forms
FORMS_FORM_ID                 = <Google Forms form ID string>
FORMS_WEBHOOK_SECRET          = <random 32-char secret for X-Goog-Channel-Token>
FORMS_WATCH_ID                = <watch ID returned by Forms API, refreshed every 7 days>

// Google Sheets
SHEETS_SPREADSHEET_ID         = <Google Sheets spreadsheet ID string>
SHEETS_SHEET_NAME             = RiskRegister
SHEETS_ARCHIVE_SHEET_NAME     = Archive_Log
SHEETS_RISK_ID_NAMED_RANGE    = RiskIDCounter

// Slack
SLACK_BOT_TOKEN               = xoxb-<your-slack-bot-token>
SLACK_ESCALATION_CHANNEL_ID   = <Slack channel ID for escalation summaries>

// Notion
NOTION_API_TOKEN              = secret_<your-notion-integration-token>
NOTION_PARENT_DATABASE_ID     = <Notion database ID for monthly reports>
NOTION_REPORT_TEMPLATE_PAGE_ID= <Notion page ID used as structural template>

// Gmail
GMAIL_SENDER_ADDRESS          = risk-automation@[YourCompany.com]
GMAIL_RISK_MANAGER_EMAIL      = <risk manager email address>
GMAIL_STAKEHOLDER_LIST        = <comma-separated leadership distribution list>
GMAIL_DEPT_HEAD_MAP           = { "Operational": "ops-head@[YourCompany.com]",
                                  "Financial": "finance-head@[YourCompany.com]",
                                  "Compliance": "compliance-head@[YourCompany.com]",
                                  "Strategic": "ceo@[YourCompany.com]" }

// Orchestration
CRITICAL_SCORE_THRESHOLD      = 15
ESCALATION_WINDOW_HOURS       = 48
REVIEW_CYCLE_DAYS             = 14
MONTHLY_REPORT_RUN_TIME_UTC   = 07:00