Integration and API Spec

Integration and API Spec

OKR and Goal Tracking Automation

Slack is used by both agents: Agent 1 sends structured update request messages and timed reminders to team leads; Agent 2 posts the formatted leadership digest to a designated channel. A custom Slack App must be created in the workspace and installed with the scopes below. Workflow Builder is not used; the automation platform drives all message delivery directly via the Slack Web API.

// Outbound (Agent 1 -> team lead DM)
POST https://slack.com/api/chat.postMessage
{ channel: <user_id>, text: <structured_update_prompt>, blocks: <Block Kit JSON> }

// Outbound (Agent 2 -> leadership channel)
POST https://slack.com/api/chat.postMessage
{ channel: SLACK_LEADERSHIP_CHANNEL_ID, text: <digest_summary>, blocks: <digest_Block_Kit_JSON> }

// Inbound event (optional reaction confirmation)
POST <platform_inbound_url>  <- Slack Event payload
{ type: 'event_callback', event: { type: 'reaction_added', user: <user_id>, reaction: 'white_check_mark' } }

Google Sheets is the master OKR data store. Agent 1 writes submitted key result values to the sheet; Agent 2 reads those values to calculate progress percentages, apply RAG thresholds, and identify at-risk objectives. A dedicated service account is used for all read and write operations. The sheet schema must be finalised before the build starts (defined during the Discovery and OKR Structure Setup stage).

// Agent 1 write (response submission)
PUT https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values/{SHEET_RESPONSES}!A{row}:H{row}
{ values: [[cycle_date, team_lead_id, objective_id, kr_id, current_value, target_value, submitted_at, notes]] }

// Agent 2 read (progress calculation input)
GET https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values/{SHEET_RESPONSES}!A:H
-> returns ValueRange { values: [[...row...], ...] }

// Control flag write (Agent 1 signals window close)
PUT https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values/Control!B2
{ values: [['TRUE']] }

Notion is used exclusively by Agent 2 to create a new cycle summary page, populate it with the progress table and at-risk flags, and archive it under the designated parent page. A Notion internal integration token is used. The parent page and database IDs must be captured during setup and stored in the credential store.

// Create cycle summary page
POST https://api.notion.com/v1/pages
Authorization: Bearer {NOTION_INTEGRATION_TOKEN}
Notion-Version: 2022-06-28
{ parent: { page_id: NOTION_PARENT_PAGE_ID },
  properties: { title: [{ text: { content: 'OKR Cycle Summary - {cycle_date}' } }] },
  children: [ <block array: heading, progress table, at-risk list, sheet link> ] }

// Append at-risk block if flagged items > 0
PATCH https://api.notion.com/v1/blocks/{page_id}/children
{ children: [ { type: 'callout', callout: { icon: { emoji: '🔴' }, rich_text: [...] } } ] }

Google Workspace is used by Agent 1 as a scheduling reference to align the cycle trigger with confirmed OKR cadence dates, and as an email fallback channel for any team lead who cannot be reached via Slack DM. Gmail API access is required for the fallback path only; Calendar API is read-only for trigger alignment.

// Email fallback send (Gmail API)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer {google_access_token}
{ raw: <base64url-encoded RFC 2822 message> }
  To: {team_lead_email}
  From: {GOOGLE_FALLBACK_EMAIL_FROM}
  Subject: 'OKR Update Required - {cycle_date}'
  Body: <plain text update request with key result list>

// Credential store entries (encrypted at rest, referenced by key name only)

SLACK_BOT_TOKEN                  // xoxb-... Bot User OAuth Token from Slack App
SLACK_SIGNING_SECRET             // From Slack App Basic Information page
SLACK_LEADERSHIP_CHANNEL_ID      // Channel ID (not name) for leadership digest
SLACK_TEAM_LEAD_USER_IDS         // JSON array: ["U0123ABC", "U0456DEF", ...]

GOOGLE_SERVICE_ACCOUNT_JSON      // Full JSON key file for Google service account
GOOGLE_SPREADSHEET_ID            // From the master OKR Google Sheet URL
GOOGLE_SPREADSHEET_URL           // Full https://docs.google.com/spreadsheets/d/... URL
GOOGLE_FALLBACK_EMAIL_FROM       // e.g. okr-automation@[yourdomain].com
GOOGLE_CALENDAR_ID               // Optional; only if calendar-based validation is active

NOTION_INTEGRATION_TOKEN         // Internal Integration Token from Notion integrations page
NOTION_PARENT_PAGE_ID            // UUID of the OKR archive parent page in Notion

// Workflow-level environment variables (non-secret, editable without credential rotation)

CYCLE_CRON_EXPRESSION            // e.g. '0 9 * * 1' for every Monday 09:00
SUBMISSION_WINDOW_HOURS          // e.g. 48  (hours before window closes)
REMINDER_1_DELAY_HOURS           // e.g. 24
REMINDER_2_DELAY_HOURS           // e.g. 48
SHEET_RESPONSES                  // Tab name, default: 'Cycle_Responses'
SHEET_CONTROL                    // Tab name, default: 'Control'
SHEET_ARCHIVE_PREFIX             // Prefix for archived tabs, default: 'Archive_'
GREEN_MIN_PCT                    // RAG threshold: >= this value = GREEN, e.g. 70
AMBER_MIN_PCT                    // RAG threshold: >= this value = AMBER, < GREEN, e.g. 40
NOTION_PAGE_TEMPLATE_PROPERTIES  // JSON: { 'Cycle Date': 'date', 'Status': 'select', ... }
KR_TARGET_VALUES                 // JSON map: { 'kr_001': 100, 'kr_002': 50, ... }