Developer Handover Pack

Developer Handover Pack

Employee Onboarding Automation

Handles all document generation and collection tasks for each hire. The agent fires immediately when BambooHR emits an 'Offer Accepted' webhook, maps the hire's role to a pre-configured DocuSign template, populates the template fields from the BambooHR record, and sends the envelope for e-signature. It then dispatches the new hire information pack via Gmail. After sending, the agent enters a polling loop: it checks DocuSign envelope status on a configurable interval (default 48 hours) and sends reminder emails via Gmail until all documents are signed and returned. On completion it writes a status flag back to BambooHR and emits a completion event consumed by downstream agents. This agent is rated Complex due to the template-matching decision gate, the reminder loop with configurable wait windows, and the DocuSign API polling requirement.

// Input (from BambooHR webhook payload)
employee.id           : string   // BambooHR employee record ID
employee.firstName    : string
employee.lastName     : string
employee.jobTitle     : string   // used for DocuSign template lookup
employee.employmentType: string  // 'full-time' | 'part-time' | 'contractor'
employee.salary       : number
employee.startDate    : date     // ISO 8601
employee.managerId    : string   // BambooHR manager record ID
employee.department   : string
employee.personalEmail: string   // pre-company email for DocuSign

// Decision gate
// IF jobTitle + employmentType maps to a known DocuSign templateId -> proceed automatically
// ELSE -> pause, alert HR via Slack/Gmail, await manual template creation, then resume

// Output (on successful document completion)
docusign.envelopeId   : string
docusign.status       : 'completed'
docusign.completedAt  : datetime
bamboohr.field[onboarding_docs_status]: 'complete'
event.emitted         : 'documents_complete' // consumed by Provisioning Agent

Creates and configures all system accounts the new hire needs before day one. The agent fires on two conditions: five business days before the hire's start date, or immediately if the start date is fewer than five business days away (calculated at the moment the 'documents_complete' event is received). It provisions a Google Workspace account via the Admin SDK, assigns the correct organisational unit based on the department field, and adds the hire to the relevant Google Groups. It then invites the hire to Slack via the Slack API and adds them to the standard company channels plus the role-specific channels defined in the job record. On completion it writes a provisioning confirmation log entry to BambooHR and emits an event for the Onboarding Coordinator Agent. This agent is rated Moderate due to the timing logic and the two-tool provisioning sequence, but the Google Workspace Admin SDK setup adds initial configuration complexity.

// Input (from Document Agent completion event + BambooHR record)
employee.id           : string
employee.firstName    : string
employee.lastName     : string
employee.jobTitle     : string
employee.department   : string   // maps to Google OU and Slack channel list
employee.startDate    : date
employee.personalEmail: string   // used as recovery email in Google Workspace
employee.managerId    : string

// Derived at runtime
google.primaryEmail   : string   // constructed: firstname.lastname@[YourCompany.com]
google.orgUnitPath    : string   // e.g. '/Engineering' or '/Sales', from department map
google.groupMemberships: string[]// from department-to-group config map
slack.channelIds      : string[] // from role-to-channel config map

// Output
google.workspace.userId    : string   // Google account ID
google.workspace.email     : string   // provisioned company email
slack.userId               : string
slack.inviteStatus         : 'ok' | 'error'
bamboohr.field[it_provisioning_status]: 'complete'
bamboohr.field[company_email]         : string   // written back for downstream use
event.emitted              : 'provisioning_complete' // consumed by Onboarding Coordinator

Builds the new hire's onboarding workspace and keeps the hiring manager and the hire informed. The agent fires once the Provisioning Agent logs a successful account creation, ensuring the hire's company email and Slack user ID exist before any communications reference them. It duplicates the correct role-based onboarding template in Notion and personalises the page header with the hire's name, role, start date, and manager. It then sends the hiring manager a structured Slack message containing the hire's details and a checklist of pre-day-one manager tasks. Finally, it dispatches a personalised day-one welcome email to the hire's new company Gmail address three days before the start date, summarising their schedule, login instructions, and any outstanding document items. This agent is rated Moderate due to the Notion API duplication logic and the date-triggered email dispatch.

