bamboohr-automation

通过 Rube MCP 自动化 BambooHR

通过 Rube MCP 使用 Composio 的 BambooHR 工具包，自动执行 BambooHR 人力资源操作。

工具包文档：composio.dev/toolkits/bamboohr

前置条件

• 必须已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 BambooHR 连接，工具包为 bamboohr
• 始终先调用 RUBE_SEARCH_TOOLS 获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能正常响应，以验证 Rube MCP 可用
2. 使用工具包 bamboohr 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请通过返回的授权链接完成 BambooHR 身份验证
4. 运行任何工作流之前，确认连接状态为 ACTIVE

核心工作流

1. 列出和搜索员工

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

工具调用顺序：

1. BAMBOOHR_GET_ALL_EMPLOYEES - 获取员工目录［必需］
2. 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. 跟踪员工变更

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

工具调用顺序：

1. BAMBOOHR_EMPLOYEE_GET_CHANGED - 获取近期发生变更的员工［必需］

关键参数：

• since：用于变更检测阈值的 ISO 8601 日期时间字符串
• type：要检查的变更类型（例如，'inserted'、'updated'、'deleted'）

注意事项：

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

3. 管理休假

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

工具调用顺序：

1. BAMBOOHR_GET_META_TIME_OFF_TYPES - 列出可用的休假类型［前置步骤］
2. BAMBOOHR_GET_TIME_OFF_BALANCES - 查看当前余额［可选］
3. BAMBOOHR_GET_TIME_OFF_REQUESTS - 列出现有申请［可选］
4. BAMBOOHR_CREATE_TIME_OFF_REQUEST - 提交新申请［可选］
5. BAMBOOHR_UPDATE_TIME_OFF_REQUEST - 修改、批准或拒绝申请［可选］

关键参数：

• 对于余额：employeeId、休假类型 ID
• 对于申请：start、end（日期范围）、employeeId
• 对于创建申请：
  • employeeId：要代为申请的员工
  • 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. 更新员工信息

使用时机：用户想要修改员工个人资料

工具调用顺序：

1. BAMBOOHR_GET_EMPLOYEE - 获取当前员工数据 [前置条件]
2. BAMBOOHR_UPDATE_EMPLOYEE - 更新员工字段 [必需]

关键参数：

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

注意事项：

• 仅更新请求中包含的字段；其他字段保持不变
• 某些字段为只读，无法通过 API 更新
• 字段名称必须与 BambooHR 要求的名称完全一致
• 更新操作会被审计；更改会显示在员工的变更历史中
• 更新前，使用 GET_EMPLOYEE 确认当前值，以免覆盖数据

5. 管理受抚养人和福利

使用时机：用户想要查看员工的受抚养人或福利保障情况

工具调用顺序：

1. BAMBOOHR_DEPENDENTS_GET_ALL - 列出所有受抚养人 [必需]
2. BAMBOOHR_BENEFIT_GET_COVERAGES - 获取福利保障详情 [可选]

关键参数：

• 受抚养人：可选的 employeeId 筛选条件
• 福利：取决于架构；通过 RUBE_SEARCH_TOOLS 查看当前参数

注意事项：

• 受抚养人数据包含敏感个人身份信息（PII）；应谨慎处理
• 每位员工可能有多种福利计划保障
• 并非所有 BambooHR 计划都包含福利管理；请查看账户功能
• 数据访问权限取决于 API 密钥权限

常见模式

ID 解析

员工姓名 -> 员工 ID：

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

休假类型名称 -> 类型 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

增量同步模式

用于使外部系统与 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

休假工作流

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)

已知注意事项

员工 ID：

• 始终为数字整数
• 通过 GET_ALL_EMPLOYEES 将姓名解析为 ID
• 离职员工仍保留其 ID

日期格式：

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

权限：

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

敏感数据：

• 员工数据包含个人身份信息（PII），例如姓名、地址、SSN 等
• 处理所有响应时都应采取适当的安全措施
• 受抚养人数据尤为敏感

速率限制：

• BambooHR API 对每个 API 密钥都设有速率限制
• 批量操作应限制调用频率
• 与逐个调用 GET_EMPLOYEE 相比，GET_ALL_EMPLOYEES 效率更高

响应解析：

• 响应数据可能嵌套在 data 键下
• 员工字段会根据 fields 参数而变化
• 空字段可能会被省略或返回为 null
• 解析时应做好防护，并提供备用处理逻辑

快速参考

任务	工具标识	关键参数
列出所有员工	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 提供支持