Bamboohr Automation

1---
2name: bamboohr-automation
3description: "Automate BambooHR tasks via Rube MCP (Composio): employees, time-off, benefits, dependents, employee updates. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# BambooHR Automation via Rube MCP
9 
10Automate BambooHR human resources operations through Composio's BambooHR toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active BambooHR connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `bamboohr`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `bamboohr`
253. If connection is not ACTIVE, follow the returned auth link to complete BambooHR authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. List and Search Employees
31 
32**When to use**: User wants to find employees or get the full employee directory
33 
34**Tool sequence**:
351. `BAMBOOHR_GET_ALL_EMPLOYEES` - Get the employee directory [Required]
362. `BAMBOOHR_GET_EMPLOYEE` - Get detailed info for a specific employee [Optional]
37 
38**Key parameters**:
39- For GET_ALL_EMPLOYEES: No required parameters; returns directory
40- For GET_EMPLOYEE:
41  - `id`: Employee ID (numeric)
42  - `fields`: Comma-separated list of fields to return (e.g., 'firstName,lastName,department,jobTitle')
43 
44**Pitfalls**:
45- Employee IDs are numeric integers
46- GET_ALL_EMPLOYEES returns basic directory info; use GET_EMPLOYEE for full details
47- The `fields` parameter controls which fields are returned; omitting it may return minimal data
48- Common fields: firstName, lastName, department, division, jobTitle, workEmail, status
49- Inactive/terminated employees may be included; check `status` field
50 
51### 2. Track Employee Changes
52 
53**When to use**: User wants to detect recent employee data changes for sync or auditing
54 
55**Tool sequence**:
561. `BAMBOOHR_EMPLOYEE_GET_CHANGED` - Get employees with recent changes [Required]
57 
58**Key parameters**:
59- `since`: ISO 8601 datetime string for change detection threshold
60- `type`: Type of changes to check (e.g., 'inserted', 'updated', 'deleted')
61 
62**Pitfalls**:
63- `since` parameter is required; use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
64- Returns IDs of changed employees, not full employee data
65- Must call GET_EMPLOYEE separately for each changed employee's details
66- Useful for incremental sync workflows; cache the last sync timestamp
67 
68### 3. Manage Time-Off
69 
70**When to use**: User wants to view time-off balances, request time off, or manage requests
71 
72**Tool sequence**:
731. `BAMBOOHR_GET_META_TIME_OFF_TYPES` - List available time-off types [Prerequisite]
742. `BAMBOOHR_GET_TIME_OFF_BALANCES` - Check current balances [Optional]
753. `BAMBOOHR_GET_TIME_OFF_REQUESTS` - List existing requests [Optional]
764. `BAMBOOHR_CREATE_TIME_OFF_REQUEST` - Submit a new request [Optional]
775. `BAMBOOHR_UPDATE_TIME_OFF_REQUEST` - Modify or approve/deny a request [Optional]
78 
79**Key parameters**:
80- For balances: `employeeId`, time-off type ID
81- For requests: `start`, `end` (date range), `employeeId`
82- For creation:
83  - `employeeId`: Employee to request for
84  - `timeOffTypeId`: Type ID from GET_META_TIME_OFF_TYPES
85  - `start`: Start date (YYYY-MM-DD)
86  - `end`: End date (YYYY-MM-DD)
87  - `amount`: Number of days/hours
88  - `notes`: Optional notes for the request
89- For update: `requestId`, `status` ('approved', 'denied', 'cancelled')
90 
91**Pitfalls**:
92- Time-off type IDs are numeric; resolve via GET_META_TIME_OFF_TYPES first
93- Date format is 'YYYY-MM-DD' for start and end dates
94- Balances may be in hours or days depending on company configuration
95- Request status updates require appropriate permissions (manager/admin)
96- Creating a request does NOT auto-approve it; separate approval step needed
97 
98### 4. Update Employee Information
99 
100**When to use**: User wants to modify employee profile data
101 
102**Tool sequence**:
1031. `BAMBOOHR_GET_EMPLOYEE` - Get current employee data [Prerequisite]
1042. `BAMBOOHR_UPDATE_EMPLOYEE` - Update employee fields [Required]
105 
106**Key parameters**:
107- `id`: Employee ID (numeric, required)
108- Field-value pairs for the fields to update (e.g., `department`, `jobTitle`, `workPhone`)
109 
110**Pitfalls**:
111- Only fields included in the request are updated; others remain unchanged
112- Some fields are read-only and cannot be updated via API
113- Field names must match BambooHR's expected field names exactly
114- Updates are audited; changes appear in the employee's change history
115- Verify current values with GET_EMPLOYEE before updating to avoid overwriting
116 
117### 5. Manage Dependents and Benefits
118 
119**When to use**: User wants to view employee dependents or benefit coverage
120 
121**Tool sequence**:
1221. `BAMBOOHR_DEPENDENTS_GET_ALL` - List all dependents [Required]
1232. `BAMBOOHR_BENEFIT_GET_COVERAGES` - Get benefit coverage details [Optional]
124 
125**Key parameters**:
126- For dependents: Optional `employeeId` filter
127- For benefits: Depends on schema; check RUBE_SEARCH_TOOLS for current parameters
128 
129**Pitfalls**:
130- Dependent data includes sensitive PII; handle with appropriate care
131- Benefit coverages may include multiple plan types per employee
132- Not all BambooHR plans include benefits administration; check account features
133- Data access depends on API key permissions
134 
135## Common Patterns
136 
137### ID Resolution
138 
139**Employee name -> Employee ID**:
140```
1411. Call BAMBOOHR_GET_ALL_EMPLOYEES
1422. Find employee by name in directory results
1433. Extract id (numeric) for detailed operations
144```
145 
146**Time-off type name -> Type ID**:
147```
1481. Call BAMBOOHR_GET_META_TIME_OFF_TYPES
1492. Find type by name (e.g., 'Vacation', 'Sick Leave')
1503. Extract id for time-off requests
151```
152 
153### Incremental Sync Pattern
154 
155For keeping external systems in sync with BambooHR:
156```
1571. Store last_sync_timestamp
1582. Call BAMBOOHR_EMPLOYEE_GET_CHANGED with since=last_sync_timestamp
1593. For each changed employee ID, call BAMBOOHR_GET_EMPLOYEE
1604. Process updates in external system
1615. Update last_sync_timestamp
162```
163 
164### Time-Off Workflow
165 
166```
1671. GET_META_TIME_OFF_TYPES -> find type ID
1682. GET_TIME_OFF_BALANCES -> verify available balance
1693. CREATE_TIME_OFF_REQUEST -> submit request
1704. UPDATE_TIME_OFF_REQUEST -> approve/deny (manager action)
171```
172 
173## Known Pitfalls
174 
175**Employee IDs**:
176- Always numeric integers
177- Resolve names to IDs via GET_ALL_EMPLOYEES
178- Terminated employees retain their IDs
179 
180**Date Formats**:
181- Time-off dates: 'YYYY-MM-DD'
182- Change detection: ISO 8601 with timezone
183- Inconsistent formats between endpoints; check each endpoint's schema
184 
185**Permissions**:
186- API key permissions determine accessible fields and operations
187- Some operations require admin or manager-level access
188- Time-off approvals require appropriate role permissions
189 
190**Sensitive Data**:
191- Employee data includes PII (names, addresses, SSN, etc.)
192- Handle all responses with appropriate security measures
193- Dependent data is especially sensitive
194 
195**Rate Limits**:
196- BambooHR API has rate limits per API key
197- Bulk operations should be throttled
198- GET_ALL_EMPLOYEES is more efficient than individual GET_EMPLOYEE calls
199 
200**Response Parsing**:
201- Response data may be nested under `data` key
202- Employee fields vary based on `fields` parameter
203- Empty fields may be omitted or returned as null
204- Parse defensively with fallbacks
205 
206## Quick Reference
207 
208| Task | Tool Slug | Key Params |
209|------|-----------|------------|
210| List all employees | BAMBOOHR_GET_ALL_EMPLOYEES | (none) |
211| Get employee details | BAMBOOHR_GET_EMPLOYEE | id, fields |
212| Track changes | BAMBOOHR_EMPLOYEE_GET_CHANGED | since, type |
213| Time-off types | BAMBOOHR_GET_META_TIME_OFF_TYPES | (none) |
214| Time-off balances | BAMBOOHR_GET_TIME_OFF_BALANCES | employeeId |
215| List time-off requests | BAMBOOHR_GET_TIME_OFF_REQUESTS | start, end, employeeId |
216| Create time-off request | BAMBOOHR_CREATE_TIME_OFF_REQUEST | employeeId, timeOffTypeId, start, end |
217| Update time-off request | BAMBOOHR_UPDATE_TIME_OFF_REQUEST | requestId, status |
218| Update employee | BAMBOOHR_UPDATE_EMPLOYEE | id, (field updates) |
219| List dependents | BAMBOOHR_DEPENDENTS_GET_ALL | employeeId |
220| Benefit coverages | BAMBOOHR_BENEFIT_GET_COVERAGES | (check schema) |
221