Integration and API Spec

Integration and API Spec

Employee Offboarding Automation

Primary trigger source for the automation. A webhook fires when an employee record is updated with a departure date or the employment status changes to a configured offboarding value. Also the destination for final record closure at the end of the workflow.

// Trigger payload (abbreviated)
{
  "employeeId": "<bamboohr_employee_id>",
  "changedFields": ["status", "terminationDate"],
  "status": "Terminated",
  "terminationDate": "YYYY-MM-DD",
  "firstName": "<string>",
  "lastName": "<string>",
  "workEmail": "<string>",
  "managerId": "<bamboohr_manager_id>"
}
// Record closure PATCH (end of workflow)
PATCH /v1/employees/{employeeId}
Body: { "status": "Offboarded", "offboardingCompletedDate": "YYYY-MM-DD" }

Receives a suspension instruction from the Access Revocation Agent. Immediately suspends the user's SSO session, which revokes access to all Okta-connected SaaS applications in a single API call.

// Step 1: Resolve Okta userId by email
GET https://{okta_domain}/api/v1/users?search=profile.login+eq+"{workEmail}"
Response: [{ "id": "<okta_user_id>", "status": "ACTIVE", ... }]

// Step 2: Suspend user
POST https://{okta_domain}/api/v1/users/{okta_user_id}/lifecycle/suspend
Authorization: Bearer {access_token}
Expected response: 200 OK (empty body)

// On success: pass okta_user_id and suspension_timestamp to next step

Used by both agents. Agent 1 calls the Admin SDK to disable the user account, configure an out-of-office reply, and transfer Drive file ownership to the departing employee's manager. Agent 2 uses the Gmail API to send the exit survey to the employee's personal email.

// Disable user account
PATCH https://admin.googleapis.com/admin/directory/v1/users/{userKey}
Body: { "suspended": true }

// Set out-of-office / vacation responder
PUT https://gmail.googleapis.com/gmail/v1/users/{userKey}/settings/vacation
Body: { "enableAutoReply": true, "responseSubject": "Out of Office",
        "responseBodyPlainText": "{vacation_template}" }

// Transfer Drive ownership to manager
POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions
Body: { "role": "owner", "type": "user", "emailAddress": "{manager_google_email}" }

// Send exit survey (Agent 2)
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
Body: { "raw": "<base64url-encoded RFC 2822 message with survey_url placeholder>" }

Used by the Task and Notification Agent to create a structured offboarding task board with subtasks assigned to the correct owner for equipment return, payroll confirmation, and exit interview tracking. Also provides the equipment return confirmation trigger.

// Create parent offboarding issue
POST https://{jira_base_url}/rest/api/3/issue
Body: {
  "fields": {
    "project": { "key": "{jira_project_key}" },
    "summary": "Offboarding: {firstName} {lastName} - {terminationDate}",
    "issuetype": { "id": "{story_issue_type_id}" },
    "assignee": { "accountId": "{hr_manager_account_id}" },
    "duedate": "{terminationDate}"
  }
}

// Create equipment return subtask (repeat pattern for each subtask)
POST https://{jira_base_url}/rest/api/3/issue
Body: {
  "fields": {
    "project": { "key": "{jira_project_key}" },
    "parent": { "key": "{parent_issue_key}" },
    "summary": "Equipment Return: {firstName} {lastName}",
    "issuetype": { "id": "{subtask_issue_type_id}" },
    "assignee": { "accountId": "{manager_account_id}" }
  }
}

Receives a structured payroll notification from the Task and Notification Agent containing the employee's final working day, accrued leave balance, and any equipment deduction flags. The automation does not write payroll entries directly; it posts a note or sends a notification to the finance lead via Xero's API.

// Resolve Xero EmployeeID
GET https://api.xero.com/payroll/v1/employees?where=FirstName=="{firstName}"&&LastName=="{lastName}"
Headers: Authorization: Bearer {access_token}, Xero-Tenant-Id: {xero_tenant_id}
Response: { "Employees": [{ "EmployeeID": "<uuid>", ... }] }

// Post payroll note
POST https://api.xero.com/payroll/v1/employees/{EmployeeID}/notes
Body: {
  "Title": "Final Pay Notification - Automated",
  "Note": "Last working day: {terminationDate}. Leave balance: {leave_balance_days} days.
            Equipment deduction flag: {equipment_flag}. Generated by offboarding automation."
}

Receives a completion summary message from the Task and Notification Agent after all automated steps are confirmed. Posts to a designated HR Slack channel listing every completed task and flagging any items still awaiting human confirmation.

// Post completion summary
POST https://slack.com/api/chat.postMessage
Headers: Authorization: Bearer {slack_bot_token}, Content-Type: application/json
Body: {
  "channel": "{slack_hr_channel_id}",
  "text": "Offboarding complete: {firstName} {lastName} ({terminationDate})",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*Offboarding Summary*\n{firstName} {lastName} | Last day: {terminationDate}" } },
    { "type": "section", "text": { "type": "mrkdwn",
      "text": ":white_check_mark: Okta suspended\n:white_check_mark: Google account disabled\n:white_check_mark: Jira board created\n:white_check_mark: Xero notified\n:white_check_mark: Exit survey sent\n:hourglass: Equipment return: {equipment_status}" } }
  ]
}

// Credential store contents (all values encrypted at rest)

// BambooHR
bamboohr_api_key          = "<BambooHR API key for integration user>"
bamboohr_subdomain        = "yourcompany"   // used to build base URL
bamboohr_webhook_secret   = "<HMAC-SHA256 secret from BambooHR webhook config>"

// Okta
okta_domain               = "yourcompany.okta.com"
okta_client_id            = "<Okta service app client ID>"
okta_client_secret        = "<Okta service app client secret>"
okta_api_token            = "<SSWS token (fallback only)>"

// Google Workspace
gws_service_account_key_json       = "<full JSON key file contents, base64-encoded>"
gws_admin_impersonation_email      = "admin@yourcompany.com"

// Jira
jira_base_url             = "https://yourcompany.atlassian.net"
jira_api_token            = "<Atlassian API token for integration user>"
jira_user_email           = "offboarding-bot@yourcompany.com"
jira_project_key          = "OFFB"
jira_webhook_secret       = "<secret for inbound Jira equipment-return webhook>"

// Xero
xero_client_id            = "<Xero app client ID>"
xero_client_secret        = "<Xero app client secret>"
xero_refresh_token        = "<long-lived refresh token from OAuth consent>"
xero_tenant_id            = "<Xero organisation tenant ID>"

// Slack
slack_bot_token           = "xoxb-<Slack bot OAuth token>"
slack_hr_channel_id       = "C<Slack channel ID for HR channel>"

// Workflow config (non-secret, stored in workflow variables)
offboarding_status_value      = "Terminated"     // BambooHR status string to match
equipment_poll_interval_hrs   = 4
equipment_poll_max_hrs        = 240
exit_survey_url               = "https://yourcompany.com/exit-survey"
ooo_reply_template            = "Thank you for your email. {firstName} {lastName} is no longer at [YourCompany.com]. Please contact hr@yourcompany.com for assistance."
jira_hr_manager_account_id    = "<Atlassian account ID for HR Manager>"
jira_it_admin_account_id      = "<Atlassian account ID for IT Administrator>"
jira_finance_account_id       = "<Atlassian account ID for Finance Lead>"