bamboohr

README

Bamboo HR Go Library

This is a fork of github.com/darrenparkinson/bamboohr, made with the express purpose of adding some custom fields to the employee data model in order to better suit the desired use case.

This is a simple Go library to utilise the Bamboo HR API.

Installation

To get the library, simply:

go get github.com/ScaleIan/bamboohr

Using the Library

To use the library you can use the New helper function and provide your API Key and your Company Domain, or provide these directly to the Client struct.

To get an API Key, follow the instructions on the Bamboo HR site, but essentially:

To generate an API key, users should log in and click their name in the upper right-hand corner of any page to get to the user context menu. If they have sufficient permissions, there will be an "API Keys" option in that menu to go to the page.

Your company domain is the part before bamboohr.com, so for https://acmecorp.bamboohr.com it would be acmecorp.

package main

import (
    "log"
    "os"

    "github.com/ScaleIan/bamboohr"
)

func main() {
    apikey := os.Getenv("BAMBOO_API_KEY")
    bamboo, _ := bamboohr.New(apikey, "acmecorp", nil)
    ctx := context.Background()
    people, _ := bamboo.GetEmployeeDirectory(ctx)
    for _, person := range people {
        log.Println(person.ID, person.Displayname)
    }

    // Note: 0 is a special ID meaning the user that created the API Key
    // If no field names are specified after the ID, then all fields will be fetched.
    me, _ := bamboo.GetEmployee(ctx, "0", bamboohr.DisplayName, bamboohr.FirstName, bamboohr.LastName)
    log.Println(me.ID, me.FirstName, me.LastName, me.DisplayName)
}

A context is required for each API request, for which you can just provide context.Background(), but you can also provide a timeout for your requests if necessary:

ctx := context.Background()
ctx, _ = context.WithTimeout(ctx, 1*time.Second)

people, err := bamboo.GetEmployeeDirectory(ctx)
if err != nil {
	log.Fatal(err)
}

This will likely return a context deadline exceeded error since the request will take longer than 1 second.

Documentation

There is an online reference for the package at [godoc.org/github.com/darrenparkinson/bamboohr][godoc-bamboohr].

Bamboo HR Documentation is available on their site.

So far, the following endpoints have been implemented:

Employees

• Get Employee
• Get Employee Directory

Employee Files

• List Employee Files and Categories
• Upload Employee File

Account Information

These have been removed temporarily due to some inconsistencies with the ID field returned from Bamboo.

• Get A List of Fields
• Get Details For List Fields

Documentation

Overview

Package bamboohr provides a library for the Bamboo HR API

Index

• Constants
• type Client
  • func New(apikey string, companyDomain string, client *http.Client) (*Client, error)
  • func (c *Client) GetEmployee(ctx context.Context, id string, fields ...EmployeeField) (Employee, error)
  • func (c *Client) GetEmployeeDirectory(ctx context.Context) ([]Employee, error)
  • func (c *Client) GetEmployeeFilesAndCategories(ctx context.Context, id string) ([]EmployeeCategory, error)
  • func (c *Client) UploadEmployeeFile(ctx context.Context, employeeID, categoryID, fileName, filePath, share string) error
• type Employee
• type EmployeeCategory
• type EmployeeCategoryResponse
• type EmployeeField
• type EmployeeFields
  • func (ef EmployeeFields) Join(sep string) string
• type EmployeeResponse
• type File

Constants

const (
	DisplayName        EmployeeField = "DisplayName"
	FirstName                        = "FirstName"
	LastName                         = "LastName"
	PreferredName                    = "PreferredName"
	Gender                           = "Gender"
	JobTitle                         = "JobTitle"
	WorkPhone                        = "WorkPhone"
	MobilePhone                      = "MobilePhone"
	WorkEmail                        = "WorkEmail"
	Department                       = "Department"
	Location                         = "Location"
	Division                         = "Division"
	LinkedIn                         = "LinkedIn"
	WorkPhoneExtension               = "WorkPhoneExtension"
	PhotoUploaded                    = "PhotoUploaded"
	PhotoURL                         = "PhotoURL"
	CanUploadPhoto                   = "CanUploadPhoto"
	HireDate                         = "HireDate"
	ReportingTo                      = "Reporting to"
)

Fields for GetEmployee

Types

type Client

type Client struct {
	// Base URL for Bamboo HR API which is set to v1 using the provided company domain if initiated with `bamboohr.New()`
	BaseURL string

	// HTTP Client to use for making requests allowing the user to supply their own if required.
	HTTPClient *http.Client

	// Base64 Encoded string based on the APIKey, used for Basic Authorization
	Auth string
}

Client represents connectivity to the bamboo hr API

func New

func New(apikey string, companyDomain string, client *http.Client) (*Client, error)

New is a helper function that returns a new instance of the bamboo hr client given a company domain and api key. An http.Client will be created if nil is provided.

func (*Client) GetEmployee

func (c *Client) GetEmployee(ctx context.Context, id string, fields ...EmployeeField) (Employee, error)

GetEmployee retrieves a specific employee by ID and allows the caller to specify fields. All fields are returned if none are specified.

func (*Client) GetEmployeeDirectory

func (c *Client) GetEmployeeDirectory(ctx context.Context) ([]Employee, error)

GetEmployeeDirectory returns a list of employees

func (*Client) GetEmployeeFilesAndCategories

func (c *Client) GetEmployeeFilesAndCategories(ctx context.Context, id string) ([]EmployeeCategory, error)

GetEmployeeFilesAndCategories returns a list of employee files and categories

func (*Client) UploadEmployeeFile

func (c *Client) UploadEmployeeFile(ctx context.Context, employeeID, categoryID, fileName, filePath, share string) error

UploadEmployeeFile uploads a file to a specific employees files under the given category ID. Beware the inconsistent ID types Bamboo uses. We require all strings here.

type Employee

type Employee struct {
	ID                 string
	DisplayName        string
	FirstName          string
	LastName           string
	PreferredName      string
	Gender             string
	JobTitle           string
	WorkPhone          string
	MobilePhone        string
	WorkEmail          string
	Department         string
	Location           string
	Division           string
	LinkedIn           string
	WorkPhoneExtension string
	PhotoUploaded      *bool // to avoid false when it's empty
	PhotoURL           string
	CanUploadPhoto     *int // to avoid 0 when it's empty
	HireDate           string
}

Employee represents a single person

type EmployeeCategory

type EmployeeCategory struct {
	ID                int
	Name              string
	CanRenameCategory string
	CanDeleteCategory string
	CanUploadFiles    string
	DisplayIfEmpty    string
	Files             []File
}

EmployeeCategory represents a files category (or folder!)

type EmployeeCategoryResponse

type EmployeeCategoryResponse struct {
	EmployeeID struct {
		ID int
	} `json:"employee"`
	Categories []EmployeeCategory
}

EmployeeCategoryResponse is the top level response from the API

type EmployeeField

type EmployeeField string

EmployeeField are fields that can be requested on GetEmployee

type EmployeeFields

type EmployeeFields []EmployeeField

EmployeeFields holds a slice of EmployeeField which are fields that can be requested on GetEmployee

func (EmployeeFields) Join

func (ef EmployeeFields) Join(sep string) string

Join concatenates the elements of EmployeeFields to create a single string. The separator is placed between elements in the resulting string.

type EmployeeResponse

type EmployeeResponse struct {
	Employees []Employee
}

EmployeeResponse is the top level response from the API

type File

type File struct {
	ID                int
	Name              string
	OriginalFileName  string
	Size              int
	DateCreated       string
	CreatedBy         string
	ShareWithEmployee string
}

File represents an individual file