Files
jobboard/plugins/readers/oracle.py
T
WolfandClaude Opus 5.5 c497fe965d Keep a description's headings, bullets and paragraphs, and draw them in the reader
The readers flattened a posting's HTML into one line with strip_html, so
sections and bullets ran together. _shared.html_text gives a line per
paragraph, '• ' before a list item and '## ' before a heading; every
reader's description goes through it, sections read per role get their
own headings, and the reader pane draws the lines as h3, ul and p.
Excerpts leave the marks out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 21:40:12 +02:00

247 lines
11 KiB
Python

"""Oracle Recruiting Cloud: `oracle:<host>/<siteNumber>`, for example
`oracle:fa-ewto-saasfaprod1.fa.ocs.oraclecloud.com/CX_1001`. A paged REST
listing that states its total, and a per-role resource for the description.
The host is the tenant's Fusion pod (`fa-...ocs.oraclecloud.com`), not the
company's own domain: Nokia's `jobs.nokia.com` only redirects to it. The site
number is `CX_1001` or `CX_1` on the tenants read so far, and the site's own
name (`SinchCareer`) is taken in its place. Written from live boards on
2026-09-29 (Milestone Systems, Nokia, Danske Bank, Sinch); jobhunt-hq did not
read Oracle.
Countries are filtered on the server by `selectedLocationsFacet`, the pod's
geography ids (`Filters(country="ids")`), which `facets` reads off
`locationsFacet`; several ids go in one request, joined with `;`, the way the
site's own search sends a multiple choice. That list holds only the pod's ten
biggest countries (fa-evmr's, 2026-09-30), so when it is full a country
missing from it may still have roles: `facets` then maps every other country
to `*`, and a series asking for one is read without a country filter. An id
the pod does not know answers the whole board (review). Remote is
`selectedWorkplaceTypesFacet=ORA_REMOTE` (`remote="one"`); two facets are an
intersection (Finland and remote answered 0 on 2026-09-30), which is why the
runner asks for remote in a series of its own.
A fetch term goes into the finder as `keyword=engineer`, one a request
(`Filters(query="one")`); it matches the text (survey, 2026-09-30: 468 of
Nokia's 554).
"""
from __future__ import annotations
import html
import json
import re
from collections.abc import Callable
from typing import Any
from urllib.parse import quote
from desk.sources import strip_html
from ._contract import Ask, Fields, Filters, Place, Reads
from ._countries import NAMES, code_of
from ._shared import Get, HEADING, Page, Row, add_place, html_text, only, parse_dt
NAME = "oracle"
LABEL = "Oracle Recruiting Cloud"
KEEP_CASE = True
PATTERNS = (
# The candidate site or one role's page: `<pod>/hcmUI/CandidateExperience/en/sites/CX_1/jobs`.
r"https?://([a-z0-9-]+(?:\.[a-z0-9-]+)*\.oraclecloud\.(?:com|eu))"
r"/hcmUI/CandidateExperience/[A-Za-z_-]+/sites/([A-Za-z0-9_-]+)",
# The REST call a company's own page makes, which names the site as `siteNumber=`.
r"https?://([a-z0-9-]+(?:\.[a-z0-9-]+)*\.oraclecloud\.(?:com|eu))"
r"/hcmRestApi/resources/[a-z0-9.]+/recruitingCEJobRequisitions[^\"'\s]*?siteNumber=([A-Za-z0-9_-]+)",
# No slug: another page of a tenant's Fusion UI (its sign-in, say), which names
# the host but no candidate site.
r"oraclecloud\.(?:com|eu)/hcmUI(?!/CandidateExperience/[A-Za-z_-]+/sites/)",
)
READS = Reads(
scope="board", listing="paged", page_size=200, text="detail", teaser=True,
complete="stated", places="many", filters=Filters(country="ids", remote="one", query="one"),
fields=Fields(posted="trusted", remote="stated"),
robots=("read: /hcmRestApi/resources/latest/recruitingCEJobRequisitions and "
"recruitingCEJobRequisitionDetails on the tenant's host, whose /robots.txt answers "
"404, so nothing is disallowed (four seed tenants, checked 2026-09-30)"),
)
#: The page size asked for. 200 was answered in full by Nokia (600 roles in
#: three calls of about 360 KB, 2026-09-29); the cursor advances by what a page
#: returned, so a tenant that caps `limit` lower would not skip a role.
PAGE_SIZE = 200
#: A pod: `fa-ewto-saasfaprod1.fa.ocs.oraclecloud.com`. Oracle's regions also
#: use `.eu` (Danske Bank's `ejqi.fa.ocs.oraclecloud.eu`). A host name has no
#: case, so a slug written with capitals is allowed as its lowercase.
_HOST = r"[a-z0-9-]+(?:\.[a-z0-9-]+)*\.oraclecloud\.(?:com|eu)"
_SLUG = re.compile(rf"({_HOST})/([A-Za-z0-9_-]+)", re.IGNORECASE)
def _parts(slug: str) -> tuple[str, str]:
"""`(host, site number)` of a slug that passed `slug_ok`."""
host, _, site = slug.partition("/")
return host.lower(), site
def slug_ok(slug: str) -> bool:
return bool(_SLUG.fullmatch(slug))
def allowed(slug: str) -> Callable[[str], bool]:
return only(_parts(slug)[0])
def _base(slug: str) -> str:
host, site = _parts(slug)
return f"https://{host}/hcmUI/CandidateExperience/en/sites/{site}"
def careers_url(slug: str) -> str:
return f"{_base(slug)}/jobs"
def _api(slug: str) -> str:
return f"https://{_parts(slug)[0]}/hcmRestApi/resources/latest"
def page(get: Get, slug: str, cursor: Any, ask: Ask = Ask()) -> Page:
"""One page of `recruitingCEJobRequisitions`. The answer's outer `count`,
`hasMore` and `limit` describe the one search wrapper in `items`, so the
total (`TotalJobsCount`) and the roles (`requisitionList`) are read from
`items[0]`. Without the `expand` only the facets come back; asking for
`requisitionList.secondaryLocations` gives the roles and each one's other
locations, which the plain `requisitionList` leaves out. Past the last role
the list is empty."""
offset = int(cursor or 0)
site = _parts(slug)[1]
data = json.loads(get(
f"{_api(slug)}/recruitingCEJobRequisitions?onlyData=true"
f"&expand=requisitionList.secondaryLocations"
f"&finder=findReqs;siteNumber={site},{_selected(ask)}limit={PAGE_SIZE},offset={offset}"))
search = (data.get("items") or [{}])[0]
roles = search.get("requisitionList") or []
# `_paged` counts `id`, which Oracle spells `Id`.
results = [{"id": str(role.get("Id") or "")} for role in roles]
return search, results, search.get("TotalJobsCount"), offset + len(roles) if roles else None
#: How many countries `locationsFacet` lists at most; a list this long may
#: leave some out.
FACET_LIMIT = 10
def _selected(ask: Ask) -> str:
"""The finder's facet parameters for `ask`, each ending in a comma: the
keyword, the location ids (none when one is `*`, a country the pod did
not list) and remote. The keyword is escaped whole, so a comma or a
semicolon in it cannot start another finder parameter."""
out = f"keyword={quote(ask.query, safe='')}," if ask.query else ""
ids = [i for i in ask.countries if re.fullmatch(r"\d+", i)]
if ids and "*" not in ask.countries:
out += f"selectedLocationsFacet={'%3B'.join(ids)},"
if ask.remote:
out += "selectedWorkplaceTypesFacet=ORA_REMOTE,"
return out
def facets(get: Get, slug: str) -> dict[str, dict[str, str]]:
"""The pod's geography id of each country `locationsFacet` names, read
with the facets and no roles. When the list is `FACET_LIMIT` long, every
country it leaves out maps to `*`: its roles may be there, and a read
for it goes unfiltered."""
site = _parts(slug)[1]
data = json.loads(get(
f"{_api(slug)}/recruitingCEJobRequisitions?onlyData=true"
f"&finder=findReqs;siteNumber={site},facetsList=LOCATIONS,limit=1,offset=0"))
listed = (data.get("items") or [{}])[0].get("locationsFacet") or []
country = {code: str(entry["Id"]) for entry in listed
if isinstance(entry, dict) and entry.get("Id")
and (code := code_of(str(entry.get("Name") or "")))}
if len(listed) >= FACET_LIMIT:
country = dict.fromkeys(NAMES, "*") | country
return {"country": country}
def parse(body: bytes, slug: str) -> list[Row]:
return rows((json.loads(body).get("items") or [{}])[0], slug)
def _text(value: Any) -> str:
return value.strip() if isinstance(value, str) else ""
def _plain(value: Any) -> str:
"""Plain text from a field of HTML, entities (`&amp;`, `&nbsp;`) included."""
return html.unescape(strip_html(_text(value))).replace("\xa0", " ").strip()
def rows(search: dict[str, Any], slug: str) -> list[Row]:
"""The roles of one page's search wrapper. The list carries the title, the
id, `PostedDate` (a date), `PrimaryLocation` ("Copenhagen, Denmark"; a
country alone where the role names no city), `secondaryLocations`,
`WorkplaceTypeCode` and `ShortDescriptionStr`, one paragraph that Nokia
and Milestone fill for most roles. The department fields (`JobFamily`,
`Department`, `Organization`) were null on every role of all four boards
read, and are taken when a tenant fills them. The full description is in
the role's own resource, see `detail`. No pay is stated."""
out = []
for role in search.get("requisitionList") or []:
role_id = str(role.get("Id") or "").strip()
title = _text(role.get("Title"))
# The id goes into a URL, and a listing is external content.
if not title or not re.fullmatch(r"[A-Za-z0-9_-]+", role_id):
continue
remote = _text(role.get("WorkplaceTypeCode")) or None
at_office = (remote or "").lower() in ("ora_hybrid", "ora_on_site")
places: list[Place] = []
secondary = [s for s in role.get("secondaryLocations") or [] if isinstance(s, dict)]
for name in (_text(role.get("PrimaryLocation")),
*(_text(s.get("Name")) for s in secondary)):
add_place(places, {"text": name, "remote": (
True if (remote or "").lower() == "ora_remote" else False if at_office else None)})
out.append({
"source_id": role_id,
"title": title,
"places": places,
"location": "; ".join(p["text"] for p in places),
"url": f"{_base(slug)}/job/{role_id}",
"posted": parse_dt(role.get("PostedDate")),
"department": (_text(role.get("JobFamily")) or _text(role.get("JobFunction"))
or _text(role.get("Department")) or _text(role.get("Organization"))),
"description": "",
"teaser": _plain(role.get("ShortDescriptionStr")),
"remote": remote,
"salary_text": "", # the resource states no pay
})
return out
def detail(get: Get, slug: str, row: Row) -> dict[str, Any]:
"""The role's own resource (`recruitingCEJobRequisitionDetails`, found by
`Id` and site). Only here is the full text: `ExternalDescriptionStr`, with
the responsibilities and qualifications strings after it where a tenant
fills them (Milestone leaves them empty), all HTML. `ExternalPostedStartDate`
is a timestamp where the listing has a date. A role that is no longer open
answers 200 with no items, and has nothing to read."""
site = _parts(slug)[1]
role_id = quote(str(row["source_id"]), safe="")
data = json.loads(get(
f"{_api(slug)}/recruitingCEJobRequisitionDetails?expand=all&onlyData=true"
f"&finder=ById;Id=%22{role_id}%22,siteNumber={site}"))
items = data.get("items") or []
if not items:
return {}
role = items[0]
parts = []
for key, heading in (("ExternalDescriptionStr", ""),
("ExternalResponsibilitiesStr", "Responsibilities"),
("ExternalQualificationsStr", "Qualifications")):
if part := html_text(_text(role.get(key))):
parts += [HEADING + heading, part] if heading else [part]
text = "\n".join(parts)
out: dict[str, Any] = {}
if text:
out["description"] = text
if posted := parse_dt(role.get("ExternalPostedStartDate")):
out["posted"] = posted
return out