bamboohr-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BambooHR Automation via Rube MCP

通过Rube MCP实现BambooHR自动化

Automate BambooHR human resources operations through Composio's BambooHR toolkit via Rube MCP.

通过Composio的BambooHR工具包，借助Rube MCP自动化BambooHR人力资源操作。

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active BambooHR connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
bamboohr
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需具备RUBE_SEARCH_TOOLS功能）
通过
```
RUBE_MANAGE_CONNECTIONS
```
并使用工具包
```
bamboohr
```
建立有效的BambooHR连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

Setup

设置

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.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
bamboohr
```
If connection is not ACTIVE, follow the returned auth link to complete BambooHR authentication
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 —— 只需添加端点即可使用。

通过确认
```
RUBE_SEARCH_TOOLS
```
能正常响应，验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包
```
bamboohr
```
如果连接状态未处于ACTIVE，请按照返回的认证链接完成BambooHR认证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. List and Search Employees

1. 员工列表与搜索

When to use: User wants to find employees or get the full employee directory

Tool sequence:

```
BAMBOOHR_GET_ALL_EMPLOYEES
```
- Get the employee directory [Required]
```
BAMBOOHR_GET_EMPLOYEE
```
- Get detailed info for a specific employee [Optional]

Key parameters:

For GET_ALL_EMPLOYEES: No required parameters; returns directory
For GET_EMPLOYEE:
- ```
id
```
  : Employee ID (numeric)
- ```
fields
```
  : Comma-separated list of fields to return (e.g., 'firstName,lastName,department,jobTitle')

Pitfalls:

Employee IDs are numeric integers
GET_ALL_EMPLOYEES returns basic directory info; use GET_EMPLOYEE for full details
The
```
fields
```
parameter controls which fields are returned; omitting it may return minimal data
Common fields: firstName, lastName, department, division, jobTitle, workEmail, status
Inactive/terminated employees may be included; check
```
status
```
field

适用场景：用户想要查找员工或获取完整的员工目录

工具流程：

```
BAMBOOHR_GET_ALL_EMPLOYEES
```
- 获取员工目录 [必填]
```
BAMBOOHR_GET_EMPLOYEE
```
- 获取特定员工的详细信息 [可选]

关键参数：

对于GET_ALL_EMPLOYEES：无必填参数；返回员工目录
对于GET_EMPLOYEE：
- ```
id
```
  ：员工ID（数字类型）
- ```
fields
```
  ：要返回的字段列表，以逗号分隔（例如：'firstName,lastName,department,jobTitle'）

注意事项：

员工ID为整数类型
GET_ALL_EMPLOYEES仅返回基础目录信息；如需完整详情请使用GET_EMPLOYEE
```
fields
```
参数控制返回的字段；若省略该参数，可能仅返回极少数据
常见字段：firstName、lastName、department、division、jobTitle、workEmail、status
可能包含已离职/终止合同的员工；请检查
```
status
```
字段

2. Track Employee Changes

2. 员工信息变更追踪

When to use: User wants to detect recent employee data changes for sync or auditing

Tool sequence:

```
BAMBOOHR_EMPLOYEE_GET_CHANGED
```
- Get employees with recent changes [Required]

Key parameters:

```
since
```
: ISO 8601 datetime string for change detection threshold
```
type
```
: Type of changes to check (e.g., 'inserted', 'updated', 'deleted')

Pitfalls:

```
since
```
parameter is required; use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
Returns IDs of changed employees, not full employee data
Must call GET_EMPLOYEE separately for each changed employee's details
Useful for incremental sync workflows; cache the last sync timestamp

适用场景：用户想要检测员工数据的近期变更，用于同步或审计

工具流程：

```
BAMBOOHR_EMPLOYEE_GET_CHANGED
```
- 获取近期有信息变更的员工 [必填]

关键参数：

```
since
```
：用于检测变更的ISO 8601格式时间戳字符串
```
type
```
：要检查的变更类型（例如：'inserted'、'updated'、'deleted'）

注意事项：

```
since
```
参数为必填项；请使用ISO 8601格式（例如：'2024-01-15T00:00:00Z'）
仅返回变更员工的ID，而非完整员工数据
必须为每个变更员工单独调用GET_EMPLOYEE以获取详细信息
适用于增量同步工作流；请缓存上次同步的时间戳

3. Manage Time-Off

3. 休假管理

When to use: User wants to view time-off balances, request time off, or manage requests

Tool sequence:

```
BAMBOOHR_GET_META_TIME_OFF_TYPES
```
- List available time-off types [Prerequisite]
```
BAMBOOHR_GET_TIME_OFF_BALANCES
```
- Check current balances [Optional]
```
BAMBOOHR_GET_TIME_OFF_REQUESTS
```
- List existing requests [Optional]
```
BAMBOOHR_CREATE_TIME_OFF_REQUEST
```
- Submit a new request [Optional]
```
BAMBOOHR_UPDATE_TIME_OFF_REQUEST
```
- Modify or approve/deny a request [Optional]

Key parameters:

For balances:
```
employeeId
```
, time-off type ID
For requests:
```
start
```
,
```
end
```
(date range),
```
employeeId
```
For creation:
- ```
employeeId
```
  : Employee to request for
- ```
timeOffTypeId
```
  : Type ID from GET_META_TIME_OFF_TYPES
- ```
start
```
  : Start date (YYYY-MM-DD)
- ```
end
```
  : End date (YYYY-MM-DD)
- ```
amount
```
  : Number of days/hours
- ```
notes
```
  : Optional notes for the request
For update:
```
requestId
```
,
```
status
```
('approved', 'denied', 'cancelled')

Pitfalls:

Time-off type IDs are numeric; resolve via GET_META_TIME_OFF_TYPES first
Date format is 'YYYY-MM-DD' for start and end dates
Balances may be in hours or days depending on company configuration
Request status updates require appropriate permissions (manager/admin)
Creating a request does NOT auto-approve it; separate approval step needed

适用场景：用户想要查看休假余额、提交休假申请或管理申请

工具流程：

```
BAMBOOHR_GET_META_TIME_OFF_TYPES
```
- 列出可用的休假类型 [前置步骤]
```
BAMBOOHR_GET_TIME_OFF_BALANCES
```
- 查看当前休假余额 [可选]
```
BAMBOOHR_GET_TIME_OFF_REQUESTS
```
- 列出已有的休假申请 [可选]
```
BAMBOOHR_CREATE_TIME_OFF_REQUEST
```
- 提交新的休假申请 [可选]
```
BAMBOOHR_UPDATE_TIME_OFF_REQUEST
```
- 修改或批准/拒绝休假申请 [可选]

关键参数：

余额查询：
```
employeeId
```
、休假类型ID
申请查询：
```
start
```
、
```
end
```
（日期范围）、
```
employeeId
```
申请创建：
- ```
employeeId
```
  ：申请休假的员工ID
- ```
timeOffTypeId
```
  ：来自GET_META_TIME_OFF_TYPES的休假类型ID
- ```
start
```
  ：开始日期（YYYY-MM-DD）
- ```
end
```
  ：结束日期（YYYY-MM-DD）
- ```
amount
```
  ：休假天数/小时数
- ```
notes
```
  ：申请的可选备注
申请更新：
```
requestId
```
、
```
status
```
（'approved'、'denied'、'cancelled'）

注意事项：

休假类型ID为数字类型；请先通过GET_META_TIME_OFF_TYPES获取对应ID
开始和结束日期格式为'YYYY-MM-DD'
休假余额的单位可能是小时或天数，取决于公司配置
更新申请状态需要相应的权限（经理/管理员）
创建申请后不会自动批准；需要单独的审批步骤

4. Update Employee Information

4. 员工信息更新

When to use: User wants to modify employee profile data

Tool sequence:

```
BAMBOOHR_GET_EMPLOYEE
```
- Get current employee data [Prerequisite]
```
BAMBOOHR_UPDATE_EMPLOYEE
```
- Update employee fields [Required]

Key parameters:

```
id
```
: Employee ID (numeric, required)
Field-value pairs for the fields to update (e.g.,
```
department
```
,
```
jobTitle
```
,
```
workPhone
```
)

Pitfalls:

Only fields included in the request are updated; others remain unchanged
Some fields are read-only and cannot be updated via API
Field names must match BambooHR's expected field names exactly
Updates are audited; changes appear in the employee's change history
Verify current values with GET_EMPLOYEE before updating to avoid overwriting

适用场景：用户想要修改员工档案数据

工具流程：

```
BAMBOOHR_GET_EMPLOYEE
```
- 获取当前员工数据 [前置步骤]
```
BAMBOOHR_UPDATE_EMPLOYEE
```
- 更新员工字段 [必填]

关键参数：

```
id
```
：员工ID（数字类型，必填）
要更新的字段-值对（例如：
```
department
```
、
```
jobTitle
```
、
```
workPhone
```
）

注意事项：

仅会更新请求中包含的字段；其他字段保持不变
部分字段为只读，无法通过API更新
字段名称必须与BambooHR要求的字段名称完全匹配
更新操作会被记录审计；变更会出现在员工的变更历史中
更新前请通过GET_EMPLOYEE验证当前值，避免覆盖错误

5. Manage Dependents and Benefits

5. 家属与福利管理

When to use: User wants to view employee dependents or benefit coverage

Tool sequence:

```
BAMBOOHR_DEPENDENTS_GET_ALL
```
- List all dependents [Required]
```
BAMBOOHR_BENEFIT_GET_COVERAGES
```
- Get benefit coverage details [Optional]

Key parameters:

For dependents: Optional
```
employeeId
```
filter
For benefits: Depends on schema; check RUBE_SEARCH_TOOLS for current parameters

Pitfalls:

Dependent data includes sensitive PII; handle with appropriate care
Benefit coverages may include multiple plan types per employee
Not all BambooHR plans include benefits administration; check account features
Data access depends on API key permissions

适用场景：用户想要查看员工家属信息或福利覆盖范围

工具流程：

```
BAMBOOHR_DEPENDENTS_GET_ALL
```
- 列出所有家属信息 [必填]
```
BAMBOOHR_BENEFIT_GET_COVERAGES
```
- 获取福利覆盖详情 [可选]

关键参数：

家属查询：可选的
```
employeeId
```
筛选条件
福利查询：取决于架构；请查看RUBE_SEARCH_TOOLS获取最新参数

注意事项：

家属数据包含敏感的个人身份信息（PII）；请妥善处理
员工的福利覆盖范围可能包含多种计划类型
并非所有BambooHR计划都包含福利管理功能；请检查账户特性
数据访问权限取决于API密钥的权限

Common Patterns

通用模式

ID Resolution

ID解析

Employee name -> Employee ID:

1. Call BAMBOOHR_GET_ALL_EMPLOYEES
2. Find employee by name in directory results
3. Extract id (numeric) for detailed operations

Time-off type name -> Type ID:

1. Call BAMBOOHR_GET_META_TIME_OFF_TYPES
2. Find type by name (e.g., 'Vacation', 'Sick Leave')
3. Extract id for time-off requests

员工姓名 -> 员工ID：

1. 调用BAMBOOHR_GET_ALL_EMPLOYEES
2. 在目录结果中按姓名查找员工
3. 提取数字类型的id用于后续详细操作

休假类型名称 -> 类型ID：

1. 调用BAMBOOHR_GET_META_TIME_OFF_TYPES
2. 按名称查找休假类型（例如：'Vacation'、'Sick Leave'）
3. 提取ID用于提交休假申请

Incremental Sync Pattern

增量同步模式

For keeping external systems in sync with BambooHR:

1. Store last_sync_timestamp
2. Call BAMBOOHR_EMPLOYEE_GET_CHANGED with since=last_sync_timestamp
3. For each changed employee ID, call BAMBOOHR_GET_EMPLOYEE
4. Process updates in external system
5. Update last_sync_timestamp

用于保持外部系统与BambooHR数据同步：

1. 存储last_sync_timestamp
2. 调用BAMBOOHR_EMPLOYEE_GET_CHANGED，参数since=last_sync_timestamp
3. 对每个变更的员工ID，调用BAMBOOHR_GET_EMPLOYEE
4. 在外部系统中处理更新
5. 更新last_sync_timestamp

Time-Off Workflow

休假申请工作流

1. GET_META_TIME_OFF_TYPES -> find type ID
2. GET_TIME_OFF_BALANCES -> verify available balance
3. CREATE_TIME_OFF_REQUEST -> submit request
4. UPDATE_TIME_OFF_REQUEST -> approve/deny (manager action)

1. GET_META_TIME_OFF_TYPES -> 查找休假类型ID
2. GET_TIME_OFF_BALANCES -> 验证可用余额
3. CREATE_TIME_OFF_REQUEST -> 提交申请
4. UPDATE_TIME_OFF_REQUEST -> 批准/拒绝（经理操作）

Known Pitfalls

已知注意事项

Employee IDs:

Always numeric integers
Resolve names to IDs via GET_ALL_EMPLOYEES
Terminated employees retain their IDs

Date Formats:

Time-off dates: 'YYYY-MM-DD'
Change detection: ISO 8601 with timezone
Inconsistent formats between endpoints; check each endpoint's schema

Permissions:

API key permissions determine accessible fields and operations
Some operations require admin or manager-level access
Time-off approvals require appropriate role permissions

Sensitive Data:

Employee data includes PII (names, addresses, SSN, etc.)
Handle all responses with appropriate security measures
Dependent data is especially sensitive

Rate Limits:

BambooHR API has rate limits per API key
Bulk operations should be throttled
GET_ALL_EMPLOYEES is more efficient than individual GET_EMPLOYEE calls

Response Parsing:

Response data may be nested under
```
data
```
key
Employee fields vary based on
```
fields
```
parameter
Empty fields may be omitted or returned as null
Parse defensively with fallbacks

员工ID：

始终为整数类型
请通过GET_ALL_EMPLOYEES将姓名解析为ID
已离职员工仍保留其ID

日期格式：

休假日期：'YYYY-MM-DD'
变更检测：带时区的ISO 8601格式
不同端点的格式可能不一致；请检查每个端点的架构

权限：

API密钥的权限决定了可访问的字段和操作
部分操作需要管理员或经理级别的权限
休假审批需要相应的角色权限

敏感数据：

员工数据包含个人身份信息（PII），如姓名、地址、社保号等
请采取适当的安全措施处理所有响应数据
家属数据尤其敏感

速率限制：

BambooHR API对每个API密钥有速率限制
批量操作应进行限流
GET_ALL_EMPLOYEES比多次调用单个GET_EMPLOYEE更高效

响应解析：

响应数据可能嵌套在
```
data
```
键下
员工字段取决于
```
fields
```
参数
空字段可能被省略或返回为null
请采用防御式解析，设置回退机制

Quick Reference

快速参考

Task	Tool Slug	Key Params
List all employees	BAMBOOHR_GET_ALL_EMPLOYEES	(none)
Get employee details	BAMBOOHR_GET_EMPLOYEE	id, fields
Track changes	BAMBOOHR_EMPLOYEE_GET_CHANGED	since, type
Time-off types	BAMBOOHR_GET_META_TIME_OFF_TYPES	(none)
Time-off balances	BAMBOOHR_GET_TIME_OFF_BALANCES	employeeId
List time-off requests	BAMBOOHR_GET_TIME_OFF_REQUESTS	start, end, employeeId
Create time-off request	BAMBOOHR_CREATE_TIME_OFF_REQUEST	employeeId, timeOffTypeId, start, end
Update time-off request	BAMBOOHR_UPDATE_TIME_OFF_REQUEST	requestId, status
Update employee	BAMBOOHR_UPDATE_EMPLOYEE	id, (field updates)
List dependents	BAMBOOHR_DEPENDENTS_GET_ALL	employeeId
Benefit coverages	BAMBOOHR_BENEFIT_GET_COVERAGES	(check schema)

任务	工具标识	关键参数
列出所有员工	BAMBOOHR_GET_ALL_EMPLOYEES	无
获取员工详情	BAMBOOHR_GET_EMPLOYEE	id, fields
追踪变更	BAMBOOHR_EMPLOYEE_GET_CHANGED	since, type
休假类型列表	BAMBOOHR_GET_META_TIME_OFF_TYPES	无
休假余额查询	BAMBOOHR_GET_TIME_OFF_BALANCES	employeeId
列出休假申请	BAMBOOHR_GET_TIME_OFF_REQUESTS	start, end, employeeId
创建休假申请	BAMBOOHR_CREATE_TIME_OFF_REQUEST	employeeId, timeOffTypeId, start, end
更新休假申请	BAMBOOHR_UPDATE_TIME_OFF_REQUEST	requestId, status
更新员工信息	BAMBOOHR_UPDATE_EMPLOYEE	id, (字段更新内容)
列出家属信息	BAMBOOHR_DEPENDENTS_GET_ALL	employeeId
福利覆盖查询	BAMBOOHR_BENEFIT_GET_COVERAGES	请查看架构