// Input (from Provisioning Agent completion event + BambooHR record)
employee.id            : string
employee.firstName     : string
employee.lastName      : string
employee.jobTitle      : string
employee.department    : string
employee.startDate     : date
employee.companyEmail  : string   // provisioned in previous agent step
employee.managerId     : string
slack.managerId        : string   // Slack user ID of hiring manager
notion.templatePageId  : string   // from role-to-template config map

// Output
notion.onboardingPageId  : string   // newly duplicated and personalised page ID
notion.pageUrl           : string   // shared with hire and manager
slack.managerMessageId   : string   // Slack message ts confirming briefing sent
gmail.welcomeEmailId     : string   // Gmail message ID of day-one email
gmail.scheduledSendTime  : datetime // 3 days before startDate, 09:00 hire timezone

// On approval (offer letter template exception path, Document Agent gate)
// HR approves template mapping via Slack interactive message or manual config update
// Coordinator Agent does not have an approval gate itself; approval lives in Document Agent

// ─────────────────────────────────────────────────────────────────────
// TRIGGER
// ─────────────────────────────────────────────────────────────────────
BambooHR webhook (POST /webhook/offer-accepted)
  -> payload.employee.id
  -> payload.employee.firstName
  -> payload.employee.lastName
  -> payload.employee.jobTitle
  -> payload.employee.employmentType
  -> payload.employee.salary
  -> payload.employee.startDate
  -> payload.employee.managerId
  -> payload.employee.department
  -> payload.employee.personalEmail

// ─────────────────────────────────────────────────────────────────────
// DOCUMENT AGENT
// ─────────────────────────────────────────────────────────────────────
Step 1: Template lookup
  input : employee.jobTitle + employee.employmentType
  output: docusign.templateId (from config map)
  branch: templateId found     -> proceed to Step 2
          templateId NOT found -> alert HR (Slack + Gmail), await manual mapping, resume

Step 2: DocuSign envelope creation
  POST /v2.1/accounts/{accountId}/envelopes
  body.templateId          = docusign.templateId
  body.templateRoles[0].tabs.textTabs:
    employee_first_name    = employee.firstName
    employee_last_name     = employee.lastName
    job_title              = employee.jobTitle
    start_date             = employee.startDate
    salary                 = employee.salary
    manager_name           = <resolved from employee.managerId via BambooHR GET /v1/employees/{managerId}>
  body.templateRoles[0].email = employee.personalEmail
  output: docusign.envelopeId

Step 3: Gmail information pack
  POST Gmail API /users/me/messages/send
  from    : hr@[YourCompany.com]
  to      : employee.personalEmail
  subject : 'Welcome to [YourCompany.com] — your pre-start checklist'
  body    : templated HTML (company policies PDF attached, document upload link)
  output  : gmail.infoPackMessageId

Step 4: DocuSign status polling loop
  GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}
  check   : envelope.status == 'completed'
  if NOT completed after 48h: send reminder via Gmail (max 3 reminders)
  if max reminders exceeded : escalate to HR via Slack
  output  : docusign.status = 'completed', docusign.completedAt

Step 5: BambooHR write-back
  PATCH /v1/employees/{employee.id}
  field: onboarding_docs_status = 'complete'
  output: confirmed write-back

// HANDOFF: Document Agent -> Provisioning Agent
// event.emitted = 'documents_complete'
// payload carries: employee.id, employee.startDate, employee.department,
//                  employee.jobTitle, employee.personalEmail, employee.managerId

// ─────────────────────────────────────────────────────────────────────
// PROVISIONING AGENT
// ─────────────────────────────────────────────────────────────────────
Step 6: Start-date proximity check
  input : employee.startDate, current date
  calc  : business_days_until_start
  if >= 5 business days : schedule agent execution for (startDate - 5 business days)
  if <  5 business days : execute immediately, set flag expedited_provisioning = true

