Appearance

Connect Oracle Fusion Cloud HCM ​

Connect Oracle Fusion Cloud HCM so the people, teams, positions and pay in Flowstate follow what HR records in Oracle. Hires, leavers, assignment changes and pay changes reach the forecast without anyone re-keying them.

Setting it up takes your Oracle HCM administrator, your integration team and a Flowstate admin. First decide whether Oracle is your source of truth. See Get your people data into Flowstate.

How it connects ​

Oracle doesn't push changes to other systems. It publishes them as change feeds (Atom feeds) that are read on a schedule. Oracle advises using the feeds to spot changes, and its REST API to read the records. Your integration platform can do both and update Flowstate through its REST API. If you'd rather not run one, a Flowstate custom integration can read Oracle's REST API on a schedule instead. Use one route for Oracle, not both.

RouteHow it worksBest for
Event-driven (recommended)Your integration platform, such as Oracle Integration, reads Oracle's change feeds for new hires, assignment and pay changes, and terminations. It reads each changed worker through Oracle's REST API and updates Flowstate through the REST API.Most organisations, and any tenant that only accepts calls from listed IP addresses
Scheduled syncA Flowstate custom integration reads workers, positions and departments from Oracle's REST API every 15 or 30 minutes, every hour, every 6 or 12 hours, or daily. It brings everyone up to date on each run.Smaller workforces that fit within a custom integration's run limits, in tenants that accept calls from any IP address

Why event-driven is recommended: Oracle's change feeds are XML, which a custom integration can't read. Without them, a scheduled sync has to re-read everyone on every run. A worker's details are also spread across several linked records (work relationships, assignments and salaries), so a large workforce can outgrow a single run. An integration platform reads only what changed.

If your tenant only allows API calls from listed IP addresses, use the event-driven route through your integration platform.

What you need from Oracle ​

  • An integration user with the Human Capital Management Integration Specialist job role, which includes access to the workers REST API. Oracle also has read-only duty roles for workers.
  • A data role with a security profile that covers the people you sync. Without one, the user can sign in but sees no one.
  • A way to sign in, either of:
    • basic authentication for the integration user; or
    • OAuth through your OCI IAM identity domain: a Confidential Application with the Client Credentials grant. The client ID must also exist as a user in Fusion, with the same roles.
  • Your Oracle address, in the form https://<servername>.fa.<region>.oraclecloud.com.
  • For the event-driven route: access to the Atom feeds for the integration user. Oracle grants feed access to the Integration Specialist role as delivered; check it in your tenant.

Set it up ​

Your Flowstate contact provides the integration logic for Oracle Fusion Cloud HCM, and works through it with your integration team. There's no one-click connection.

In Oracle ​

  1. In the Security Console, create the integration user.
  2. Give it the Human Capital Management Integration Specialist job role, through a data role whose security profile covers the people you sync.
  3. For OAuth: in your OCI IAM identity domain, create a Confidential Application with the Client Credentials grant and the scope for Fusion REST APIs. Make sure a Fusion user exists for its client ID, with the same roles.
  4. For the event-driven route: give your integration team the user's sign-in details, so the platform can read the employee change feeds and the REST API.
  5. For the scheduled sync: keep the sign-in details ready to store in Flowstate.

Event-driven: connect your integration platform ​

  1. In Flowstate, go to Settings → Users & Access → API Keys and select Create API Key. Name it after the sync, such as "Oracle HCM sync", and tick view, create and update for employees, contractors, vacancies and teams. See Create and manage API keys.
  2. Copy the key and give it to your integration team to store in the platform. Keys last 90 days at most, so put a reminder in to replace it.
  3. If people are already in Flowstate, your integration team gives each one their Oracle person ID first. See Adopt people who are already in Flowstate.
  4. Your integration team loads everyone once from Oracle's REST API, leavers included. The platform creates or updates each person in Flowstate by their person ID.
  5. They set the platform to read the change feeds on a schedule. For each change, the platform reads the worker from Oracle and sends the changes to Flowstate. How: Sync people from an HR system with the REST API.

