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.

Toolkit docs: composio.dev/toolkits/bamboohr

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

工具包文档：composio.dev/toolkits/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
```
如果连接未处于激活状态，请按照返回的认证链接完成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获取
开始和结束日期格式为'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)

Powered by Composio

任务	工具标识	关键参数
列出所有员工	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	请查看架构

由 Composio 提供支持