From 1ccfec97ea02ba05b6a466f67368e7fd36a08346 Mon Sep 17 00:00:00 2001 From: Wolf Date: Wed, 30 Sep 2026 15:44:06 +0200 Subject: [PATCH] Correct docs/filter-survey.md against the readers and say what F2 landed as State which hosts the survey covers and which it leaves out, fix the Workday and Oracle facet names, the All countries versus All roles sentence and the places-in-reach claim, mark the Workable, Teamtailor and Jibe query rows as not built, and reword the plan voice and first person. Co-Authored-By: Claude Fable 5.1 --- docs/filter-survey.md | 50 ++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/filter-survey.md b/docs/filter-survey.md index 4584096..a4b8bd1 100644 --- a/docs/filter-survey.md +++ b/docs/filter-survey.md @@ -1,6 +1,6 @@ # Survey: which filters the hosts take at the source -Surveyed 2026-09-30 for the fetch terms (see `decisions.md`, Ingestion); kept as the reference for each host's filter parameters. Each host got at most two live requests, one small page each, against boards that are already attached (`roledesk.db` opened read-only for the targets). Nothing else was read except one page of HTML or JS where noted. +Surveyed 2026-09-30 for the fetch terms (see `decisions.md`, Ingestion); kept as the reference for each host's filter parameters. Each host got at most two live requests, one small page each, against boards that are already attached (`roledesk.db` opened read-only for the targets). Nothing else was read except one page of HTML or JS where noted. It covers the nine readers that declare a filter (SmartRecruiters, SuccessFactors, Workday, Oracle, Phenom, Eightfold, Jobindex, Platsbanken, Adzuna) and Workable, Teamtailor, Jibe and Lever, which declare none. Greenhouse, Ashby, Recruitee, Personio, Pinpoint, Deel, HiBob, HR Manager, Gem, Jobylon, Rippling and BambooHR take no filter at the source and were not surveyed. Sections 2 and 3 began as the plan for the fetch terms, which it called F2; F2 has landed (`decisions.md`, Fetch terms), and those sections now say what was recommended and what became of it. Marks used in the table: @@ -72,7 +72,7 @@ Country and remote are left out; they are in the readers already. "Combine" is h | category | `appliedFacets.jobFamily=[, ...]` (30 values on LEGO); the parameter name is the tenant's (`jobFamilyGroup` elsewhere) | ids in one facet union: Mechanical Engineering (4) plus IT Engineering (8) with Denmark and `engineer` answered 12 | AND across facets and with `searchText` | untested | live | | level | no level facet on LEGO; `jobFamily` has "Trainee / Intern / Apprentice" | | | | live | | employment | `workerSubType` ("Job Type": Regular, Education Fixed Term, Student Worker, Temporary) and `timeType` (Full time, Part time) | as `jobFamily` | AND | untested | live | -| place | LEGO's `Location` facet lists countries only (13 values); other tenants nest a city facet under `locationMainGroup` | as `jobFamily` | | | code | +| place | LEGO's `Location` facet lists countries only (13 values); on some tenants `locationMainGroup` holds `locationCountry`, another country facet, and no city facet was seen | as `jobFamily` | | | code | | notes | The reader's `facets` call already reads facet ids off one page; the facet list responds to `searchText` (counts change) | | | | live | ### Oracle Recruiting Cloud (`oracle:fa-evmr-saasfaprod1.fa.ocs.oraclecloud.com/CX_1`, Nokia, 554 roles) @@ -86,7 +86,7 @@ Requests go through `finder=findReqs;siteNumber=CX_1,=,...`. | category | `selectedCategoriesFacet=` from `categoriesFacet` (10 values: Applied R&D 259, Direct Production 55 under the keyword) | joined with `;` (`%3B`): two ids answered 314 = 259 + 55 with the keyword: union | AND with the keyword | an id the pod does not know answers the whole board (superset) | live; unknown from code | | level | none: `titlesFacet` holds function codes (`SWA` Software, `TRA` Trainee), `flexFieldsFacet` holds unnamed attributes | | | | live | | employment | none seen; `selectedWorkplaceTypesFacet` is the work-location type (`ORA_HYBRID`, `ORA_ON_SITE`, `ORA_REMOTE`) | | | | live | -| place | `selectedLocationsFacet` lists 10 countries only; `workLocationsFacet` lists sites; the answer also echoes `Location`, `LocationId` and `Radius`, which suggests a free place search | | | | live, untested | +| place | `locationsFacet`, the response facet, lists 10 countries only, and `selectedLocationsFacet` is the request parameter that takes its ids; `workLocationsFacet` lists sites; the answer also echoes `Location`, `LocationId` and `Radius`, which suggests a free place search | | | | live, untested | ### Workable (`workable:starling-bank`, 48 roles) @@ -94,10 +94,10 @@ Requests go through `finder=findReqs;siteNumber=CX_1,=,...`. |---|---|---|---|---|---| | keyword | `query` in the POST body of `/api/v3/accounts//jobs`; `{"query": "engineer"}` answered 42 of 48 | | | | live | | keyword scope | title and text, judged from the 6 of 10 hits that have it in the title: not determined | | | | untested | -| category | `department`: the site sends a list of names taken from each department's `filter` array; my body `["Engineering"]` was answered 400 (the request with `location` too), which of the two keys was refused is not known | | | | live (rejected), front end | +| category | `department`: the site sends a list of names taken from each department's `filter` array; the survey's body `["Engineering"]` was answered 400 (the request with `location` too), which of the two keys was refused is not known | | | | live (rejected), front end | | level | none: no filter key | | | | front end | | employment | `worktype`, and `workplace` (`hybrid`, `on_site`, `remote`) | | | | front end | -| place | `location`: a list of `{country, region, city, countryCode}` objects, the shape of a role's `locations`; my body left out `countryCode`, which may have caused the 400 | | | | front end | +| place | `location`: a list of `{country, region, city, countryCode}` objects, the shape of a role's `locations`; the survey's body left out `countryCode`, which may have caused the 400 | | | | front end | ### Teamtailor (`teamtailor:careers.shine.co`, 73 roles) @@ -159,7 +159,7 @@ For agent 2 this costs nothing: its `any` group has DK and SE beside the towns, **Which hosts could take a town instead.** - Could, by what was seen: Eightfold (`location=`, its facet values are town strings; untested), Workable (`location` objects with `city`; untested body), Lever (`location=Stockholm`, live: exact text, matches any of a role's places), Adzuna (`where`, `location0..7`), Jobindex (`geoareaid`), Platsbanken (`municipality`). -- Could, with facets: Workday on tenants that have a city facet (LEGO's is countries only), SuccessFactors (`locationsearch=`, untested), Phenom (`location` and `locationData` in the body, untested), Jibe (a city facet is listed; the parameter is not known). +- Could, with facets: Workday if a tenant has a city facet (none seen: LEGO's is countries only, and `locationMainGroup` holds a country facet), SuccessFactors (`locationsearch=`, untested), Phenom (`location` and `locationData` in the body, untested), Jibe (a city facet is listed; the parameter is not known). - Cannot: SmartRecruiters has `city=` and `region=` in its documentation but it is untested; Oracle lists ten countries and sites only; Teamtailor takes ids. - Only the search providers do so today (`Filters(place="one")` on Adzuna, Jobindex and Platsbanken). @@ -169,9 +169,11 @@ For agent 2 this costs nothing: its `any` group has DK and SE beside the towns, 2. Town strings are the host's own, unlike ISO codes: each host needs a name-to-string table or a facet lookup, and a town the host spells differently returns nothing and, on the closing guard, wrongly closes roles. 3. Hosts that state their places per role (all the big ones) leave the exact match to the gates and the gazetteer, which is already right. -So: F2 changes `reach.py` to carry `places` beside `countries` for a group that has towns and no country, and passes them only to readers that declare `place` (the three providers now; Eightfold and Lever if a later run shows the strings work). Everything else keeps the country. +So: the plan was to carry `places` beside `countries` in the reach for a group that has towns and no country, and to pass them only to readers that declare `place`. That was not built. `Reach` (`app/jobs/reach.py`) carries countries and remote, a town in a gate is fetched as its country (`decisions.md`, Fetch terms), and the three search providers take their `place` from the saved params (`PARAMS`), never from a reach. Eightfold and Lever wait for a run that shows the town strings work. -## 3. Recommendation +## 3. What was recommended, and what landed + +Landed: `query` on SmartRecruiters, SuccessFactors, Workday, Phenom, Eightfold and Oracle (`Filters(query="one")`). Not built: the rows below marked "no" or "later", and the rows for Workable, Teamtailor and Jibe, which declare no `query` yet. ### Declarations per host @@ -183,17 +185,17 @@ So: F2 changes `reach.py` to carry `places` beside `countries` for a group that | Phenom | yes: `keywords` | later: `selected_fields.category` needs the value list | no: `positionLevel` is empty | no | | Workday | yes: `searchText` | later: `jobFamily` ids from the existing `facets` call | no | no | | Oracle | yes: `keyword` | later: `selectedCategoriesFacet` ids from `categoriesFacet` | no | no | -| Workable | yes: `query` | no: the body is not settled (400) | no | no | -| Teamtailor | yes, after one baseline request confirms the feed filters | no | no | no | -| Jibe | yes: `keywords` | later: `categories` | no | no | +| Workable | not built: `query` answered in the survey | no: the body is not settled (400) | no | no | +| Teamtailor | not built: needs a baseline request that confirms the feed filters | no | no | no | +| Jibe | not built: `keywords` | later: `categories` | no | no | | Lever | no: no keyword parameter; boards are small and read whole | no | no | later, as above | | Jobindex, Platsbanken, Adzuna | already `query` and `place`; `subid`, `occupation-field` and `category` are available for `category` | | | | -`level` is not worth declaring on any host: only SuccessFactors and Jibe have a facet for it, and on the tenants seen it is a tenant label or empty. Seniority stays a prep matter (title rules, host word). +`level` is not worth declaring on any host: only SuccessFactors and Jibe have a facet for it, and on the tenants seen it is a tenant label or empty (Lever documents `level=` and SmartRecruiters states `experienceLevel` on each role; neither is filtered on). Seniority stays a prep matter (title rules, host word). -### What F2 should build first +### What F2 built, and why in this order -The plan assumes terms narrow big boards. The live DB says how much: +The table shows how much terms can narrow big boards, from the live database of 2026-09-30: | Board | Host | Open | In Europe | In DK or SE (today's reach) | Roles with a term in the title, Europe | |---|---|---|---|---|---| @@ -211,29 +213,29 @@ The plan assumes terms narrow big boards. The live DB says how much: | Ericsson | Eightfold | 618 | 210 | 149 | 64 | | Nokia | Oracle | 554 | 87 (54 with none) | 0 | 24 | -"Term in the title" is a count of the words head, director, VP, chief, CTO, CDO, data, AI, machine learning, forward deployed, solutions engineer or architect, professional services, research, innovation, principal, lead and manager in the title. It is a proxy for `fetch_terms`, and a lower bound on what a text filter returns: every host's keyword matched text, not only titles (Ericsson: `software` matched a thesis title without it; Nokia: `engineer` matched 468 of 554; Bosch: 1,713 of 4,830). Expect a keyword read to return several times these counts, and a broad term like `engineer` to cut little. +"Term in the title" is a count of the words head, director, VP, chief, CTO, CDO, data, AI, machine learning, forward deployed, solutions engineer or architect, professional services, research, innovation, principal, lead and manager in the title. It is a proxy for `fetch_terms`, and a lower bound on what a text filter returns: where the scope could be told, the keyword matched text and not only titles (SmartRecruiters, Eightfold and Oracle by the examples here; on SuccessFactors, Workday, Workable and Jibe it is not determined) (Ericsson: `software` matched a thesis title without it; Nokia: `engineer` matched 468 of 554; Bosch: 1,713 of 4,830). Expect a keyword read to return several times these counts, and a broad term like `engineer` to cut little. Findings: -1. **Narrow reach needs no terms.** At DK and SE every big board is already at most 149 roles (Ericsson), and Bosch is two requests. Terms save requests only on the wide reach: the All roles tag, and the favourite reads the plan drops. +1. **Narrow reach needs no terms.** At DK and SE every big board is already at most 149 roles (Ericsson), and Bosch is two requests. Terms save requests only on the wide reach, which is the All countries tag; a company set to All roles takes no terms, and a favourite no longer widens the fetch (`decisions.md`). 2. **The wide reach is where terms pay.** SmartRecruiters reads Europe (33 countries) as the whole board, because `MAX_SERIES` is 8 for a `one` host: Bosch is 49 requests of 100 for 1,564 European roles. One `q` request per term (about 35% of the board for `engineer`, far less for `director` or `data`) replaces it. -3. **Order by the size of the whole read that terms replace**, then by how sure the parameter is: +3. **The order followed the size of the whole read that terms replace**, then how sure the parameter was: 1. SmartRecruiters `q`: Bosch, Delivery Hero, Wise and Coolblue, 6,700 roles in the live DB, one live-verified parameter, AND with country. 2. SuccessFactors `q`: SAP, Scania, Vestas and Novo Nordisk, 2,650 roles; verified. The reader already reads a country a request, so a term multiplies the series. 3. Workday `searchText` (Zeiss 848, LEGO 455), Phenom `keywords` (Philips 868), Eightfold `query` (Ericsson 618) and Oracle `keyword` (Nokia 554): each verified once, each a small change to the request body or URL. -4. **Category next, and only for Workday, Oracle, Jibe and Eightfold.** They state their own category ids in a response the reader already reads or can read (`facets`, `categoriesFacet`, `filter.categories`, `filterDef`), and the union across values is verified on Workday and Oracle. But an agent's term (`engineer`) is not a category name, so it needs a mapping from term to category per tenant that nobody has: not before terms have run on real boards. -5. **Level: never at the source.** **Place: the search providers now, Eightfold and Lever if a test proves a town string; the rest stay on country.** +4. **Category comes next, and only for Workday, Oracle, Jibe and Eightfold** (Phenom's needs its value list first). They state their own category ids in a response the reader already reads or can read (`facets`, `categoriesFacet`, `filter.categories`, `filterDef`), and the union across values is verified on Workday and Oracle. But an agent's term (`engineer`) is not a category name, so it needs a mapping from term to category per tenant that nobody has: not before terms have run on real boards. +5. **Level is not filtered at the source.** Place is filtered by the search providers; Eightfold and Lever wait for a test that proves a town string, and the rest stay on country. -### Guards F2 must keep +### Guards the fetch terms keep -- A term filter needs the closing guards to hold: a keyword read is not a whole board, so `ats:size` must not be overwritten by it, and roles outside it must not be closed as gone. -- Unknown-value behaviour differs: Lever returns nothing, Oracle returns everything, SuccessFactors returned something unrelated, Workable answers 400. The runner must treat a facet value as known only when the host's own facet list stated it, as `series` does for ids. +- A term filter needs the closing guards to hold: a keyword read is not a whole board, so it does not write `ats:size` (a pull no longer rewrites a size at all) and roles outside it are not closed as gone (`narrowed` in `plugins/readers/_runner.py`, `close_boards` in `app/jobs/pull.py`). +- Unknown-value behaviour differs: Lever returns nothing, Oracle returns everything, SuccessFactors returned something unrelated, Workable answered 400 to a body whose refused key is not known. The runner treats a facet value as known only when the host's own facet list stated it, as `series` does for ids. - Keywords are text matches everywhere except Adzuna's `title_only`; the agent's own scoring still decides relevance. -### Open, and cheap to settle in F2's first hour +### Open, and cheap to settle with one request each - SmartRecruiters: does `q="head of data"` mean all words or any, and are `department`, `function`, `experienceLevel` accepted (one request each)? - Teamtailor: a baseline request to confirm the feed's `query` filter. -- Workable: which key of my body was refused (`department` or `location`). +- Workable: which key of the survey's body was refused (`department` or `location`). - Eightfold: a `location` with a town string, and repeated `filter_function` values. - Adzuna: everything, once the key exists.