Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(bamboohr): add time tracking setup and custom field list value tables (#119195)

Tom Owers0fb61dd0340d
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index 149363af5d03..100bf2a45d67 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -1434,7 +1434,7 @@ Note: The official portal links directly to the bundled OpenAPI file, which list
## BambooHR — **thin**
-Today (28): `applicant_statuses`, `application_details`, `applications`, `archived_custom_fields`, `ats_locations`, `clock_entries`, `custom_fields`, `employee_compensation`, `employee_employment_status`, `employee_goal_comments`, `employee_goals`, `employee_job_info`, `employee_time_off_balances`, `employee_time_off_policies`, `employees`, `holidays`, `hour_entries`, `job_openings`, `locations`, `meta_fields`, `meta_lists`, `meta_users`, `time_off_policies`, `time_off_requests`, `time_off_types`, `timesheet_entries`, `timesheets`, `whos_out`
+Today (33): `applicant_statuses`, `application_details`, `applications`, `archived_custom_fields`, `ats_locations`, `clock_entries`, `custom_field_list_values`, `custom_fields`, `employee_compensation`, `employee_employment_status`, `employee_goal_comments`, `employee_goals`, `employee_job_info`, `employee_time_off_balances`, `employee_time_off_policies`, `employees`, `holidays`, `hour_entries`, `job_openings`, `locations`, `meta_fields`, `meta_lists`, `meta_users`, `time_off_policies`, `time_off_requests`, `time_off_types`, `time_tracking_configurations`, `time_tracking_employees`, `time_tracking_kiosks`, `time_tracking_time_clocks`, `timesheet_entries`, `timesheets`, `whos_out`
Diffed against: <https://documentation.bamboohr.com/sitemap.xml>
@@ -1455,6 +1455,11 @@ Diffed against: <https://documentation.bamboohr.com/sitemap.xml>
- [x] `GET /api/v1/time-tracking/clock-entries` — clock-in/clock-out entries per timesheet, from the newer time-tracking API (high)
- [x] `GET /api/v1/holidays` — company holidays with audience and pay treatment; before this they only appeared as rows inside whos_out (medium)
- [x] `GET /api/v1/hris/custom-fields (plus /archived)` — custom field and custom table definitions, active and archived (medium)
+- [x] `GET /api/v1/time-tracking/employees` — time tracking enrollment per employee, with the configuration each one tracks under (medium)
+- [x] `GET /api/v1/time-tracking/configurations` — time tracking configurations: timesheet type, approver and overtime rules (medium)
+- [x] `GET /api/v1/time-tracking/kiosks` — shared kiosks employees clock in on (low)
+- [x] `GET /api/v1/time-tracking/time-clocks` — hardware time clocks and their connection status (low)
+- [x] `GET /api/v1/hris/custom-fields/{customFieldId}/list-values` — dropdown options of list-type custom fields, with the employee count per option (medium)
Note: documentation.bamboohr.com is a ReadMe site with no public OpenAPI download (the /reference slug in the source config 404s), but its sitemap enumerates all 312 reference pages, which is what I diffed against. Six tables against roughly 130 GET endpoints spanning employees, time off, time tracking, scheduling, benefits, goals, training, ATS, compensation benchmarks and reports. Also below the cut: employee dependents, scheduling shifts/schedules, compensation benchmarks, bank holidays, break policies.
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/bamboohr.py b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/bamboohr.py
index a4ed66c8d159..bcc2a6cc4a5d 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/bamboohr.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/bamboohr.py
@@ -1,6 +1,6 @@
import re
import dataclasses
-from collections.abc import Iterable, Iterator
+from collections.abc import Callable, Iterable, Iterator
from datetime import UTC, date, datetime, timedelta
from typing import Any, Optional, cast
from urllib.parse import parse_qs, quote, urlsplit
@@ -11,6 +11,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.bamboohr.s
BAMBOOHR_ENDPOINTS,
EMPLOYEE_TABLE_EMPLOYEE_ID,
EMPLOYEE_TABLE_LAST_CHANGED,
+ ENCODED_PARENT_ID,
GOAL_ID,
BambooHREndpointConfig,
ChunkedDateWindow,
@@ -278,6 +279,13 @@ def _rest_client(base_url: str, api_key: str) -> RESTClient:
)
+def _encode_parent_id(field: str) -> Callable[[dict[str, Any]], dict[str, Any]]:
+ def encode(row: dict[str, Any]) -> dict[str, Any]:
+ return {**row, ENCODED_PARENT_ID: quote(str(row[field]), safe="")}
+
+ return encode
+
+
def _employee_table_rows(body: Any) -> Iterator[dict[str, Any]]:
"""Flatten one ``employees/changed/tables/{table}`` response into rows.
@@ -489,6 +497,7 @@ def bamboohr_source(
page_size_param=None,
parent_endpoint_extra=_endpoint_extra(parent_config),
child_endpoint_extra=_endpoint_extra(config),
+ parent_data_map=(_encode_parent_id(config.encode_parent_field) if config.encode_parent_field else None),
),
)
return SourceResponse(
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/canonical_descriptions.py
index 22c84094bccf..9c1ed5d312e1 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/canonical_descriptions.py
@@ -358,6 +358,67 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"updatedAt": "Time at which the entry was last changed.",
},
},
+ "time_tracking_employees": {
+ "description": "An employee's time tracking enrollment, with the configuration they track time under.",
+ "docs_url": "https://documentation.bamboohr.com/reference/list-time-tracking-employees",
+ "columns": {
+ "id": "Unique identifier for the enrollment record.",
+ "employeeId": "ID of the employee.",
+ "configurationId": "ID of the time tracking configuration the employee is enrolled in. Null means the company's GLOBAL configuration.",
+ "enabled": "Whether the employee is enrolled in time tracking.",
+ "enabledOn": "Date time tracking was enabled for the employee. Null if never enabled.",
+ "timezone": "IANA timezone used for the employee's time tracking.",
+ "clockInId": "Kiosk or badge clock-in ID of the employee. Unique per company.",
+ "createdAt": "Time at which the enrollment record was created.",
+ "updatedAt": "Time at which the enrollment record was last changed.",
+ },
+ },
+ "time_tracking_configurations": {
+ "description": "A time tracking configuration: how a group of employees logs time, who approves it and the overtime rules.",
+ "docs_url": "https://documentation.bamboohr.com/reference/list-time-tracking-configurations",
+ "columns": {
+ "id": "Unique identifier for the configuration.",
+ "name": "Name of the configuration. Unique per company.",
+ "type": "GLOBAL for the one company-wide configuration, GROUP for every other configuration.",
+ "timesheetType": "How time is logged: CLOCK, SINGLE, MULTIPLE or HOUR.",
+ "workWeekStartsOn": "Day of the week the work week starts.",
+ "approverType": "Who approves timesheets: REPORTS_TO (the employee's manager) or SPECIFIC_PERSON.",
+ "approverUserId": "User ID of the approver when approverType is SPECIFIC_PERSON.",
+ "approvalCutoff": "Time of day by which timesheets must be approved, in 24-hour HH:MM format.",
+ "approvalCutoffDays": "Number of days before the pay date the approval cutoff applies.",
+ "clockInSchedulePolicy": "When scheduled employees can clock in: ANYTIME or SHIFT_REQUIRED.",
+ "mobileEnabled": "Whether employees can log time in the BambooHR mobile app.",
+ "customOvertimeEnabled": "Whether the daily and weekly overtime thresholds apply instead of the standard U.S. and Canada rules.",
+ "overtimeDailyHours": "Daily overtime threshold in hours, when custom overtime is enabled.",
+ "overtimeWeeklyHours": "Weekly overtime threshold in hours, when custom overtime is enabled.",
+ "employeeIds": "IDs of the employees enrolled in the configuration.",
+ "createdAt": "Time at which the configuration was created.",
+ "updatedAt": "Time at which the configuration was last changed.",
+ },
+ },
+ "time_tracking_kiosks": {
+ "description": "A shared device employees clock in and out on.",
+ "docs_url": "https://documentation.bamboohr.com/reference/list-time-tracking-kiosks",
+ "columns": {
+ "id": "Unique identifier for the kiosk.",
+ "name": "Name of the kiosk.",
+ "lastUsed": "Time at which the kiosk last recorded a clock entry. Null if never used.",
+ "createdAt": "Time at which the kiosk was created.",
+ "updatedAt": "Time at which the kiosk was last changed. Null if never changed.",
+ },
+ },
+ "time_tracking_time_clocks": {
+ "description": "A BambooHR hardware time clock and its connection status.",
+ "docs_url": "https://documentation.bamboohr.com/reference/list-time-tracking-time-clocks",
+ "columns": {
+ "id": "Unique identifier for the time clock.",
+ "name": "Name of the time clock.",
+ "serialNumber": "Manufacturer serial number of the device.",
+ "type": "Hardware model of the time clock: TIME_CLOCK or TIME_CLOCK_PLUS.",
+ "online": "Whether the device is reachable. Null when device status is unavailable.",
+ "timezone": "IANA timezone the device records clock entries in.",
+ },
+ },
"holidays": {
"description": "An active company holiday, with the employees it applies to and its pay treatment.",
"docs_url": "https://documentation.bamboohr.com/reference/list-company-holidays",
@@ -404,4 +465,15 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"type": "Type of the custom field or custom table.",
},
},
+ "custom_field_list_values": {
+ "description": "A dropdown option of a list-type custom field, with the number of employees who use it.",
+ "docs_url": "https://documentation.bamboohr.com/reference/list-custom-field-list-values",
+ "columns": {
+ "customFieldId": "ID of the custom field the option belongs to.",
+ "id": "Unique identifier for the list value within its custom field.",
+ "legacyId": "Numeric ID of the list value, as the older API endpoints use it.",
+ "display": "Display name of the list value.",
+ "count": "Number of employees who use the list value.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/settings.py
index ed1027cdef66..73169f1765f6 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/settings.py
@@ -31,10 +31,17 @@ EMPLOYEE_TABLE_EMPLOYEE_ID = "employeeId"
# Goal comments are addressed by employee *and* goal, and the comment rows carry neither.
GOAL_ID = "goalId"
+# List values are addressed by their custom field, and the value rows do not carry it.
+CUSTOM_FIELD_ID = "customFieldId"
+
+# Parent row key holding the percent-encoded copy of a fan-out parent id, for the child path.
+ENCODED_PARENT_ID = "_encoded_parent_id"
+
# BambooHR's org locations endpoint is the only one that takes a page size.
LOCATIONS_PAGE_SIZE = 500
# The documented maximum page size of each newer collection endpoint.
TIME_TRACKING_PAGE_SIZE = 200
+TIME_TRACKING_SETUP_PAGE_SIZE = 100
HOLIDAYS_PAGE_SIZE = 100
CUSTOM_FIELDS_PAGE_SIZE = 1000
@@ -70,6 +77,9 @@ class BambooHREndpointConfig:
chunked_date_window: ChunkedDateWindow | None = None
# Fan-out over a parent listing, for endpoints addressed by a single parent record.
fanout: DependentEndpointConfig | None = None
+ # Parent field to percent-encode before the fan-out binds it into the child path, for ids
+ # that are not known to be numeric. The fan-out must resolve on ENCODED_PARENT_ID.
+ encode_parent_field: str | None = None
# Set when the endpoint is two fan-out levels deep, which the single-hop helper cannot express.
custom_iterator: Literal["goal_comments"] | None = None
# Static query params every request for this endpoint carries.
@@ -139,6 +149,35 @@ def _time_tracking_endpoint(name: str, resource: str, sort: str) -> BambooHREndp
)
+_CUSTOM_FIELD_FANOUT = DependentEndpointConfig(
+ parent_name="custom_fields",
+ resolve_param=CUSTOM_FIELD_ID,
+ resolve_field=ENCODED_PARENT_ID,
+ include_from_parent=["id"],
+ parent_field_renames={"id": CUSTOM_FIELD_ID},
+ parent_params={"pageSize": CUSTOM_FIELDS_PAGE_SIZE},
+ # The listing has no type filter, so every custom field is asked for its list values. The
+ # docs answer 422 for an id the endpoint rejects, taken here as a field that is not list-type,
+ # and a field deleted after the listing 404s.
+ child_response_actions=[
+ {"status_code": 404, "action": "ignore", "message": None},
+ {"status_code": 422, "action": "ignore", "message": None},
+ ],
+)
+
+
+def _time_tracking_setup_endpoint(name: str, resource: str, order_by: str) -> BambooHREndpointConfig:
+ return BambooHREndpointConfig(
+ name=name,
+ path=f"v1/time-tracking/{resource}",
+ data_key="data",
+ primary_keys=["id"],
+ pagination="page_links",
+ # The default sort is by name, which a rename reorders mid-walk.
+ params={"orderBy": order_by, "pageSize": TIME_TRACKING_SETUP_PAGE_SIZE},
+ )
+
+
def _employee_table_endpoint(name: str, table: str) -> BambooHREndpointConfig:
return BambooHREndpointConfig(
name=name,
@@ -287,6 +326,16 @@ BAMBOOHR_ENDPOINTS: dict[str, BambooHREndpointConfig] = {
"timesheets": _time_tracking_endpoint("timesheets", "timesheets", "startDate asc"),
"hour_entries": _time_tracking_endpoint("hour_entries", "hour-entries", "date asc"),
"clock_entries": _time_tracking_endpoint("clock_entries", "clock-entries", "start asc"),
+ "time_tracking_employees": _time_tracking_setup_endpoint("time_tracking_employees", "employees", "employeeId asc"),
+ "time_tracking_configurations": _time_tracking_setup_endpoint(
+ "time_tracking_configurations", "configurations", "createdAt asc"
+ ),
+ # Kiosks can filter on updatedAt, but it stays null until the first edit, so a filter on it
+ # would never pick up a new kiosk.
+ "time_tracking_kiosks": _time_tracking_setup_endpoint("time_tracking_kiosks", "kiosks", "createdAt asc"),
+ "time_tracking_time_clocks": _time_tracking_setup_endpoint(
+ "time_tracking_time_clocks", "time-clocks", "serialNumber asc"
+ ),
"holidays": BambooHREndpointConfig(
name="holidays",
path="v1/holidays",
@@ -311,6 +360,17 @@ BAMBOOHR_ENDPOINTS: dict[str, BambooHREndpointConfig] = {
pagination="page_links",
params={"pageSize": CUSTOM_FIELDS_PAGE_SIZE},
),
+ "custom_field_list_values": BambooHREndpointConfig(
+ name="custom_field_list_values",
+ path="v1/hris/custom-fields/{customFieldId}/list-values",
+ data_key="values",
+ # A list value id is only documented as unique within its field.
+ primary_keys=[CUSTOM_FIELD_ID, "id"],
+ pagination="single",
+ fanout=_CUSTOM_FIELD_FANOUT,
+ # Custom field ids are strings, and the path binding applies no escaping.
+ encode_parent_field="id",
+ ),
}
ENDPOINTS = tuple(BAMBOOHR_ENDPOINTS.keys())
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/tests/test_bamboohr.py b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/tests/test_bamboohr.py
index 22278060ca9d..32c65e90f0da 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/tests/test_bamboohr.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/bamboohr/tests/test_bamboohr.py
@@ -18,6 +18,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.bamboohr.b
)
from products.warehouse_sources.backend.temporal.data_imports.sources.bamboohr.settings import (
BAMBOOHR_ENDPOINTS,
+ CUSTOM_FIELD_ID,
+ CUSTOM_FIELDS_PAGE_SIZE,
EMPLOYEE_TABLE_EMPLOYEE_ID,
GOAL_ID,
LOCATIONS_PAGE_SIZE,
@@ -420,6 +422,25 @@ class TestPageLinksPagination:
("holidays", "v1/holidays", {"orderBy": "startDate asc", "pageSize": 100}, {"next": None}),
("custom_fields", "v1/hris/custom-fields", {"pageSize": 1000}, {"next": None}),
("archived_custom_fields", "v1/hris/custom-fields/archived", {"pageSize": 1000}, {}),
+ (
+ "time_tracking_employees",
+ "v1/time-tracking/employees",
+ {"orderBy": "employeeId asc", "pageSize": 100},
+ {},
+ ),
+ (
+ "time_tracking_configurations",
+ "v1/time-tracking/configurations",
+ {"orderBy": "createdAt asc", "pageSize": 100},
+ {},
+ ),
+ ("time_tracking_kiosks", "v1/time-tracking/kiosks", {"orderBy": "createdAt asc", "pageSize": 100}, {}),
+ (
+ "time_tracking_time_clocks",
+ "v1/time-tracking/time-clocks",
+ {"orderBy": "serialNumber asc", "pageSize": 100},
+ {},
+ ),
]
)
def test_walks_pages_by_the_next_link(
@@ -516,6 +537,41 @@ class TestGoalStreams:
assert result.paths[1] == ("/api/gateway.php/acme/v1/performance/employees/7%2F..%2F..%2Fmeta%2Fusers%3F/goals")
+class TestCustomFieldListValues:
+ def test_values_carry_their_field_and_non_list_fields_are_skipped(self) -> None:
+ responses = [
+ ScriptedResponse(json={"data": [{"id": "4001"}, {"id": "4002"}], "_links": {}}),
+ ScriptedResponse(
+ json={"id": "4001", "type": "list", "values": [{"id": "1", "display": "Red", "count": 3}]}
+ ),
+ ScriptedResponse(status=422, json={"title": "Invalid custom field ID."}),
+ ]
+
+ result = _driver().run("custom_field_list_values", responses)
+
+ # Value ids repeat across fields, so the field id has to be on every row.
+ assert result.raised is None
+ assert result.rows == [{"id": "1", "display": "Red", "count": 3, CUSTOM_FIELD_ID: "4001"}]
+ assert result.paths == [
+ "/api/gateway.php/acme/v1/hris/custom-fields",
+ "/api/gateway.php/acme/v1/hris/custom-fields/4001/list-values",
+ "/api/gateway.php/acme/v1/hris/custom-fields/4002/list-values",
+ ]
+ assert result.queries[0] == {"pageSize": (str(CUSTOM_FIELDS_PAGE_SIZE),)}
+
+ def test_field_ids_from_the_api_cannot_extend_the_request_path(self) -> None:
+ responses = [
+ ScriptedResponse(json={"data": [{"id": "../../other?x="}], "_links": {}}),
+ ScriptedResponse(json={"id": "x", "values": [{"id": "1"}]}),
+ ]
+
+ result = _driver().run("custom_field_list_values", responses)
+
+ assert result.raised is None
+ assert result.paths[1] == "/api/gateway.php/acme/v1/hris/custom-fields/..%2F..%2Fother%3Fx%3D/list-values"
+ assert result.rows == [{"id": "1", CUSTOM_FIELD_ID: "../../other?x="}]
+
+
class TestEndpointCatalog:
@parameterized.expand(
[