Integration and API Spec

Integration and API Spec

Performance Review Cycle

Provides the authoritative employee list at cycle open and receives confirmed final ratings via API write-back after calibration. Consumed by Agent 1 (read) and the post-calibration write-back step (write).

// Input (Agent 1 - read)
GET /employees/directory?fields=id,firstName,lastName,workEmail,supervisorId,supervisorEmail,department,status
GET /employees/{id}/customFields?field=review_cycle_status,review_cycle_deadline
// Output (post-calibration write-back)
POST /employees/{id}/tables/customTabularData
Body: { "review_rating_final": "<agreed_rating>", "review_notes": "<calibration_notes>" }

Hosts the employee self-assessment form and the manager assessment form. Agent 2 monitors for new responses via the Google Sheets linked response destination. Agent 3 reads matched response pairs to generate summaries.

// Input (Agent 2 polls linked sheet)
GET https://sheets.googleapis.com/v4/spreadsheets/{SELF_ASSESSMENT_SHEET_ID}/values/Sheet1
GET https://sheets.googleapis.com/v4/spreadsheets/{MANAGER_ASSESSMENT_SHEET_ID}/values/Sheet1
// Output (rows consumed by Agent 2 and Agent 3)
Row structure: [timestamp, employee_id, q1_response, q2_response, ..., qN_response, submitter_email]

Serves as the live submission status tracker maintained by Agent 2. Contains one row per employee with submission status columns for self-assessment and manager assessment, timestamps, and reminder log entries.

// Input (Agent 2 writes on each poll)
PATCH https://sheets.googleapis.com/v4/spreadsheets/{TRACKER_SHEET_ID}/values/Sheet1!F{row}:L{row}
Body: { "values": [["submitted", "{timestamp}", "pending", "", reminder_count, last_reminder_sent, ""]] }
// Output (Agent 2 reads for overdue detection)
GET https://sheets.googleapis.com/v4/spreadsheets/{TRACKER_SHEET_ID}/values/Sheet1!A2:L

Hosts the manager summary template and stores auto-generated per-employee summary documents in manager-specific Drive folders. Consumed exclusively by Agent 3.

// Agent 3: copy template, then replace placeholders
POST https://www.googleapis.com/drive/v3/files/{SUMMARY_TEMPLATE_DOC_ID}/copy
Body: { "name": "Performance Review Summary - {employee_name} - {review_period}", "parents": ["{manager_folder_id}"] }
POST https://docs.googleapis.com/v1/documents/{new_doc_id}:batchUpdate
Body: { "requests": [ { "replaceAllText": { "containsText": { "text": "{{employee_name}}" }, "replaceText": "{employee_name}" } }, ... ] }

Dispatches kick-off emails (Agent 1), daily chase reminders and 48-hour deadline nudges (Agent 2), and manager summary-ready notifications (Agent 3). All mail is sent from a designated HR service mailbox, not an individual user account.

// Agent 1: kick-off send
POST https://gmail.googleapis.com/gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
Body: { "raw": "<base64-encoded RFC 2822 message>" }
// Encoded message headers example
From: hr-reviews@[YourCompany.com]
To: {employee_email}
Subject: Your Performance Review is Now Open - Action Required by {deadline_date}
Content-Type: text/html; charset=UTF-8

Posts kick-off announcements to configured HR and team channels (Agent 1) and sends direct-message nudges to overdue submitters 48 hours before the deadline (Agent 2). Uses a dedicated Slack app with bot token authentication.

// Agent 1: channel announcement
POST https://slack.com/api/chat.postMessage
Headers: { Authorization: Bearer {SLACK_BOT_TOKEN} }
Body: { "channel": "{SLACK_ANNOUNCEMENTS_CHANNEL_ID}", "blocks": [{...Block Kit JSON...}] }
// Agent 2: direct message nudge
POST https://slack.com/api/chat.postMessage
Body: { "channel": "{slack_user_id}", "text": "Reminder: your performance review form is due in 48 hours. {form_link}" }

# Credential store contents
# BambooHR
BAMBOOHR_API_KEY=<api_key_from_bamboohr_settings>
BAMBOOHR_SUBDOMAIN=<your_bamboohr_subdomain>
BAMBOOHR_FIELD_REVIEW_STATUS=<custom_field_id_for_review_cycle_status>
BAMBOOHR_FIELD_REVIEW_DEADLINE=<custom_field_id_for_review_cycle_deadline>
BAMBOOHR_FIELD_FINAL_RATING=<custom_field_id_for_review_rating_final>

# Google Workspace (shared service account)
GOOGLE_SERVICE_ACCOUNT_KEY=<path_or_json_of_service_account_key_file>
GOOGLE_IMPERSONATION_EMAIL=hr-reviews@[YourCompany.com]

# Google Forms
SELF_ASSESSMENT_FORM_ID=<google_form_id_for_self_assessment>
SELF_ASSESSMENT_FORM_URL=<public_url_for_self_assessment_form>
SELF_ASSESSMENT_SHEET_ID=<google_sheets_id_of_linked_response_sheet>
MANAGER_ASSESSMENT_FORM_ID=<google_form_id_for_manager_assessment>
MANAGER_ASSESSMENT_FORM_URL=<public_url_for_manager_assessment_form>
MANAGER_ASSESSMENT_SHEET_ID=<google_sheets_id_of_linked_manager_response_sheet>

# Google Sheets tracker
TRACKER_SHEET_ID=<google_sheets_id_of_submission_tracker>

# Google Docs
SUMMARY_TEMPLATE_DOC_ID=<google_docs_id_of_summary_template>
MANAGER_FOLDER_MAP={"mgr_id_001":"drive_folder_id_001","mgr_id_002":"drive_folder_id_002"}

# Gmail
GMAIL_SENDER_ADDRESS=hr-reviews@[YourCompany.com]
KICKOFF_EMPLOYEE_TEMPLATE=<inline_html_or_template_id>
KICKOFF_MANAGER_TEMPLATE=<inline_html_or_template_id>
REMINDER_TEMPLATE=<inline_html_or_template_id>
FINAL_NUDGE_TEMPLATE=<inline_html_or_template_id>
SUMMARY_READY_TEMPLATE=<inline_html_or_template_id>

# Slack
SLACK_BOT_TOKEN=xoxb-<bot_token_from_slack_app_settings>
SLACK_HR_CHANNEL_ID=<channel_id_e.g._C012AB3CD>
SLACK_ANNOUNCEMENTS_CHANNEL_ID=<channel_id_e.g._C045EF6GH>

# Cycle config
REVIEW_PERIOD_LABEL=<e.g._H1_2025>
REMINDER_THRESHOLD_DAYS=1
FINAL_NUDGE_HOURS_BEFORE_DEADLINE=48