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(data-warehouse): add 4 missing tables to the Ashby source (#121228)

Tom Owers1f78675e089c
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 8a3869615c70..b3636b34284a 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
@@ -901,7 +901,7 @@ Note: Diffed against Asana's official OpenAPI spec (3 MB, ~120 GET paths). Also
## Ashby — gaps
-Today (22): `application_feedback`, `application_history`, `applications`, `archive_reasons`, `candidate_tags`, `candidates`, `custom_fields`, `departments`, `interview_events`, `interview_schedules`, `interview_stages`, `interviews`, `job_postings`, `jobs`, `locations`, `offers`, `openings`, `projects`, `referrals`, `sequences`, `sources`, `users`
+Today (26): `application_feedback`, `application_hiring_team_roles`, `application_history`, `applications`, `archive_reasons`, `candidate_notes`, `candidate_tags`, `candidates`, `custom_fields`, `departments`, `interview_events`, `interview_schedules`, `interview_stage_groups`, `interview_stages`, `interviews`, `job_postings`, `jobs`, `locations`, `offers`, `openings`, `projects`, `referrals`, `sequences`, `sources`, `survey_submissions`, `users`
Diffed against: <https://developers.ashbyhq.com/reference/introduction>
@@ -911,10 +911,10 @@ Diffed against: <https://developers.ashbyhq.com/reference/introduction>
- [x] `application.listHistory` — stage-transition history; without it you cannot compute time-in-stage or funnel conversion (high)
- [x] `interviewStage.list` — lookup resolving the currentInterviewStage ID carried on every synced application (high)
- [x] `interviewEvent.list` — actual scheduled interview occurrences with interviewers and times, distinct from the interview definitions we sync (high)
-- [ ] `interviewStageGroup.list` — lookup grouping stages into funnel phases for stage-level reporting (medium)
-- [ ] `applicationHiringTeamRole.list` — membership table linking users to applications by role (recruiter, hiring manager) (medium)
-- [ ] `surveySubmission.list` — candidate survey responses (including DEI surveys) tied to applications (medium)
-- [ ] `candidate.listNotes` — recruiter notes per candidate, commonly wanted alongside candidates (medium)
+- [x] `interviewStageGroup.list` — lookup grouping stages into funnel phases for stage-level reporting (medium)
+- [x] `applicationHiringTeamRole.list` — membership table linking users to applications by role (recruiter, hiring manager) (medium)
+- [x] `surveySubmission.list` — candidate survey responses (including DEI surveys) tied to applications (medium)
+- [x] `candidate.listNotes` — recruiter notes per candidate, commonly wanted alongside candidates (medium)
- [ ] `closeReason.list` — lookup resolving why openings/jobs were closed; pairs with the archiveReasons we already sync (medium)
- [ ] `application.listCriteriaEvaluations` — structured per-criterion scores behind feedback, for calibrated scoring analysis (medium)
- [ ] `takeHomeAssignment.list` — assignment issue/completion records, a stage most funnels drop out at (medium)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/ashby.py b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/ashby.py
index fcb4a1f08c48..74885b0ed749 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/ashby.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/ashby.py
@@ -41,6 +41,8 @@ class AshbyResumeConfig:
"""Fan-out: how many parents in that page are already finished."""
child_cursor: Optional[str] = None
"""Fan-out: next page cursor for the parent currently in progress."""
+ variant_index: int = 0
+ """Variant listing: how many values of ``variant_param`` are already finished."""
def _headers() -> dict[str, str]:
@@ -170,26 +172,43 @@ def _listed_pages(
resumable_source_manager: ResumableSourceManager[AshbyResumeConfig],
) -> Iterator[list[dict[str, Any]]]:
resume = resumable_source_manager.load_state() if resumable_source_manager.can_resume() else None
-
- def save_checkpoint(cursor: Optional[str]) -> None:
- # Persist only when a next page remains; the checkpoint fires AFTER a page is yielded so a
- # crash re-fetches from the next page (already-yielded pages are persisted); merge/replace
- # dedupes on the primary key.
- if cursor:
- resumable_source_manager.save_state(AshbyResumeConfig(cursor=cursor))
-
- body: dict[str, Any] = {} if config.page_size is None else {"limit": config.page_size}
- for page, _ in _iter_pages(
- api_key,
- config.name,
- config.path,
- body,
- team_id,
- job_id,
- start_cursor=resume.cursor if resume else None,
- on_next_cursor=save_checkpoint,
- ):
- yield [row for item in page for row in (item.get(config.nested_field) or [])] if config.nested_field else page
+ start_cursor = resume.cursor if resume else None
+ variants: tuple[Optional[str], ...] = config.variant_values or (None,)
+ skip = resume.variant_index if resume else 0
+
+ for variant_index, variant in enumerate(variants):
+ if variant_index < skip:
+ continue
+ if variant_index > skip:
+ # Staged before this value's first page, so it covers every page of the values before it.
+ resumable_source_manager.save_state(AshbyResumeConfig(variant_index=variant_index))
+
+ def save_checkpoint(cursor: Optional[str], at: int = variant_index) -> None:
+ # Persist only when a next page remains; the checkpoint fires AFTER a page is yielded so a
+ # crash re-fetches from the next page (already-yielded pages are persisted); merge/replace
+ # dedupes on the primary key.
+ if cursor:
+ resumable_source_manager.save_state(AshbyResumeConfig(cursor=cursor, variant_index=at))
+
+ body: dict[str, Any] = {} if config.page_size is None else {"limit": config.page_size}
+ if config.variant_param and variant is not None:
+ body[config.variant_param] = variant
+
+ for page, _ in _iter_pages(
+ api_key,
+ config.name,
+ config.path,
+ body,
+ team_id,
+ job_id,
+ start_cursor=start_cursor,
+ on_next_cursor=save_checkpoint,
+ ):
+ yield (
+ [row for item in page for row in (item.get(config.nested_field) or [])] if config.nested_field else page
+ )
+
+ start_cursor = None
def _fanned_out_pages(
@@ -275,7 +294,7 @@ def ashby_source(
)
-def check_access(api_key: str, path: str) -> tuple[int, Optional[str]]:
+def check_access(api_key: str, path: str, body: Optional[dict[str, Any]] = None) -> tuple[int, Optional[str]]:
"""Probe a single endpoint to validate credentials.
Ashby's RPC endpoints are POST-only and report many failures as HTTP 200 with
@@ -286,7 +305,11 @@ def check_access(api_key: str, path: str) -> tuple[int, Optional[str]]:
session = make_tracked_session(redact_values=(api_key,))
try:
response = session.post(
- f"{ASHBY_BASE_URL}/{path}", json={"limit": 1}, auth=(api_key, ""), headers=_headers(), timeout=15
+ f"{ASHBY_BASE_URL}/{path}",
+ json={"limit": 1} if body is None else body,
+ auth=(api_key, ""),
+ headers=_headers(),
+ timeout=15,
)
except Exception as e:
return 0, f"Could not connect to Ashby: {e}"
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/canonical_descriptions.py
index 623579f3bc17..79c1b977f45e 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/canonical_descriptions.py
@@ -281,4 +281,48 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
extraData="Arbitrary key/value pairs stored against the event.",
),
},
+ "interview_stage_groups": {
+ "description": "A group of interview stages that forms one phase of the hiring funnel. Resolves the interviewStageGroupId carried on interview stages.",
+ "docs_url": "https://developers.ashbyhq.com/reference/interviewstagegrouplist",
+ "columns": {
+ "id": "Unique identifier for the interview stage group.",
+ "title": "The stage group's title.",
+ "order": "Position of the stage group in the organization's ordered list of groups.",
+ "stageType": "Type of the stages in the group (Lead, PreInterviewScreen, Active, Offer, Hired, Archived).",
+ },
+ },
+ "application_hiring_team_roles": {
+ "description": "A hiring team role that users can hold on an application, such as recruiter or hiring manager.",
+ "docs_url": "https://developers.ashbyhq.com/reference/applicationhiringteamrolelist",
+ "columns": {
+ "id": "Unique identifier for the application hiring team role.",
+ "title": "The role's title.",
+ },
+ },
+ "survey_submissions": {
+ "description": "A submitted candidate experience, questionnaire, or hiring manager experience survey.",
+ "docs_url": "https://developers.ashbyhq.com/reference/surveysubmissionlist",
+ "columns": {
+ "id": "Unique identifier for the survey submission.",
+ "surveyFormDefinitionId": "ID of the survey form definition, if any.",
+ "submittedAt": "Time at which the survey was submitted.",
+ "candidateId": "ID of the candidate the submission belongs to.",
+ "applicationId": "ID of the application the submission belongs to, if any.",
+ "surveyType": "Type of the survey (CandidateExperience, Questionnaire, HiringManagerExperience).",
+ "formDefinition": "The survey form's sections and fields.",
+ "submittedValues": "The submitted answers, keyed by the path of each form field.",
+ },
+ },
+ "candidate_notes": {
+ "description": "A note added to a candidate in Ashby.",
+ "docs_url": "https://developers.ashbyhq.com/reference/candidatelistnotes",
+ "columns": {
+ "id": "Unique identifier for the note.",
+ "candidateId": "ID of the candidate the note belongs to.",
+ "createdAt": "Time at which the note was created.",
+ "isPrivate": "Whether the note is private.",
+ "content": "The note's content as plain text.",
+ "author": "The user who created the note.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/settings.py
index ca063f419a99..2aad81ca1ce1 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/settings.py
@@ -1,5 +1,5 @@
from dataclasses import dataclass
-from typing import Optional
+from typing import Any, Optional
PAGE_SIZE = 100 # Ashby's documented max (and default).
@@ -34,6 +34,9 @@ class AshbyEndpointConfig:
"""Rows come from this array on each item of ``path``, instead of from the items themselves."""
fanout: Optional[AshbyFanoutConfig] = None
"""Set when ``path`` must be called once per parent row rather than listed directly."""
+ variant_param: Optional[str] = None
+ """Required request-body key that ``path`` is listed once per value of ``variant_values`` for."""
+ variant_values: tuple[str, ...] = ()
@property
def probe_path(self) -> str:
@@ -44,6 +47,16 @@ class AshbyEndpointConfig:
"""
return self.fanout.parent_path if self.fanout else self.path
+ @property
+ def probe_body(self) -> dict[str, Any]:
+ """Smallest valid request body for ``probe_path``."""
+ if self.fanout:
+ return {"limit": 1}
+ body: dict[str, Any] = {} if self.page_size is None else {"limit": 1}
+ if self.variant_param and self.variant_values:
+ body[self.variant_param] = self.variant_values[0]
+ return body
+
# Every Ashby object exposes a top-level ``id``, so the primary key is ``["id"]`` throughout.
#
@@ -112,6 +125,33 @@ ASHBY_ENDPOINTS: dict[str, AshbyEndpointConfig] = {
# instead of calling interviewEvent.list once per schedule.
nested_field="interviewEvents",
),
+ "interview_stage_groups": AshbyEndpointConfig(
+ name="interview_stage_groups", path="interviewStageGroup.list", primary_key=["id"], page_size=None
+ ),
+ "application_hiring_team_roles": AshbyEndpointConfig(
+ name="application_hiring_team_roles",
+ path="applicationHiringTeamRole.list",
+ primary_key=["id"],
+ page_size=None,
+ ),
+ "survey_submissions": AshbyEndpointConfig(
+ name="survey_submissions",
+ path="surveySubmission.list",
+ primary_key=["id"],
+ partition_key="submittedAt",
+ # surveyType is required, and these are the only types the method lists.
+ variant_param="surveyType",
+ variant_values=("CandidateExperience", "Questionnaire", "HiringManagerExperience"),
+ ),
+ "candidate_notes": AshbyEndpointConfig(
+ name="candidate_notes",
+ path="candidate.listNotes",
+ primary_key=["candidateId", "id"],
+ partition_key="createdAt",
+ fanout=AshbyFanoutConfig(
+ parent_path="candidate.list", resolve_param="candidateId", parent_id_field="candidateId"
+ ),
+ ),
}
ENDPOINTS = tuple(ASHBY_ENDPOINTS.keys())
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/source.py
index 92af1d2b75e4..f9da6289ad49 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/source.py
@@ -99,8 +99,11 @@ You can create an API key under **Admin → API Keys** in Ashby. Grant read perm
if schema_name is not None and schema_name not in ASHBY_ENDPOINTS:
return False, f"Unknown Ashby schema '{schema_name}'"
- path = ASHBY_ENDPOINTS[schema_name].probe_path if schema_name is not None else DEFAULT_PROBE_PATH
- status, message = check_access(config.api_key, path)
+ if schema_name is not None:
+ endpoint_config = ASHBY_ENDPOINTS[schema_name]
+ status, message = check_access(config.api_key, endpoint_config.probe_path, endpoint_config.probe_body)
+ else:
+ status, message = check_access(config.api_key, DEFAULT_PROBE_PATH)
if status == 200:
return True, None
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby.py b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby.py
index 9de12dbf33f8..82c857c9866b 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby.py
@@ -148,29 +148,38 @@ class TestCheckAccess:
class TestFanOut:
- def test_calls_the_child_once_per_parent_and_injects_the_parent_id(self) -> None:
+ @pytest.mark.parametrize(
+ "endpoint, parent_path, child_path, parent_id_field",
+ [
+ ("application_history", "application.list", "application.listHistory", "applicationId"),
+ ("candidate_notes", "candidate.list", "candidate.listNotes", "candidateId"),
+ ],
+ )
+ def test_calls_the_child_once_per_parent_and_injects_the_parent_id(
+ self, endpoint: str, parent_path: str, child_path: str, parent_id_field: str
+ ) -> None:
result = _driver().run(
- "application_history",
+ endpoint,
[
- _page([{"id": "app-1"}, {"id": "app-2"}]),
- _page([{"id": "h-1", "stageNumber": 0}]),
- _page([{"id": "h-2", "stageNumber": 0}]),
+ _page([{"id": "parent-1"}, {"id": "parent-2"}]),
+ _page([{"id": "child-1"}]),
+ _page([{"id": "child-2"}]),
],
)
assert result.raised is None
- # application.listHistory rows carry no applicationId, so the fan-out has to add it —
- # without it the table can't be joined back to applications and its key isn't unique.
+ # The child rows carry no parent id, so the fan-out has to add it — without it the table
+ # can't be joined back to its parent and its key isn't unique.
assert result.rows == [
- {"id": "h-1", "stageNumber": 0, "applicationId": "app-1"},
- {"id": "h-2", "stageNumber": 0, "applicationId": "app-2"},
+ {"id": "child-1", parent_id_field: "parent-1"},
+ {"id": "child-2", parent_id_field: "parent-2"},
]
assert result.urls == [
- f"{ASHBY_BASE_URL}/application.list",
- f"{ASHBY_BASE_URL}/application.listHistory",
- f"{ASHBY_BASE_URL}/application.listHistory",
+ f"{ASHBY_BASE_URL}/{parent_path}",
+ f"{ASHBY_BASE_URL}/{child_path}",
+ f"{ASHBY_BASE_URL}/{child_path}",
]
- assert result.requests[1].json() == {"applicationId": "app-1", "limit": 100}
- assert result.requests[2].json() == {"applicationId": "app-2", "limit": 100}
+ assert result.requests[1].json() == {parent_id_field: "parent-1", "limit": 100}
+ assert result.requests[2].json() == {parent_id_field: "parent-2", "limit": 100}
def test_unpaginated_child_sends_only_the_resolve_param(self) -> None:
# interviewStage.list takes interviewPlanId and nothing else — Ashby rejects a `limit`.
@@ -214,6 +223,78 @@ class TestFanOut:
]
+class TestUnpaginatedListing:
+ @pytest.mark.parametrize(
+ "endpoint, path",
+ [
+ ("interview_stage_groups", "interviewStageGroup.list"),
+ ("application_hiring_team_roles", "applicationHiringTeamRole.list"),
+ ],
+ )
+ def test_sends_an_empty_body(self, endpoint: str, path: str) -> None:
+ # These methods accept no request-body keys, and Ashby rejects a `limit`.
+ result = _driver().run(endpoint, [_page([{"id": "1", "title": "Screen"}])])
+ assert result.raised is None
+ assert result.rows == [{"id": "1", "title": "Screen"}]
+ assert result.urls == [f"{ASHBY_BASE_URL}/{path}"]
+ assert result.requests[0].json() == {}
+
+
+class TestVariantListing:
+ def test_lists_each_survey_type_in_turn(self) -> None:
+ result = _driver().run(
+ "survey_submissions",
+ [
+ _page([{"id": "s-1", "surveyType": "CandidateExperience"}], more=True, next_cursor="c1"),
+ _page([{"id": "s-2", "surveyType": "CandidateExperience"}]),
+ _page([]),
+ _page([{"id": "s-3", "surveyType": "HiringManagerExperience"}]),
+ ],
+ )
+ assert result.raised is None
+ assert [row["id"] for row in result.rows] == ["s-1", "s-2", "s-3"]
+ assert all(url == f"{ASHBY_BASE_URL}/surveySubmission.list" for url in result.urls)
+ assert [request.json() for request in result.requests] == [
+ {"limit": 100, "surveyType": "CandidateExperience"},
+ {"limit": 100, "surveyType": "CandidateExperience", "cursor": "c1"},
+ {"limit": 100, "surveyType": "Questionnaire"},
+ {"limit": 100, "surveyType": "HiringManagerExperience"},
+ ]
+ # The cursor of one survey type must never be sent with the next one.
+ assert result.saved_states == [
+ AshbyResumeConfig(cursor="c1", variant_index=0),
+ AshbyResumeConfig(variant_index=1),
+ AshbyResumeConfig(variant_index=2),
+ ]
+
+ @pytest.mark.parametrize(
+ "resume_state, expected_bodies",
+ [
+ (
+ AshbyResumeConfig(cursor="half-way", variant_index=1),
+ [
+ {"limit": 100, "surveyType": "Questionnaire", "cursor": "half-way"},
+ {"limit": 100, "surveyType": "HiringManagerExperience"},
+ ],
+ ),
+ (
+ AshbyResumeConfig(variant_index=2),
+ [{"limit": 100, "surveyType": "HiringManagerExperience"}],
+ ),
+ ],
+ )
+ def test_resumes_at_the_survey_type_in_progress(
+ self, resume_state: AshbyResumeConfig, expected_bodies: list[dict[str, Any]]
+ ) -> None:
+ result = _driver().run(
+ "survey_submissions",
+ [_page([{"id": f"s-{index}"}]) for index in range(len(expected_bodies))],
+ resume_state=resume_state,
+ )
+ assert result.raised is None
+ assert [request.json() for request in result.requests] == expected_bodies
+
+
class TestNestedRows:
def test_interview_events_are_read_from_the_schedule_listing(self) -> None:
result = _driver().run(
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby_source.py
index cbbbc83f59de..d78fd49cc5f4 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby_source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/ashby/tests/test_ashby_source.py
@@ -50,16 +50,26 @@ class TestAshbySource:
assert network.requests_log[0].headers["authorization"] == "Basic YXNoYnkta2V5Og=="
@pytest.mark.parametrize(
- "schema_name, expected_path",
- [("application_history", "/application.list"), ("interview_stages", "/interviewPlan.list")],
+ "schema_name, expected_path, expected_body",
+ [
+ # The fan-out child methods need a parent id, so probing them directly always fails.
+ ("application_history", "/application.list", {"limit": 1}),
+ ("interview_stages", "/interviewPlan.list", {"limit": 1}),
+ ("candidate_notes", "/candidate.list", {"limit": 1}),
+ # These methods reject unknown request-body keys, so the probe must not send a limit.
+ ("interview_stage_groups", "/interviewStageGroup.list", {}),
+ ("application_hiring_team_roles", "/applicationHiringTeamRole.list", {}),
+ # surveyType is required.
+ ("survey_submissions", "/surveySubmission.list", {"limit": 1, "surveyType": "CandidateExperience"}),
+ ],
)
- def test_validate_credentials_probes_the_parent_of_a_fanned_out_schema(
- self, schema_name: str, expected_path: str
+ def test_validate_credentials_sends_a_valid_probe_for_the_schema(
+ self, schema_name: str, expected_path: str, expected_body: dict
) -> None:
- # The child methods need a parent id, so probing them directly always fails.
with scripted_network([ScriptedResponse(json={"success": True})]) as network:
self.source.validate_credentials(self.config, self.team_id, schema_name=schema_name)
assert network.requests_log[0].path == expected_path
+ assert network.requests_log[0].json() == expected_body
def test_validate_credentials_uses_default_probe_without_schema(self) -> None:
with scripted_network([ScriptedResponse(json={"success": True})]) as network: