Integration and API Spec

Integration and API Spec

Standard Operating Procedure Management

Monitors the approved SOPs folder for file create and modify events. Supplies file metadata (file ID, name, MIME type, last-modifying user, modified timestamp) to Agent 1. Also used by Agent 1 to write back the incremented version string to the document properties field.

// Trigger payload (Drive Push Notification or poll result)
{ "kind": "drive#change",
  "fileId": "<string>",
  "file": {
    "id": "<string>",
    "name": "<string>",
    "mimeType": "<string>",
    "modifiedTime": "<ISO-8601>",
    "lastModifyingUser": { "emailAddress": "<string>", "displayName": "<string>" },
    "appProperties": { "sop_version": "<string|null>" }
  }
}
// Output written back to Drive (via files.update)
PATCH https://www.googleapis.com/drive/v3/files/{fileId}
Body: { "appProperties": { "sop_version": "<incremented_version>" } }

Hosts three key data structures used across both agents: the master SOP register (Agent 1 writes), the role-to-SOP mapping table (Agent 2 reads), and the acknowledgement tracker (Agent 2 reads and writes). All sheet interactions use the Sheets v4 REST API.

// Agent 1 append to SOP Register (spreadsheets.values.append)
POST https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_REGISTER_ID}/values/'SOP Register'!A:H:append
Body: { "values": [[sop_id, sop_name, new_version, last_revised, revised_by, change_summary, compliance_critical, "open"]] }

// Agent 2 read Role Mapping (spreadsheets.values.get)
GET https://sheets.googleapis.com/v4/spreadsheets/{SHEETS_REGISTER_ID}/values/'Role Mapping'!A:C
Filter client-side: rows where col_A == sop_id

// Agent 2 write Ack Tracker row
POST .../values/'Ack Tracker'!A:G:append
Body: { "values": [[cycle_id, sop_id, sop_version, staff_email, ack_method, "", 0]] }

Used by Agent 2 for direct message notifications with interactive acknowledgement buttons, scheduled 48-hour reminders, escalation messages to line managers, and a final completion summary posted to the operations channel. Requires a custom Slack app installed in the workspace.

// Outbound: acknowledgement DM (chat.postMessage)
POST https://slack.com/api/chat.postMessage
{ "channel": "<user_id>",
  "blocks": [ { "type": "section", "text": { "type": "mrkdwn",
    "text": "*SOP Updated:* {{sop_name}} v{{sop_version}}\n{{change_summary}}\n<{{doc_link}}|View document>" } },
    { "type": "actions", "elements": [ { "type": "button",
      "action_id": "ack_sop__{{cycle_id}}__{{staff_email}}",
      "text": { "type": "plain_text", "text": "I have read this SOP" },
      "style": "primary" } ] } ] }

// Inbound: interactive callback from Slack
POST <orchestration_webhook_endpoint>
Header: X-Slack-Signature: v0=<hmac_sha256>
Payload: { "type": "block_actions",
  "actions": [ { "action_id": "ack_sop__<cycle_id>__<staff_email>",
    "action_ts": "<unix_ts>" } ],
  "user": { "id": "<slack_user_id>", "name": "<slack_username>" } }

Invoked by Agent 2 for compliance-critical SOPs only. Sends an envelope to required signatories, monitors envelope status via webhook, and writes completion status back to the acknowledgement tracker in Sheets. Uses the DocuSign eSignature REST API v2.1.

// Create envelope (POST /v2.1/accounts/{DOCUSIGN_ACCOUNT_ID}/envelopes)
{ "emailSubject": "Please sign: {{sop_name}} v{{sop_version}}",
  "templateId": "<DOCUSIGN_EMAIL_TEMPLATE_ID>",
  "templateRoles": [
    { "email": "<staff_email>", "name": "<staff_name>",
      "roleName": "Signer",
      "tabs": { "textTabs": [ { "tabLabel": "sop_name", "value": "{{sop_name}}" },
                               { "tabLabel": "sop_version", "value": "{{sop_version}}" } ] } }
  ],
  "status": "sent"
}

// Inbound Connect webhook payload (envelope-completed)
{ "EnvelopeStatus": { "EnvelopeID": "<guid>", "Status": "Completed",
  "Completed": "<ISO-8601>",
  "RecipientStatuses": [ { "Email": "<staff_email>", "Status": "Completed",
    "Signed": "<ISO-8601>" } ] } }

Used in the Standard build as a read reference only. Agent 2 may retrieve the Notion page URL for an archived SOP version to include in Slack messages or the SOP register. No automated writes to Notion are in scope for the Standard build. Archive writes remain a manual step for the operations manager.

// Query Notion database for archive page (POST /v1/databases/{NOTION_SOP_DATABASE_ID}/query)
{ "filter": { "property": "sop_id", "rich_text": { "equals": "<sop_id>" } } }

// Response (used to extract public URL for Slack message)
{ "results": [ { "id": "<page_id>", "url": "https://www.notion.so/<page_id>",
  "properties": { "sop_id": { "rich_text": [ { "plain_text": "<sop_id>" } ] } } } ] }

# Credential store contents (all keys required before go-live)
# Google
GOOGLE_OAUTH_CLIENT_ID          = "<oauth_client_id>"
GOOGLE_OAUTH_CLIENT_SECRET      = "<oauth_client_secret>"
GOOGLE_OAUTH_REFRESH_TOKEN      = "<refresh_token>"
DRIVE_SOP_FOLDER_ID             = "<google_drive_folder_id>"
DRIVE_ARCHIVE_FOLDER_ID         = "<google_drive_archive_folder_id>"
DRIVE_WATCH_CHANNEL_TOKEN       = "<random_uuid_for_channel_validation>"
SHEETS_REGISTER_ID              = "<google_sheets_spreadsheet_id>"
SHEETS_REGISTER_TAB_NAME        = "SOP Register"
SHEETS_MAPPING_TAB_NAME         = "Role Mapping"
SHEETS_ACK_TAB_NAME             = "Ack Tracker"

# Slack
SLACK_BOT_TOKEN                 = "xoxb-<token>"
SLACK_SIGNING_SECRET            = "<signing_secret>"
SLACK_OPS_CHANNEL_ID            = "<channel_id>"

# DocuSign
DOCUSIGN_INTEGRATION_KEY        = "<integration_key_guid>"
DOCUSIGN_ACCOUNT_ID             = "<account_id_guid>"
DOCUSIGN_USER_GUID              = "<impersonation_user_guid>"
DOCUSIGN_RSA_PRIVATE_KEY        = "-----BEGIN RSA PRIVATE KEY-----\n<pem>\n-----END RSA PRIVATE KEY-----"
DOCUSIGN_BASE_URI               = "https://www.docusign.net/restapi"
DOCUSIGN_EMAIL_TEMPLATE_ID      = "<template_guid>"
DOCUSIGN_CONNECT_HMAC_KEY       = "<connect_hmac_key>"

# Notion
NOTION_TOKEN                    = "secret_<token>"
NOTION_SOP_DATABASE_ID          = "<notion_database_guid>"

# Orchestration
INBOUND_WEBHOOK_ENDPOINT        = "https://<platform_host>/webhook/<workflow_id>"
REMINDER_INTERVAL_HOURS         = 48
ESCALATION_AFTER_REMINDERS      = 2