Scheduled sync: set up a custom integration ​

  1. Ask your Flowstate contact to switch on custom integrations.
  2. Go to Settings → Integrations, select Browse catalog, open Custom Integrations and select Connect.
  3. Select Create Integration. Enter a Name and, in Source System Key, enter oracle-hcm. You can't change the key later.
  4. Under Credentials, select Add Credential for the Oracle sign-in details, using the key names your Flowstate contact gives you.
  5. If people are already in Flowstate, give each one their Oracle person ID first. See Adopt people who are already in Flowstate.
  6. Under Hooks, select Create Hook and choose Pull. Make one hook for each kind of record: teams first, then employees, contractors and vacancies. Paste in the code from your Flowstate contact and select Save Code.
  7. Select Test (Dry Run) and check Preview for anyone who'd be created twice.
  8. On the Settings tab, turn on Run on schedule, choose an Interval and select Save Code.
  9. Turn the hook on with Enable Hook.

More on each step: Manage a custom integration in Settings.

What syncs ​

In Oracle Fusion Cloud HCMIn FlowstateNotes
Person IDThe person's external IDOracle's own number for the person. The person number is the one people see, and can be set by your organisation.
Work relationship with worker type EmployeeEmployeeA person can have more than one work relationship. Use the primary one.
Work relationship with worker type Contingent WorkerContractorIf Oracle doesn't hold a contractor's rate, add it in Flowstate.
Position, or job requisitionVacancyPositions carry a hiring status and FTE. Requisitions carry the number of openings.
DepartmentTeam
Manager on the assignmentLine managerThe event-driven route sets a person's line manager. A scheduled sync can only set a team's manager, and only if that manager has a Flowstate login.
Job on the assignmentJob role
FTE on the assignmentFTE on the person's team allocationFlowstate records FTE, not hours.
Work relationship start date and termination dateStart date and end date
SalaryPay changesOracle holds the annual salary, currency and the date each salary starts.
Name and work emailName and work emailWork email links the person to their activity in your other tools.

A scheduled sync can't set a person's location, resource type, line manager or notice date. Set them in Flowstate, or use the event-driven route, which can.

How changes arrive ​

  • Event-driven. Changes arrive as often as your platform reads the feeds. Oracle can purge old feed entries, so your platform also re-reads everyone from time to time.
  • Scheduled sync. Changes arrive on the next run. Each run reads everyone again, so anything missed last time is picked up.
  • Effective dates. Oracle's assignments, positions and departments are date-effective, and an assignment can have more than one change on the same date. Your integration reads them as of a date. In Oracle Integration's HCM adapter, future-dated changes appear once they take effect, unless that setting is changed. Future pay changes show as Scheduled on the person's Compensation tab until their date.
  • Leavers. The termination date becomes the person's last day. They stay in Flowstate for past months.
  • Rehires. A rehire appears on Oracle's new hire feed. Under the same person ID it updates the same person. On the event-driven route, your platform clears their old end date through the REST API. On a scheduled sync, your technical team clears it through the REST API. See Undo a leaver.
  • Edits made in Flowstate. Anything Oracle sends is put back the next time that person is updated from Oracle. Details Oracle doesn't send stay as you set them.

Check it's working ​

  • Event-driven: make a test change to a worker's assignment in Oracle. After your platform's next read, the change shows on the People tab under Resourcing → People and teams. On Settings → Users & Access → API Keys, the key shows recent use.
  • Scheduled sync: open the hook's Execution History tab. The latest run shows Completed, with Records above zero and no failed records in its log.

If something's not right ​

Oracle returns no workers, or refuses every call. Check three things:

  • the integration user has the Human Capital Management Integration Specialist role;
  • its data role's security profile covers those people;
  • for OAuth, a Fusion user with the same roles exists for the client ID. Create one in the Security Console if not.

A scheduled sync is refused, though the sign-in details are right. Your tenant only allows API calls from listed IP addresses, and a scheduled sync doesn't call from a fixed address. Use the event-driven route, with your integration platform's addresses on the list.

A future-dated hire didn't arrive until their start date. Oracle Integration's HCM adapter shows future-dated changes once they take effect by default. Ask your integration team to change that setting.

Someone's job or team is wrong. They have more than one work relationship or assignment in Oracle. Ask your integration team to use the primary one.

For your technical team ​

