Bamboohr Automation Agent Skill

BambooHR Automation via Rube MCP

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

Toolkit docs: 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

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

Core Workflows

1. List and Search Employees

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

2. Track Employee Changes

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

3. Manage Time-Off

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

4. Update Employee Information

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

5. Manage Dependents and Benefits

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

Common Patterns

ID Resolution

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

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

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)

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

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*