Oracle Fusion Cloud HCM Tool

Reads HR data from Oracle Fusion Cloud HCM over its REST API.

Tool ID

fusion-hcm

Fusion is not PeopleSoft

Oracle owns both, and conflating them is the most common mistake in this space.

Blog posts and vendors claiming "Oracle HCM has REST APIs" are describing Fusion. Those endpoints do not exist in PeopleSoft — everything Oracle ships pre-built there is asynchronous publish/subscribe, which is why the PeopleSoft connector reads the database directly.

Do not point this connector at a PeopleSoft install.

Three traps worth knowing

1. Departments are served by /organizations. Oracle's documentation page is titled "Departments REST Endpoints", but every operation on it is GET .../organizations. There is no /departments resource. This is the single most likely 404.

2. limit caps at 499, silently. Oracle: "If you specify a value more than 499, only the first 499 records are returned and the hasMore parameter is false." An over-large page size therefore truncates and tells you there is no more data. Page with limit ≤ 499 and follow hasMore; never trust one large request. Default page size is 25, so a caller who sets nothing reads 25 rows as the whole population.

3. Assignments are a grandchild. The path is /workers/{workerId}/child/workRelationships/{periodOfServiceId}/child/assignments — you need both ids. The /workers/{id}/child/assignments shape belongs to the deprecated emps resource.

Which people resource

Credential Required

Yes — a fusion-hcm credential. HTTP Basic over TLS with an integration user; the login and password come from the vault and never enter a task definition or the assistant's context.

Oracle's Multi Token Over SSL policy documents Basic, SAML 2.0 bearer and JWT. Basic is not deprecated and is Oracle's own example throughout the REST reference. OAuth2 via OCI IAM exists at the platform level, but its token endpoint is not documented in the HCM REST book, so it is not implemented here rather than guessed at.

Authorization is RBAC: the integration user needs the function/aggregate privileges for the resource and an HCM data role granting the person population. A correctly authenticated user with the wrong data role returns an empty collection, not an error.

Operations

Inputs

apiVersion is an input, not a constant: 11.13.18.05 has been stable since R13, but it is a version segment and it moved once already (R12 used 11.12.1.0 with per-pillar context roots).

Query parameters

Passed as a JSON object string, e.g. {"limit": 499, "totalResults": true, "effectiveDate": "2020-01-01"}

Filter examples from Oracle: PersonNumber=1000, PersonNumber between 1000 and 1100, DateOfBirth > '1960-01-01', names.FirstName like '%Ki%', upper(FirstName) = 'KIM'.

Run describe_workers before writing a filter. Only attributes marked "queryable": true may appear in q; anything else returns 400.

Effective dating

A query parameter, not a header: {"effectiveDate": "2020-01-01"} returns the rows in force on that date. There is no separate history endpoint — the same call retrieves past or future rows depending on the date. (The Effective-Of header governs writes, which this read-only connector does not perform.)

REST-Framework-Version

Sent as 4 on every request. Versions differ in backward-incompatible ways and the default when the header is absent is 1 — under which the q syntax above is interpreted differently rather than rejected. Version 4 also returns structured errors (code, path, details).

Bulk extracts

Oracle explicitly steers away from REST for full-population work, on the resource pages themselves: "Use HCM Data Loader for bulk load operations and HCM Extracts for extract operations" and "Do not use REST APIs for detecting data changes; use Atom feeds instead."

A whole-workforce sync over workers with deep expand at 499/page is fighting the product. Use this connector for targeted reads, lookups and moderate extracts; use HCM Extracts for the full population and Atom feeds for change detection.

Errors and backoff

Oracle documents no rate limit and no 429 for this API. The pressure signals are 503 Service Unavailable (server overload) and 504 — back off on those. 413 means a bulk request exceeded the allowed operation count.

Build

./gradlew :intouchtools:tools:fusion-hcm:toolJar

Produces build/libs/fusion-hcm-1.0.0.jar, matching connector.json's jars[0].

Licensing

licenseRequired() returns true, matching the other ERP/HCM connectors.

Status

Untested against a live Fusion pod. The endpoint shapes, parameters and limits above are taken from Oracle's REST API reference for Oracle Fusion Cloud HCM (doc G29489-05), but nothing here has been exercised against a real tenant. Validate before relying on it.

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

• complete
• operation
• result
• status
• warning

Fields not documented above

Generated from this tool's own schema and published outputs on 2026-09-03. A field the README omits is discoverable only by reading the source, and a published key nothing documents is a capability nobody can reference.