jsieber / Bamboozled

A simple PowerShell module for working with the BambooHR API

Bamboozled!

A simple (unofficial) PowerShell module to interact with the BambooHR API. For more information about this module, see the Bamboozled article on my personal blog.

Installation

Recommended: From the PowerShell Gallery

1. Open PowerShell (Core or Desktop)
2. Run "install-module -name Bamboozled"
3. Confirm the prompt to install

Manually

1. Download and unzip the module.
2. Copy to PowerShell's modules folder in your environment. See this article for details.
3. That's it!

Getting Started

Available functions

• Get-BambooHRDirectory: Gets a directory of users from BambooHR
• Get-BambooHRUser: Gets a single user from BambooHR
• Get-BambooHRFields: Uses the BambooHR meta API to get a list of all available fields
• Update-BambooHRUser: Takes a hash table of BambooHR fields and values to update a user's information

Get-BambooHRDirectory

The basics

The basic syntax for the Get-BambooHRDirectory commandlet is below. This commandlet also provides a few options, detailed later.

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname"

When run, this command will output a list of all employees, past and present, including all fields available from BambooHR's API. For a full list of these fields, see this link.

Active users only

To filter by active users, use the 'active' flag:

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -active

Customising fields

To adjust the fields returned in the results, you can use the fields flag:

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -fields "firstName,lastName,workEmail,supervisorEid"

A list of available fields can be found in BambooHR's API documentation, or by using the Get-BambooHRFields commandlet. This module expects the field names to be provided as written in BambooHR's documentation, separated by commas (no spaces).

Filtering by "Changed since"

To find a list of user records that have changed since a specified date, you can use the 'since' flag as below. The module expects the time to be provided in ISO 8601 format.

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -since "2018-10-22T15:00:00Z"

Get-BambooHRUser

The basics

The basic syntax for the Get-BambooHRUser commandlet is below. This commandlet also provides a few options, detailed later.

Get-BambooHRUser -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300

The above command will output BambooHR's information related to the employee with a unique ID of '300'.

By email address

If you don't have the employee's ID, you can use their email address instead. Note however, this performs a full directory lookup first, extracts the user's ID, and then performs an API request for that user's ID. If you have the employee's unique ID, the command above will be considerably quicker.

Get-BambooHRUser -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -emailAddress "[e-mail]"

Customising fields

To adjust the fields returned in the results, you can use the fields flag:

Get-BambooHRUser -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300 -fields "firstName,lastName,workEmail,supervisorEid"

A list of available fields can be found in BambooHR's API documentation, or by using the Get-BambooHRFields commandlet. This module expects the field names to be provided as written in BambooHR's documentation, separated by commas (no spaces).

Get-BambooHRFields

The basics

The basic syntax for the Get-BambooHRFields commandlet is below.

Get-BambooHRFields -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname"

Update-BambooHRUser

The basics

To update a BambooHR user's details, use the command below. If successful, the command returns TRUE.

Update-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300 -fields @{firstName="Simon";lastName="Buckley"}

The -fields parameter accepts a hash table containing the fields and values that you wish to update. A list of available fields can be found in BambooHR's API documentation, or by using the Get-BambooHRFields commandlet. To make the script more manageable, you can pass a variable to the parameter like below:

$fields = @{
    firstName = "Simon"
    lastName = "Buckley"
}

Update-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300 -fields $fields

By email address

If you don't have the employee's ID, you can use their email address instead. Note however, this performs a full directory lookup first, extracts the user's ID, and then performs the update request against that user's ID. If you have the employee's unique ID, using it instead will be considerably quicker.

Update-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -emailAddress "[e-mail]" -fields $fields

New-BambooHRUser

The basics

To add a new user to BambooHR, use the command below. Note: the BambooHR API expects a minimum of firstName and lastName for new users. The 'Fields' parameter expects a hash table of fields/values, as below.

New-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -fields @{firstName="Simon";lastName="Buckley"}