BambooHR

1. Overview

What is BambooHR?

BambooHR is a comprehensive human resources information system (HRIS) designed for small and medium-sized businesses. It provides a centralized platform for managing employee information, tracking time off, storing documents, generating reports, and streamlining various HR processes.

What can the GoInsight BambooHR node do?

Through the GoInsight BambooHR node, you can seamlessly integrate HR data management into your automated workflows. You can perform comprehensive operations across multiple resource types to manage your organization's HR data, including:

• Employee Management: Create, retrieve, update, and list employee records with customizable field selection.
• Document Management: Upload, download, update, and delete both company-wide files and employee-specific documents.
• Category Organization: Create and manage file categories for both company files and employee documents.
• Reporting: Access and retrieve custom reports to analyze HR data.

2. Prerequisites

Before using this node, you need to meet the following requirements:

• You must have an active BambooHR account with a valid company subdomain.
• You need appropriate permissions to generate and use API keys. Typically, only administrators or users with specific API access rights can create API credentials.
• Ensure that your BambooHR plan includes API access, as some features may vary depending on your subscription level.

3. Credentials

For detailed guidance on how to obtain and configure your BambooHR credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

The BambooHR node enables you to manage various HR resources including employees, company files, employee documents, file categories, and custom reports. The following table provides a quick overview of all supported operations organized by resource type:

Operation Details

Create an Employee

Create an Employee from BambooHR.

Options:

• EmployeeData: Employee data in JSON format containing the employee fields to create.

Output:

• EmployeeData (object): EmployeeData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Get an Employee

Get an Employee from BambooHR.

Options:

• EmployeeId: The unique identifier for the employee.
• Fields: Comma separated field list specifying which employee fields to retrieve (e.g., "displayName,jobTitle,workEmail").

Output:

• EmployeeData (object): EmployeeData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Get all Employees

Get All Employees from BambooHR.

Output:

• EmployeeCount (number): Total count of employees
• Employees (object-array): List of employee data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Update an Employee

Update an Employee from BambooHR.

Options:

• EmployeeId: The unique identifier for the employee to update.
• EmployeeData: Employee data in JSON format containing the fields to update.

Output:

• EmployeeData (object): EmployeeData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Get Reports

Get all custom reports from BambooHR.

Options:

• Page: Optional. Page number for pagination. Must be a positive integer.
• PageSize: Optional. Number of records per page. Must be a positive integer.

Output:

• Reports (object-array): Reports array data
• Pagination (object): Pagination information containing total_records, current_page, total_pages, next_page, prev_page
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Get a Report

Get a report from BambooHR.

Options:

• ReportId: The unique identifier for the custom report.

Output:

• ReportData (object): ReportData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Create a Company File Category

Create a company file category in BambooHR.

Input Parameters:

• CategoryName: Name of the category to create

Output:

• CategoryData (object): Created category data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Delete a Company File Category

Delete a company file category from BambooHR.

Input Parameters:

• CategoryId: ID of the category to delete

Output:

• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Get all Company Files and Categories

Lists company files and categories

Output:

• Categories (object-array): Categories array data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Upload a Company File

Upload a Company File from BambooHR.

Options:

• FileName: Name of the file to upload.
• FileData: Base64-encoded file content.
• CategoryId: ID of the category to upload the file into.

Output:

• FileData (object): FileData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Update a Company File

Update a Company File from BambooHR.

Options:

• FileId: The unique identifier for the company file to update.
• FileData: Base64-encoded file content for the updated file.

Output:

• FileData (object): FileData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Download a Company File

Download a Company File from BambooHR.

Options:

• FileId: The unique identifier for the company file to download.

Output:

• FileData (string): FileData data
• FileName (string): FileName data
• MimeType (string): MIME type of the file
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Delete a Company File

Delete a Company File from BambooHR.

Options:

• FileId: The unique identifier for the company file to delete.

Output:

• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Create an Employee File Category

Create an employee file category in BambooHR.

Input Parameters:

• CategoryName: Name of the category to create

Output:

• CategoryData (object): Created category data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Get all Employee Documents and Categories

Lists employee documents and categories.

Input Parameters:

• EmployeeId: The unique identifier for the employee whose documents to retrieve.

Output:

• Categories (object-array): Categories array data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Upload an Employee Document

Upload an Employee Document from BambooHR.

Options:

• EmployeeId: The unique identifier for the employee.
• FileName: Name of the document to upload.
• FileData: Base64-encoded file content.
• CategoryId: ID of the category to upload the document into.

Output:

