: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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.mdindex 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.pyindex 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 reimport dataclasses-from collections.abc import Iterable, Iterator+from collections.abc import Callable, Iterable, Iteratorfrom datetime import UTC, date, datetime, timedeltafrom typing import Any, Optional, castfrom urllib.parse import parse_qs, quote, urlsplit@@ -11,6 +11,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.bamboohr.sBAMBOOHR_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.pyindex 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.pyindex 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 = 100HOLIDAYS_PAGE_SIZE = 100CUSTOM_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.pyindex 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([