Integration and API Spec

Integration and API Spec

Staff Scheduling and Rostering

Used by Agent 1 (Availability Collection) to dispatch the weekly availability request to all active staff, and by Agent 3 (Roster Publication and Payroll) to send personalised shift confirmation emails after roster publication.

// Input (Agent 1 send)
recipient_email: string          // from STAFF_ROSTER sheet column staff_email
staff_name: string               // from STAFF_ROSTER sheet column full_name
week_start_date: ISO8601 date    // computed by trigger
availability_form_url: string    // from credential store key AVAIL_FORM_URL
// Output
gmail_message_id: string         // stored to AVAIL_LOG sheet for delivery tracking
send_status: 'sent' | 'failed'

Acts as the central data layer for the entire automation. Agent 1 writes availability responses row by row. Agent 2 reads availability and shift demand data to build the draft roster, then writes the draft back to a designated roster tab. The manager's approval signal is also read from a named cell in this sheet.

// Input (Agent 2 read)
spreadsheet_id: string           // from credential store SHEETS_SPREADSHEET_ID
range: 'AVAILABILITY_RESPONSES!A2:H'  // all staff rows for current week
range: 'SHIFT_DEMAND!A2:E'       // demand requirements for the week
// Output (Agent 2 write)
range: 'DRAFT_ROSTER!A2:K'       // one row per shift slot
range: 'STATUS!A1'               // write 'ROSTER_DRAFT_READY' on completion
// Output (Agent 1 write)
range: 'AVAILABILITY_RESPONSES!A{n}:H{n}'  // append one row per staff response
range: 'AVAIL_LOG!A{n}:D{n}'     // append delivery and response log entry

Provides the recurring weekly timer that fires the start of each scheduling cycle. The orchestration layer listens to a specific calendar event pattern to determine when to initiate Agent 1.

// Trigger output passed to Agent 1
event_id: string                 // Google Calendar event ID
event_start: ISO8601 datetime    // exact trigger timestamp
week_start_date: ISO8601 date    // derived: Monday of the roster week
week_end_date: ISO8601 date      // derived: Sunday of the roster week

Receives the finalised roster from Agent 3 via the Deputy REST API, creating or updating shift records for each staff member. At pay-period close, Agent 3 also reads confirmed timesheet data from Deputy to export to Xero.

// Input (Agent 3 shift creation)
POST /api/v1/resource/Roster/BULK
body: [{ EmployeeId, StartTime, EndTime, OperationalUnitId, Comment, Published }]
// Input (Agent 3 timesheet read at pay-period close)
GET /api/v1/resource/Timesheet?search={EmployeeId,StartDate,EndDate,Status:'Approved'}
// Output (shift creation response)
roster_id[]: integer[]           // Deputy-assigned shift IDs, stored to DRAFT_ROSTER sheet
// Output (timesheet read response)
timesheet[]: { EmployeeId, StartTime, EndTime, TotalTime, Status }

Used by Agent 2 to post conflict and rule-breach alerts to the manager's designated channel, and by Agent 3 to send personalised shift notifications to each staff member's direct message or a shared shifts channel.

// Input (Agent 2 conflict alert)
channel: SLACK_MANAGER_CHANNEL_ID
blocks: ConflictSummaryBlockKit    // list of unresolved shifts with rule breach type
// Input (Agent 3 staff DM)
channel: slack_user_id             // resolved from staff email via users.lookupByEmail
blocks: ShiftConfirmationBlockKit  // staff_name, shift_day, shift_start, shift_end
// Output
ts: string                         // Slack message timestamp, stored for audit log
ok: boolean                        // success flag; false triggers Gmail fallback

Receives timesheet entries from Agent 3 at pay-period close. Confirmed shift hours are read from Deputy and posted to Xero as manual journal or timesheet records ready for payroll processing.

// Input (Agent 3 timesheet post)
POST /api.xro/2.0/Timesheets
body: { EmployeeID, StartDate, EndDate, Status:'Draft',
        TimesheetLines: [{ EarningsRateID, NumberOfUnits[] }] }
// Output
TimesheetID: GUID                // Xero-assigned ID, stored to PAYROLL_LOG sheet
Status: 'Draft' | 'Approved'     // Xero status after creation
ValidationErrors[]: string[]     // surface to orchestration error handler if non-empty

// Credential store: required keys (all values injected at runtime, never hardcoded)

// Google (shared OAuth client)
GOOGLE_CLIENT_ID=<oauth_client_id>
GOOGLE_CLIENT_SECRET=<oauth_client_secret>
GOOGLE_REFRESH_TOKEN=<refresh_token>          // single token with all Google scopes

// Google Sheets
SHEETS_SPREADSHEET_ID=<google_sheets_file_id>

// Google Calendar
AUTOMATION_CALENDAR_ID=<google_calendar_id>
ROSTER_CYCLE_DAY=Monday                       // day of week trigger fires
ROSTER_CYCLE_TIME=07:00                       // local time trigger fires

// Gmail
GMAIL_SENDER_ADDRESS=roster@yourcompany.com
AVAIL_FORM_URL=https://forms.gle/<form_id>
GMAIL_TEMPLATE_AVAIL_REQUEST=<template_id_or_body_key>
GMAIL_TEMPLATE_SHIFT_CONFIRM=<template_id_or_body_key>

// Deputy
DEPUTY_SUBDOMAIN=yourcompany                  // subdomain only, not full URL
DEPUTY_CLIENT_ID=<deputy_oauth_client_id>
DEPUTY_CLIENT_SECRET=<deputy_oauth_client_secret>
DEPUTY_ACCESS_TOKEN=<access_token>            // auto-refreshed by orchestration layer
DEPUTY_REFRESH_TOKEN=<refresh_token>
DEPUTY_LOCATION_ID=<operational_unit_id>

// Slack
SLACK_BOT_TOKEN=xoxb-<token>
SLACK_SIGNING_SECRET=<signing_secret>         // for interactive component validation
SLACK_MANAGER_CHANNEL_ID=C<channel_id>
SLACK_STAFF_NOTIFY_CHANNEL_ID=C<channel_id>  // fallback if DM resolution fails

// Xero
XERO_CLIENT_ID=<xero_app_client_id>
XERO_TENANT_ID=<xero_organisation_tenant_id>
XERO_ACCESS_TOKEN=<access_token>              // auto-refreshed before every call
XERO_REFRESH_TOKEN=<refresh_token>
XERO_PAYROLL_CALENDAR_ID=<payroll_calendar_guid>
XERO_EARNINGS_RATE_ID=<earnings_rate_guid>
XERO_PAY_PERIOD_CLOSE_DAY=Friday             // day of week payroll export fires