• DocumentData (object): DocumentData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Update an Employee Document

Update an Employee Document from BambooHR.

Options:

• EmployeeId: The unique identifier for the employee.
• FileId: The unique identifier for the employee document to update.
• DocumentData: Updated document data in JSON format.

Output:

• DocumentData (object): DocumentData data
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Download an Employee Document

Download an Employee Document from BambooHR.

Options:

• EmployeeId: The unique identifier for the employee.
• FileId: The unique identifier for the employee document to download.

Output:

• FileData (string): FileData data
• FileName (string): FileName data
• MimeType (string): MIME type extracted from Content-Type header
• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

Delete an Employee Document

Delete an Employee Document from BambooHR.

Options:

• EmployeeId: The unique identifier for the employee.
• FileId: The unique identifier for the employee document to delete.

Output:

• StatusCode (number): HTTP/status code
• ErrorMessage (string): Error message if any

5. Example Usage

This section will guide you through creating a simple workflow to retrieve all employees from your BambooHR account. This is one of the most common operations and demonstrates how to effectively use the BambooHR node in GoInsight.

Scenario: You want to create an automated workflow that fetches all employee records from BambooHR and returns the data for further processing or analysis.

Workflow Overview: The workflow consists of three basic components: Start → BambooHR (Get all Employees) → Answer.

Step-by-Step Guide:

1. Add the BambooHR Tool Node:

• On your workflow canvas, click the "+" button to add a new node.
• In the popup panel, select the "Tools" tab.
• Find and select BambooHR from the tools list.
• In the list of supported operations for BambooHR, click to select Get all Employees. This will add the corresponding node to your canvas.

2. Configure the Node:

• Click on the newly added Get all Employees node. The configuration panel will appear on the right side.
• Credential Configuration: At the top of the panel, locate the credential field. Click the dropdown menu and select your previously configured BambooHR credential. If you haven't set up credentials yet, refer to the Credentials section above.
• Parameter Configuration: The Get all Employees operation doesn't require any input parameters, so no additional configuration is needed. The node will automatically retrieve all employees from your BambooHR account.

3. Run and Verify:

• Once the credential is properly configured, any error indicators on the canvas should disappear.
• Click the "Test Run" button in the upper right corner of the canvas to execute the workflow.
• After successful execution, click the log icon in the upper right corner to view the detailed input and output of the node. You should see the complete list of employees returned in the Employees output field, along with the EmployeeCount showing the total number of employees.

Final Workflow Summary: After completing these steps, your workflow is ready to use. When you click "Test Run", the workflow will connect to your BambooHR account and retrieve all employee records. You can then use this data in subsequent workflow nodes for reporting, notifications, data synchronization, or any other automation needs.

6. FAQs

Q: I'm receiving a 401 Unauthorized error. What should I do?

A: This typically indicates an authentication issue. Please check the following:

• Verify that your API key is correct and hasn't expired.
• Ensure that your BambooHR subdomain is correctly configured in the credentials.
• Confirm that the API key has the necessary permissions for the operation you're trying to perform.
• Make sure your API key hasn't been revoked in the BambooHR admin panel.

Q: What format should I use for the EmployeeData when creating or updating an employee?

A: The EmployeeData should be provided as a JSON object containing the employee fields you want to set or update. For example:

{
  "firstName": "John",
  "lastName": "Doe",
  "jobTitle": "Software Engineer",
  "workEmail": "john.doe@company.com"
}

Refer to the BambooHR API documentation for a complete list of available employee fields.

Q: How do I upload a file to BambooHR?

A: To upload files (either company files or employee documents), you need to:

• Convert your file to Base64 encoding.
• Provide the Base64-encoded content in the FileData parameter.
• Specify the FileName with the appropriate file extension.
• Optionally, provide a CategoryId to organize the file into a specific category.

Q: Can I retrieve specific employee fields instead of all fields?

A: Yes! When using the Get an Employee operation, you can use the Fields parameter to specify exactly which fields you want to retrieve. Provide a comma-separated list of field names (e.g., "displayName,jobTitle,workEmail") to optimize performance and reduce data transfer.

Q: What does a successful operation return?

A: All operations return a StatusCode field. A status code of 200 or 201 typically indicates success. You'll also receive relevant data in operation-specific output fields (e.g., EmployeeData, FileData, ReportData). If an error occurs, the ErrorMessage field will contain details about what went wrong.

7. Official Documentation

For advanced use cases, detailed API specifications, and comprehensive field references, please visit the official BambooHR API documentation:

BambooHR Official API Documentation