Oracle APIs ​

  • REST base. https://<servername>.fa.<region>.oraclecloud.com/hcmRestApi/resources/11.13.18.05/<resource>.
  • Oracle's guidance. REST for transactional reads, HCM Extracts for bulk extracts, and Atom feeds, not REST, to detect changes.
  • Auth.
    • REST accepts basic authentication over SSL, a SAML 2.0 bearer token, or a JWT in the Authorization header.
    • OAuth: in the OCI IAM identity domain, create a Confidential Application. Grants are Client Credentials, Authorization Code, Resource Owner and JWT Assertion.
    • Token URL: https://<domainURL>/oauth2/v1/token. Scope for Fusion REST APIs: urn:opc:resource:fa:<instanceid>=<podname> urn:opc:resource:consumer::all. Tokens last 3,600 seconds.
    • With client credentials, the client ID must also exist as a Fusion user with roles.
  • Roles.
    • ORA_HRC_HUMAN_CAPITAL_MANAGEMENT_INTEGRATION_SPECIALIST carries the workers REST duty roles. Read-only variants include ORA_PER_REST_SERVICE_ACCESS_WORKER_EMPLOYMENT_RO.
    • Assign the role through a data role with a security profile.
  • Resources.
    • /workers has PersonId and PersonNumber, plus names and emails children.
    • /workers/{id}/child/workRelationships/{PeriodOfServiceId} has WorkerType (E employee, C contingent worker, P pending, N nonworker), StartDate, TerminationDate, LegalEmployerName and PrimaryFlag.
    • .../workRelationships/{id}/child/assignments has JobId, JobCode, PositionId, DepartmentId, DepartmentName, LocationId, AssignmentName, FullPartTime, NormalHours, Frequency, PrimaryAssignmentFlag, EffectiveStartDate, EffectiveEndDate, EffectiveSequence and EffectiveLatestChange. Its children include managers and workMeasures. Check the child field names in your tenant.
    • /salaries?finder=findByAssignmentId;AssignmentId=... has SalaryAmount, CurrencyCode, SalaryFrequencyCode, AnnualSalary, AnnualFullTimeSalary, FTEValue, DateFrom and DateTo. Other finders: findByAssignmentIdAndDate and findAssignmentSalaryHistory.
    • /organizations returns departments as of a date.
    • /positions has PositionId, PositionCode, Name, DepartmentId, JobId, FTE, HeadCount, HiringStatus (PROPOSED, FROZEN or APPROVED), ActiveStatus, EffectiveStartDate and EffectiveEndDate. It takes an effectiveDate parameter or an Effective-Of header.
    • /recruitingJobRequisitions has RequisitionId, RequisitionNumber, Title, StateName, PhaseName, DepartmentId, PositionId, NumberOfOpenings and HiringManagerId.
    • /publicWorkers (DisplayName, FirstName, LastName, WorkEmail) returns only assignments active today.
    • Direct reports: workers?finder=findReports;PersonId=....
  • Paging and filters. Every collection takes limit and offset, and returns count, hasMore, limit, offset and, optionally, totalResults. q filters and effectiveDate also work. The largest limit depends on your system's configuration.

Change feeds ​

  • URL. https://<host>/hcmRestApi/atomservlet/employee/<collection>, read with the same credentials as REST.

  • Collections.

    CollectionRaised by
    newhireHire, rehire, future-dated hire
    empassignmentAssignment, salary and manager changes
    empupdateName, email, phone, address and personal details
    terminationEmployee terminated
    workrelshipupdateHire date change, primary flag change and similar
    cancelworkrelshipNo-show, offer rejected, reverted transfer

  • Coverage. Feeds fire for employees, contingent workers and pending workers.

  • Paging. page-size (default 10) and page (default 1). Oracle Integration's adapter documentation also shows updated-min and updated-max; check them in your tenant.

  • Retention. Feed data can be purged periodically.

  • Push. Fusion HCM has no native push to an external endpoint. Oracle Integration's HCM adapter subscribes to Atom feeds in scheduled (polling) mode only. By default it shows future-dated entries once they take effect; that's configurable.

Flowstate ​

  • REST API. https://{tenant}.flowstate.inc/api/v1/org/{orgId} with Authorization: Bearer <key>.
    • There's no upsert. GET /employees/{personId}, then POST on 404 or PATCH on 200. Contractors, vacancies and teams work the same way.
    • PATCH /employees/:id sets managerId, geographyId, workTypeId and noticeDate, and { "endDate": null } clears a leaving date.
    • See the recipe and Permissions by endpoint.
  • Custom integration.
    • It calls a public HTTPS address and follows no redirects. Responses are capped at 10 MB. Only JSON is parsed, so Atom feeds arrive as a string.
    • Store basic authentication as the already-encoded value, or fetch and cache an OAuth client-credentials token in the hook.
    • It doesn't call from a fixed IP address.
    • Records match on external ID, never email.
    • See Sync people from an HR system and Limits.

Oracle documentation ​

Flowstate Documentation

Copyright 2026 Flowstate.