Integration and API Spec

Integration and API Spec

End-of-day / Shift Handover

Used by Agent 1 (Handover Collector Agent) to present staff with a structured end-of-shift data entry form. Responses are captured automatically in the linked Google Sheet via the Forms native response destination. The orchestration layer does not call the Forms API directly for submission; it reads resulting data from Sheets.

Used by both agents. Agent 1 appends staff form responses as new rows and writes a 'log_ready' status flag. Agent 2 reads the completed log to compile the handover report. The Sheet also serves as the manual shift-close trigger surface: a team lead can write 'CLOSE' into a designated trigger cell to fire the workflow outside the scheduled time.

Used by Agent 1 to send the end-of-shift prompt and Google Forms link to outgoing staff, and by Agent 2 to post the compiled handover report to the designated operations channel. Both interactions use the Slack Web API via a single Bot token scoped to the workspace.

Used by Agent 2 (Handover Compiler Agent) to file the finalised handover report as a new page inside the designated Notion database. Each page corresponds to a single shift and is dated and tagged automatically. This creates the searchable audit trail that replaces the manual Notion filing step.

Used by Agent 2 to email the compiled handover report to the incoming shift manager and any on-call contacts registered for that shift. The email is sent from a designated sender address using OAuth-authorised access. No SMTP relay or third-party mail service is required.

Used by Agent 2 to raise an on-call escalation alert when the compiled handover report contains one or more unresolved incidents or high-priority equipment flags. The alert is created via the PagerDuty Events API v2, targeting the configured service integration key.

// Google (shared OAuth service account or per-user refresh tokens)
GOOGLE_OAUTH_CLIENT_ID          = '<oauth_client_id>'
GOOGLE_OAUTH_CLIENT_SECRET      = '<oauth_client_secret>'
GOOGLE_OAUTH_REFRESH_TOKEN      = '<refresh_token_for_service_account_or_sender_user>'

// Google Forms
GFORMS_FORM_ID                  = '<google_forms_form_id>'

// Google Sheets
GSHEETS_LOG_SHEET_ID            = '<spreadsheet_id>'
GSHEETS_RESPONSES_TAB_NAME      = 'shift_responses'
GSHEETS_CONTROL_TAB_NAME        = 'control'
GSHEETS_LOG_READY_CELL          = 'control!B3'
GSHEETS_COLUMN_MAP              = '<JSON string mapping Form question IDs to Sheet column letters>'

// Slack
SLACK_BOT_TOKEN                 = 'xoxb-<token>'
SLACK_SIGNING_SECRET            = '<signing_secret_for_future_webhook_validation>'
SLACK_OPS_CHANNEL_ID            = 'C<channel_id>'
SLACK_FORM_LINK                 = 'https://forms.gle/<form_short_url>'
SLACK_PROMPT_TEMPLATE_ID        = 'shift_end_prompt_v1'

// Notion
NOTION_INTEGRATION_TOKEN        = 'secret_<token>'
NOTION_DATABASE_ID              = '<32_char_database_id>'

// Gmail
GMAIL_SENDER_ADDRESS            = 'handover-bot@[YourCompany.com]'
GMAIL_RECIPIENT_LIST_KEY        = 'shift_recipient_list'
GMAIL_REPORT_SUBJECT_TEMPLATE   = 'Shift Handover Report - {shift_date} - {shift_id}'

// PagerDuty
PAGERDUTY_INTEGRATION_KEY       = '<events_api_v2_routing_key>'
PAGERDUTY_API_KEY               = '<rest_api_v2_user_or_service_key>'
PAGERDUTY_SERVICE_ID            = '<service_id>'
PAGERDUTY_ESCALATION_POLICY_ID  = '<policy_id>'
PAGERDUTY_WEBHOOK_SECRET        = '<webhook_signing_secret_for_future_use>'

// Orchestration config
SHIFT_SCHEDULE                  = '<JSON array of shift_end_times in HH:MM local format>'
RESPONSE_WINDOW_MINUTES         = '10'
ESCALATION_SEVERITY_MAP         = '{"unresolved_incident":"critical","equipment_flag":"warning"}'