Files
jobboard/plugins/readers/oracle.py
T

258 lines
12 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; an answer without the wrapper raises (`_search`)."""
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 = _search(data)
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
def _search(data: Any) -> dict[str, Any]:
"""The search wrapper of a listing's answer, `items[0]`. Every answer has
one, past the last role too; one without (an error document sent with a
200) raises, so the read fails and closes nothing rather than reading as
an empty last page with no total, which is a complete read."""
items = data.get("items") if isinstance(data, dict) else None
if not isinstance(items, list) or not items or not isinstance(items[0], dict):
raise ValueError("Oracle's answer has no search wrapper in items")
return items[0]
#: 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(_search(json.loads(body)), 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