Oracle HCM

Authentication & Authorization

Credentials

• Oracle HCM uses basic authentication with “username” and “password” to allow access to the API.

• You can find the REST username and password in the welcome email sent to your Oracle Cloud service administrator (see the DataGrail Help Docs).

• Publicly exposing your API credentials can allow unauthorized access to the Oracle HCM API endpoints, and your Oracle HCM data by a third party. DataGrail stores your API credentials encrypted and protected.

Permissions

Authorization identifies which users can access the REST APIs. To access REST APIs, users must have the required roles with appropriate security privileges.

Oracle HCM Cloud REST APIs are secured with function and aggregate security privileges, which are delivered through predefined job roles. These job roles control access to the REST resources.

You can also define your own custom roles and add them to appropriate job roles as per the standard security guidelines. You must also include any job role that you'll use to access REST APIs in an Oracle HCM Cloud data role to provide the necessary data access. Depending on the roles assigned and their level of access, users can access the REST resources to view or manage data.

You must have the necessary security roles and privileges to use the GET method on your parent and child resources.

Base URL

The request API URL consists of the server name and the resource path:

• https://<server>/<resource-path>

The <server> is the REST Server URL that can be found in the welcome email sent to your Oracle Cloud service administrator (see the DataGrail Help Docs), e.g. https://servername.fa.us2.oraclecloud.com

The <resource-path> is the relative path or endpoint to the resource you're working with, e.g. /hcmRestApi/resources/11.13.18.05/selfDetails

The base API URL for the current DataGrail integration is:

• https://{servername}.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05

Endpoints Utilized

DataGrail uses the following endpoint to validate that credentials are good based on a successful response:

• GET /selfDetails

Version

DataGrail integration currently supports Oracle HCM API version 11.13.18.05.

Limits

• DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.

• DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

Access

For an access request, DataGrail will take the following actions:

• Search employees by work email and work phone number using Subject Identifiers.

• For each Employee, DataGrail fetches child resources:

  • Assignments

  • Person Descriptive Flexfields

  • Person Extra Information Extensible FlexFields

  • Photos

  • Roles

  • Visas

• Search HCM Contacts by email and phone number using Subject Identifiers.

• For each HCM Contact, DataGrail fetches child resources:

  • Addresses

  • Citizenships

  • Contact Descriptive Flexfields

  • Driver Licenses

  • Emails

  • Names

  • National Identifiers

  • Other Communication Accounts

  • Passports

  • Phones

• Search Workers by email and phone number using Subject Identifiers.

• For each Worker, DataGrail fetches child resources:

  • Addresses

  • Citizenships

  • Driver Licenses

  • Emails

  • Names

  • External Identifiers

  • Messages

  • National Identifiers

  • Phones

• Search Public Workers by work email and phone number using Subject Identifiers.

• For each Public Worker, DataGrail fetches child resources:

  • Messages

  • Phones

  • Other Communication Accounts

• Search Recruiting Candidate Details by candidate email using Subject Identifiers.

• Search Locations V2 by email using Subject Identifiers.

• For each Location, DataGrail fetches child resources:

  • Addresses

  • Attachments

  • Locations Descriptive Flexfields

• Search Incident Kiosks by incident reporter email using Subject Identifiers.

• Search Learner Learning Records by assigned to/assigner person email using Subject Identifiers.

Endpoints Utilized

• GET /emps

• GET /emps/{empsUniqID}/child/assignments

• GET /emps/{empsUniqID}/child/personDFF

• GET /emps/{empsUniqID}/child/personExtraInformation

• GET /emps/{empsUniqID}/child/photo

• GET /emps/{empsUniqID}/child/roles

• GET /emps/{empsUniqID}/child/visas

• GET /hcmContacts

• GET /hcmContacts/{hcmContactsUniqID}/child/addresses

• GET /hcmContacts/{hcmContactsUniqID}/child/citizenships

• GET /hcmContacts/{hcmContactsUniqID}/child/contactsDFF

• GET /hcmContacts/{hcmContactsUniqID}/child/driverLicenses

• GET /hcmContacts/{hcmContactsUniqID}/child/emails

• GET /hcmContacts/{hcmContactsUniqID}/child/names

• GET /hcmContacts/{hcmContactsUniqID}/child/nationalIdentifiers

• GET /hcmContacts/{hcmContactsUniqID}/child/otherCommunicationAccounts

• GET /hcmContacts/{hcmContactsUniqID}/child/passports

• GET /hcmContacts/{hcmContactsUniqID}/child/phones

• GET /workers

• GET /workers/{workersUniqID}/child/addresses

• GET /workers/{workersUniqID}/child/citizenships

• GET /workers/{workersUniqID}/child/driverLicenses

• GET /workers/{workersUniqID}/child/emails

• GET /workers/{workersUniqID}/child/names

• GET /workers/{workersUniqID}/child/externalIdentifiers

• GET /workers/{workersUniqID}/child/messages

• GET /workers/{workersUniqID}/child/nationalIdentifiers

• GET /workers/{workersUniqID}/child/phones

• GET /publicWorkers

• GET /publicWorkers/{PersonId}/child/messages

• GET /publicWorkers/{PersonId}/child/phones

• GET /publicWorkers/{PersonId}/child/otherCommunicationAccounts

• GET /bcCandidateDetails

• GET /locationsV2

• GET /locationsV2/{locationsV2UniqID}/child/addresses

• GET /locationsV2/{locationsV2UniqID}/child/attachments

• GET /locationsV2/{locationsV2UniqID}/child/locationsDFF

• GET /incidentKiosks

• GET /learnerLearningRecords

Deletion

DataGrail supports the Direct Contact Deletion workflow for Oracle HCM.