Step 7: Google Workspace account creation
  POST Admin SDK Directory API /admin/directory/v1/users
  body.primaryEmail     = firstName.toLowerCase() + '.' + lastName.toLowerCase() + '@[YourCompany.com]'
  body.name.givenName   = employee.firstName
  body.name.familyName  = employee.lastName
  body.orgUnitPath      = department_to_ou_map[employee.department]
  body.password         = temporary password (env var pattern)
  body.changePasswordAtNextLogin = true
  body.recoveryEmail    = employee.personalEmail
  output: google.workspace.userId, google.workspace.email
  on collision (409): append numeral suffix, retry, log collision alert

Step 8: Google Group membership
  POST /admin/directory/v1/groups/{groupKey}/members
  for each groupKey in department_to_groups_map[employee.department]:
    body.email = google.workspace.email
    body.role  = 'MEMBER'

Step 9: Slack invitation
  POST Slack API admin.users.invite
  body.email      = employee.personalEmail
  body.channel_ids = role_to_slack_channels_map[employee.jobTitle]
  output: slack.userId

Step 10: BambooHR provisioning write-back
  PATCH /v1/employees/{employee.id}
  field: it_provisioning_status = 'complete'
  field: company_email          = google.workspace.email

// HANDOFF: Provisioning Agent -> Onboarding Coordinator Agent
// event.emitted = 'provisioning_complete'
// payload carries: employee.id, employee.firstName, employee.lastName,
//                  employee.jobTitle, employee.department, employee.startDate,
//                  employee.companyEmail (= google.workspace.email),
//                  employee.managerId, slack.managerId (resolved from managerId)

// ─────────────────────────────────────────────────────────────────────
// ONBOARDING COORDINATOR AGENT
// ─────────────────────────────────────────────────────────────────────
Step 11: Notion page creation
  POST Notion API /v1/pages
  body.parent.page_id       = role_to_notion_template_map[employee.jobTitle]
  body.properties.title     = employee.firstName + ' ' + employee.lastName + ' — Onboarding'
  body.properties.Name      = employee.firstName + ' ' + employee.lastName
  body.properties.Role      = employee.jobTitle
  body.properties.StartDate = employee.startDate
  body.properties.Manager   = <manager name resolved from employee.managerId>
  output: notion.onboardingPageId, notion.pageUrl
  on failure: retry once after 300s, then Slack alert to HR, continue remaining steps

Step 12: Slack manager briefing
  POST Slack API chat.postMessage
  channel : slack.managerId (resolved via users.lookupByEmail on manager company email)
  text    : structured message template (hire name, role, startDate, companyEmail,
            notion.pageUrl, manager pre-day-one checklist)
  output  : slack.managerMessageId

Step 13: Scheduled day-one welcome email
  POST Gmail API /users/me/messages/send (with scheduledSendTime)
  from             : hr@[YourCompany.com]
  to               : employee.companyEmail
  scheduledSendTime: (employee.startDate - 3 calendar days) at 09:00 company timezone
  subject          : 'See you on [startDate] — everything you need for day one'
  body             : templated HTML (schedule summary, login instructions,
                     notion.pageUrl, any outstanding document items from docusign.status)
  output           : gmail.welcomeEmailId, gmail.scheduledSendTime

// ─────────────────────────────────────────────────────────────────────
// TERMINAL STATE
// ─────────────────────────────────────────────────────────────────────
All outputs confirmed:
  bamboohr.onboarding_docs_status    = 'complete'
  bamboohr.it_provisioning_status    = 'complete'
  bamboohr.company_email             = google.workspace.email
  notion.onboardingPageId            = <page ID>
  slack.managerMessageId             = <ts>
  gmail.welcomeEmailId               = <message ID>
  error_log_table                    = 0 unresolved errors (or HR alerted for each)