Integration and API Spec

Integration and API Spec

Workplace Incident Reporting

Incident intake trigger. The form is the sole entry point for all incident reports. A new form response fires the orchestration layer's trigger step and passes the raw response payload to Agent 1.

// Inbound watch notification payload (abbreviated)
{
  "formId": "<GFORMS_INCIDENT_FORM_ID>",
  "responseId": "<string>",
  "eventType": "RESPONSE_CREATED"
}

// Follow-up GET returns full response
GET https://forms.googleapis.com/v1/forms/{formId}/responses/{responseId}
Authorization: Bearer <oauth_access_token>

Incident register. Agent 1 appends a new structured row on each submission. Agents 2 and 3 are triggered by detecting that new row. Agent 3 also updates the row status field when the incident is closed.

// Append new incident row
POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append
?valueInputOption=USER_ENTERED

// Body
{
  "values": [[
    "<reference_number>", "<submission_timestamp>", "<reporter_name>",
    "<department>", "<incident_type>", "<severity>", "<description>",
    "<injured_employee_id>", "<manager_email>", "open", ""
  ]]
}

Manager and escalation notifications. Agent 2 posts a channel message to the relevant department manager channel and, for serious incidents, sends a direct message to the Operations Director.

// Post channel notification
POST https://slack.com/api/chat.postMessage
Authorization: Bearer <SLACK_BOT_TOKEN>

// Body
{
  "channel": "<dept_channel_id>",
  "text": "Incident <reference_number> logged. Severity: <severity>. Reporter: <reporter_name>.",
  "blocks": [ { "type": "section", "text": { "type": "mrkdwn", "text": "*<ref>* | <severity> | <summary>" } } ]
}

// Direct message for serious incidents
{
  "channel": "<SLACK_OPS_DIRECTOR_USER_ID>",
  "text": "SERIOUS incident <reference_number> requires your attention. Dept: <department>."
}

Investigation tasks and corrective action tracking. Agent 3 creates a new database page per incident, sets structured properties, and polls for status changes to detect overdue investigations and closed records.

// Create investigation page
POST https://api.notion.com/v1/pages
Authorization: Bearer <NOTION_INTEGRATION_TOKEN>
Notion-Version: 2022-06-28

// Body (abbreviated)
{
  "parent": { "database_id": "<NOTION_INVESTIGATION_DB_ID>" },
  "properties": {
    "Reference Number": { "title": [{ "text": { "content": "<ref_number>" } }] },
    "Severity": { "select": { "name": "<severity>" } },
    "Investigation Deadline": { "date": { "start": "<deadline_iso8601>" } },
    "Status": { "select": { "name": "Open" } }
  }
}

Deadline reminder emails and closure confirmation emails. Agent 3 sends outbound email via the Gmail API on two triggers: investigation deadline approaching or passed (reminder), and incident closed in Notion (closure confirmation to reporter).

// Send email via Gmail API
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Authorization: Bearer <oauth_access_token>

// Body
{
  "raw": "<base64url_encoded_RFC2822_message>"
}

// RFC 2822 headers required
From: <GMAIL_SENDER_ADDRESS>
To: <manager_email | reporter_email>
Subject: Incident <reference_number> - Investigation Reminder
Content-Type: text/html; charset=UTF-8

Employee record updates for injury-classified incidents. Agent 3 writes the incident date, type, and reference number to the employee's custom fields in BambooHR. This step runs only when the severity classification includes an injury flag.

// Update employee custom fields
PUT https://api.bamboohr.com/api/gateway.php/{BAMBOOHR_SUBDOMAIN}/v1/employees/{employee_id}/customTabFields/{tabId}
Authorization: Basic <base64(BAMBOOHR_API_KEY:x)>
Content-Type: application/json
Accept: application/json

// Body
{
  "customField": [
    { "fieldId": "<BAMBOOHR_INCIDENT_DATE_FIELD_ID>",  "value": "<incident_date_YYYY-MM-DD>" },
    { "fieldId": "<BAMBOOHR_INCIDENT_TYPE_FIELD_ID>",  "value": "<incident_type>" },
    { "fieldId": "<BAMBOOHR_INCIDENT_REF_FIELD_ID>",   "value": "<reference_number>" }
  ]
}

// Credential store keys
// Google
GFORMS_INCIDENT_FORM_ID          = "<google_forms_form_id>"
GSHEETS_INCIDENT_REGISTER_ID     = "<spreadsheet_id>"
GSHEETS_INCIDENT_RANGE           = "IncidentRegister!A:Z"
GOOGLE_OAUTH_CLIENT_ID           = "<oauth_client_id>"
GOOGLE_OAUTH_CLIENT_SECRET       = "<oauth_client_secret>"
GOOGLE_OAUTH_REFRESH_TOKEN       = "<oauth_refresh_token>"
GMAIL_SENDER_ADDRESS             = "<hr@yourcompany.com>"
GMAIL_TEMPLATE_REMINDER          = "<template_id_or_path>"
GMAIL_TEMPLATE_CLOSURE           = "<template_id_or_path>"

// Slack
SLACK_BOT_TOKEN                  = "xoxb-<token>"
SLACK_DEPT_CHANNEL_MAP           = "{\"operations\": \"C012AB3CD\", \"retail\": \"C045EF6GH\"}"
SLACK_OPS_DIRECTOR_USER_ID       = "U0123ABCDE"
SLACK_FALLBACK_CHANNEL_ID        = "C099ZZZZZZ"
SLACK_HR_ALERT_CHANNEL_ID        = "C077HRALRT"

// Notion
NOTION_INTEGRATION_TOKEN         = "secret_<token>"
NOTION_INVESTIGATION_DB_ID       = "<32_char_database_id>"
NOTION_PROP_REFERENCE_NUMBER     = "Reference Number"
NOTION_PROP_SEVERITY             = "Severity"
NOTION_PROP_DEADLINE             = "Investigation Deadline"
NOTION_PROP_STATUS               = "Status"
NOTION_PROP_ASSIGNED_MANAGER     = "Assigned Manager"
NOTION_PROP_BAMBOOHR_UPDATED     = "BambooHR Updated"

// BambooHR
BAMBOOHR_API_KEY                 = "<api_key>"
BAMBOOHR_SUBDOMAIN               = "<yourcompany>"
BAMBOOHR_INCIDENT_DATE_FIELD_ID  = "<numeric_field_id>"
BAMBOOHR_INCIDENT_TYPE_FIELD_ID  = "<numeric_field_id>"
BAMBOOHR_INCIDENT_REF_FIELD_ID   = "<numeric_field_id>"
BAMBOOHR_CUSTOM_TAB_ID           = "<numeric_tab_id>"

// Orchestration internal
GSHEETS_LAST_PROCESSED_ROW       = "<integer; updated after each Agent 2/3 poll>"