# Connecting SailPoint and Oracle HCM Cloud To connect SailPoint with Oracle HCM Cloud, perform the following tasks: ## Adding the Source in SailPoint To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs. > [!IMPORTANT] > > By default, the provisioning feature is **disabled**, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration. **To configure a new source:** 1. Sign in to SailPoint. 2. Go to **Admin \> Connections \> Sources**. 3. Select **Create New**. 4. Search for the connector by entering the name in the search box, and then select **Configure**. 5. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters. 6. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters. 7. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](). 8. Under **Connection Type**, select **Direct Connection** or **Flat File**. - **Direct Connection** - A direct connection fetches data from the **Virtual Appliance Cluster** you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](). - **Flat File** - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable. 9. If you selected **Direct Connection**, in **Virtual Appliance Cluster**, select the virtual appliance cluster that will be used as the application connector for the source. 10. (Optional) Select a governance group to grant its members [source]() or [role]() sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](). 11. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](). 12. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there. ## Base Configuration Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary. 1. Enter a unique name and description for the source. 2. In the **Source Owner** dropdown list, select the identity that owns this source. - To find a source owner, begin entering their name. 3. In the **Virtual Appliance Cluster** dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to [SailPoint Virtual Appliances](). 4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 5. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information. 6. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](). 7. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default. - **Enable Provisioning** - Set the toggle to **Enabled** to allow the source to create, update, and deactivate accounts in the connected source system. - **Disable Provisioning** - Set the toggle to **Disabled** to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source. 8. Select **Save**. ## Connection Settings Use the settings on this page to create a secure, direct connection to the source. These instructions also describe how to configure an export file for use by the Oracle HCM source. > [!NOTE] > > **Screenshot** > > [![Connection Settings]()]() 1. Go to **Connection Settings**. 2. In **File Transport**, SFTP mode will be used for accessing the file. 3. Enter the **Host** name where the file is located. 4. Enter the **Port** number that will be used to establish a connection. 5. Enter the **Username** to use during the file transfer. 6. For **Authentication Type**, select **Basic** or **Public Key**. **Basic** is the default. - **Basic** > **Screenshot** > > [![SFTP connection settings with Basic authentication]()]() Enter the **Password** for the user to use during the file transfer. - **Public Key** > **Screenshot** > > [![SFTP connection settings with Public Key authentication]()]() Provide the following details: - **SSH Private Key** - Enter the private key content to use to establish a connection. Paste the full private key in PEM or OpenSSH format. Do not enter a file path. - (Optional) **SSH Private Key Passphrase** - Enter the passphrase for the private key. > **Note** > > The public key that matches this private key must already be installed for the SFTP account. SSH public key authentication is separate from the PGP keys used to sign or decrypt worker files. 7. Provide the fully qualified paths to the Oracle HCM file exports in the FTP server. This enables the connector to differentiate between New Hires and Rehires. It also enables the source to populate data points which enable it to trigger the Joiner, Mover, and Leaver workflows more effectively. For example: ```text /home/sailpoint/File_Export/Details_Active_Encrypted.csv ``` 1. In the **Active Workers File Path** field, enter the fully qualified path of the Active Workers CSV extract file. The first line of the file must contain the column headers. 2. In the **Future Workers File Path** field, enter the fully qualified path of the Future Workers CSV extract file. The first line of the file must contain the column headers. 3. In the **Terminated Workers File Path** field, enter the fully qualified path of the Terminated Workers CSV extract file. The first line of the file must contain the column headers. 8. Select **Disable Integrity Check** to skip the integrity check while establishing the connection to the source. This needs to be done when a PGP public key is not available to sign the file. 9. Enter the **PGP Public Key** generated at the Oracle Fusion HCM system in the same format as shown below: ```text -----BEGIN PGP PUBLIC KEY BLOCK----- Version: BCPG v1.71 lEVFBsA1Iqt4Abh+8dWh3UtTcSuT8KIDYX+OpnVrWAUXMmnKT+JAI7Tk3vtYPiWe7E slg+8m7jXsFfZE5vaJOeFMbMfxC1jVNy+azO/EMg41kKW7pJHCTsGnChrteJ1ocv1iycl NAPf7E==ofag -----END PGP PUBLIC KEY BLOCK----- ``` 10. Enter the **PGP Private Key** generated at the Oracle Fusion HCM system in the same format as shown below: ```text -----BEGIN PGP PRIVATE KEY BLOCK----- Version: BCPG v1.71 lEVFBsA1Iqt4Abh+8dWh3UtTcSuT8KIDYX+OpnVrWAUXMmnKT+JAI7Tk3vtYPiWe7E slg+8m7jXsFfZE5vaJOeFMbMfxC1jVNy+azO/EMg41kKW7pJHCTsGnChrteJ1ocv1iycl NAPf7E==ofag -----END PGP PRIVATE KEY BLOCK----- ``` 11. Enter the **PGP Private Key Password** generated at the Oracle Fusion HCM system. 12. Enter the unique end point **URL** to connect to the Oracle Fusion HCM managed system. For example: ```text https://{yourOracleCloudDomain}.com ``` > **Note** > > SailPoint recommends using HTTPS for a secured connection. 13. In **API Authentication Settings**, for **Authentication Type**, select **Basic Authentication** or **OAuth 2.0 JWT User Assertion**. **Basic Authentication** is the default. > **Note** > > Existing basic authentication configurations continue to work without changes. - **Basic Authentication** Enter the **Username** and **Password** that connects with the end point database. - **OAuth 2.0 JWT User Assertion** > **Screenshot** > > [![OAuth 2.0 JWT User Assertion authentication settings]()]() > **Note** > > One signing certificate signs both the user assertion and the client assertion. For Oracle-side setup, refer to [Configuring OAuth 2.0 JWT User Assertion](<#configuring-oauth-20-jwt-user-assertion>). Provide the following details: - **Username** - The username is the subject of the user assertion. Enter the identity-domain **Username**. Use that value when the username and email differ. - **OAuth Token URL** - Enter the Oracle token endpoint that receives the user assertion and the client assertion. - **OAuth Client ID** - Enter the **Client ID** from the confidential application OAuth configuration page. Do not use the Fusion service parameter `IDCS_CONNECTOR_CLIENT_ID`. - **OAuth Scope** - Enter the Fusion Applications client scope. Copy it from the confidential application **Resources** table, or from the Fusion service parameter `IDCS_CONNECTOR_CLIENT_SCOPE`. Scope values differ by instance. Do not rebuild the string from a screenshot. Do not use the Spectra / Oracle BOSS scope `urn:opc:resource:fusion::boss/`. - **OAuth Audience** - Enter the audience expected by Oracle Identity Cloud Service. The audience is the JWT `aud` claim, normally `https://identity.oraclecloud.com/`. It is separate from the Fusion primary audience used inside the scope. - **Signing Key ID** - Enter the certificate alias (`kid`). - **Signing Private Key** - Enter the PEM-formatted private key. - (Optional) **Private Key Passphrase** - If the signing private key is encrypted, enter its passphrase. 14. Enable **Via API Authentication** if you want to use the API authentication credentials you provide instead of the SFTP server authentication. 15. Select **Enter**. ## Configuring OAuth 2.0 JWT User Assertion Follow [Configure OAuth to Access Oracle Fusion Cloud Applications REST APIs](), section **Configure OAuth Using User Assertion Grant Type**. > [!NOTE] > > Do not change the name of the OAuth token issuer. ### Identifying the Identity Domain and Token URL 1. Sign in to the OCI Identity and Access Management console as an administrator of the identity domain associated with the Fusion Applications instance. 2. Open that domain and copy the **Domain URL** from the domain details page. 3. The **OAuth Token URL** is the **Domain URL** plus `/oauth2/v1/token`. The same endpoint is listed in `https:///.well-known/idcs-configuration`. ### Registering the Confidential Application 1. In that identity domain, open **Integrated applications** and select **Add application**. 2. Select **Confidential Application** and select **Launch workflow**. 3. Enter an application name. Skip the other fields and select **Submit**. 4. In **OAuth configuration**, select **Edit OAuth**, then **Configure this application as a client now**. 5. Under **Authorization**, select only **JWT assertion**. 6. Under **Client type**, select **Trusted**. A trusted client can request access tokens with a signed JWT assertion. 7. Select **Import certificate** and import the public signing certificate that matches the private key stored in SailPoint. Set the certificate alias to the JWT Key Identifier (`kid`). That alias is the connector **Signing Key ID**. 8. Under **Token issuance policy**, set **Authorized resources** to **specific**. 9. Turn on **Add resources**. Select **Add scope**, select **Oracle Applications Cloud (Fusion)**, and add the Fusion client scope described in [Generating the OAuth Scope](<#generating-the-oauth-scope>). Remove any resource that is not required. 10. From the **Actions** menu, select **Activate**, then **Activate application**. 11. On the OAuth configuration page, copy the **Client ID**. That value is the connector **OAuth Client ID**. Do not use the Fusion service parameter `IDCS_CONNECTOR_CLIENT_ID`. Also import the same public certificate in the same domain under **Security** \> **Trusted partner certificates**, using the same alias as the JWT `kid`. Oracle stores one certificate on the confidential application. The connector uses the matching private key to sign both the user assertion and the client assertion. ### Generating the OAuth Scope The connector **OAuth Scope** is the Fusion Applications client scope. Do not use the Spectra / Oracle BOSS scope (`urn:opc:resource:fusion::boss/`). 1. In the same identity domain, open **Oracle Cloud Services** and select **Oracle Applications Cloud (Fusion)**. 2. Go to **OAuth configuration** \> **Configure application APIs that need to be OAuth protected** \> **Scopes**. 3. Copy the primary audience. Oracle shows it in one of these forms: - `urn:opc:resource:fa:instanceid=` - `urn:opc:resource:faaas:fa:` 4. Copy the resource scope. For this connector, use `urn:opc:resource:consumer::all`. 5. Concatenate the primary audience and the resource scope with no space and no extra slash. For example: ```text urn:opc:resource:fa:instanceid=urn:opc:resource:consumer::all ``` 6. Add that exact string on the confidential application **Resources** list. 7. Enter the same string in the connector **OAuth Scope** field. Copy it from the **Resources** table, or from the Fusion service parameter `IDCS_CONNECTOR_CLIENT_SCOPE`. Scope values differ by instance. Do not rebuild the string from a screenshot. **OAuth Audience** is the JWT `aud` claim, normally `https://identity.oraclecloud.com/`. It is separate from the Fusion primary audience used inside the scope. ### Mapping Oracle Values to Connector Fields | Oracle Value | Connector Field | | --- | --- | | **Domain URL** + `/oauth2/v1/token` | OAuth Token URL | | Confidential Application Client ID | OAuth Client ID | | Primary audience concatenated with `urn:opc:resource:consumer::all` | OAuth Scope | | `https://identity.oraclecloud.com/` | OAuth Audience | | Certificate alias (`kid`) | Signing Key ID | | Matching private key | Signing Private Key | | Identity-domain **Username** | Username (user assertion subject) | The API username must be the identity-domain **Username**. Use that value when the username and email differ. ## Aggregation Settings For more information about aggregation, refer to [Loading Account Data](). Use the settings available in **Aggregation Settings** to adjust aggregation processes as required for your organization. > [!NOTE] > > - When full aggregation is triggered, the connector always reads data from CSV files. > - Past and Future offsets for full aggregation are configured under **Filter Condition** when generating the extract. For more information about filter conditions, refer to the [Oracle HCM Cloud Export File Guide](). > - The **Past Termination Offset** and **Future Offset** values are applicable only when delta aggregation is triggered. > [!NOTE] > > **Screenshot** > > [![Aggregation Settings]()]() [![Aggregation Settings]()]() [![Aggregation Settings]()]() [![Aggregation Settings]()]() [![Aggregation Settings]()]() 1. Enable aggregation options as per your requirements: - **Aggregate Employes** will aggregate employee type workers. - **Aggregate Contractors** will aggregate contractor type workers. - **Aggregate Pending Workers** will aggregate pending worker type workers. - **Aggregate Non Workers** will aggregate non worker type workers. > **Note** > > Selection of at least one person type is mandatory 2. Enter the **Page Size** as the number of records to aggregate in a single page when iterating over large datasets, from 1 to 499 records. The default is 100 records. 3. Enable **Delta Aggregation** to aggregate accounts that have changed since the last execution. For more information about supported ATOM feeds, refer to [Delta Aggregation via ATOM Feeds](<#delta-aggregation-via-atom-feeds>). 4. Configure the **Delta Aggregation Page Size** as the number of records to aggregate in a single page when iterating over large datasets, from 1 to 499 records. The default is 100 records. 5. Enable **Delta Aggregation Via Worker CSV Extractor** to aggregate delta accounts by using the Worker CSV Extractor. > **Note** > > Selecting this option configures the connector to read from the delta file paths specified below. When disabled, ATOM Feeds API is used by default. 1. Enter the fully qualified file path and file name of the delta Active Workers CSV extract file in **Delta Active Workers File Path**. 2. Enter the fully qualified file path and file name of the delta Future Workers CSV extract file in **Delta Future Workers File Path**. 3. Enter the fully qualified file path and file name of the delta Terminated Workers CSV extract file in **Delta Terminated Workers File Path**. 6. Enter the **Past Termination Offset** as the number of past days to aggregate terminated workers. For example, the number 14 will aggregate workers whose termination date is within a 14 day range in the past. > **Note** > > This date offset setting applies only to single account aggregation and delta aggregation by using the ATOM Feeds API. It does not apply if **Delta Aggregation Via Worker CSV Extractor** is enabled. 7. Enter the **Future Offset** as the number of days in advance to aggregate future hires and terminations. For example, the number 14 will aggregate workers 14 days in advance of their joining date. > **Note** > > This date offset setting applies only to single account aggregation and delta aggregation by using the ATOM Feeds API. It does not apply if **Delta Aggregation Via Worker CSV Extractor** is enabled. 8. Define **Retryable Errors**, which are error messages from the Oracle Fusion HCM system that, when returned, tell the connector to retry failed operations. Enter the error message in the field provided and press **Enter** to add it to the list. 9. Enter the **Connection Timeout** as the duration of inactivity the connector allows before terminating its connection to the source. The default is 1 minute. 10. Select **Save**. ### Delta Aggregation via ATOM Feeds The Oracle HCM Cloud connector supports delta aggregation for accounts. Delta aggregation aggregates accounts that have changed since the last aggregation. > [!NOTE] > > When **Delta Aggregation Via Worker CSV Extractor** is disabled, the connector uses the Oracle HCM ATOM Feeds API for delta aggregation. For more information about aggregation settings, refer to [Aggregation Settings](<#aggregation-settings>). #### Supported ATOM Feeds When delta aggregation uses the ATOM Feeds API, the Oracle HCM Cloud connector supports the following Atom feeds: | Atom Feed | Feed Code | Description | | --- | --- | --- | | New Hire | `newhire` | Triggered when an employee is hired, a terminated employee is rehired, or a future-dated new hire is created. | | Employee Assignment Update | `empassignment` | Triggered when assignment, salary, or manager information is created, updated, corrected, or deleted, or when assignment flexfields are updated. | | Employee Update | `empupdate` | Triggered when person details such as name, email, phone, address, national identifier, passport, citizenship, religion, or flexfields are created, updated, or corrected. | | Termination | `termination` | Triggered when an employee is terminated. | | Person Work Relationship Cancelled | `cancelworkrelship` | Triggered when a work relationship is cancelled. | | Employee Work Relationship Updated | `workrelshipupdate` | Triggered when the work relationship of an active employee is updated, including changes to the start date and other configured attributes. | ## Attribute Mapping The Oracle HCM Cloud connector uses a combination of REST API, Atom Feeds, and File Export to read data from the Oracle Fusion HCM source. The attribute name in the Oracle File export can be anything you choose. However, the parameter names in the REST API and Atom Feed are rigidly configured. To keep all the information in sync, you must map the attributes properly. > [!NOTE] > > For a list and correlation information of the API parameters, refer to [Employees]() for account attributes and [Assignments]() for entitlement attributes in the Oracle documentation. The linked documents are not maintained by SailPoint and are subject to change without notice. > [!NOTE] > > **Screenshot** > > [![Attribute Mapping]()]() > [!CAUTION] > > Failure to properly map an attribute will result in data not being fetched for the specified attribute. This may result in inconsistent behavior between full, delta, and single account aggregation processes. For example, the three attribute names in the following list all describe the same account attribute. In this example, they describe a given worker's start date. However, it might go by a different attribute name in the Workers Attribute column or the Atom Feeds column. - `HIRE_DATE` - The worker's start date according to the CSV file/Schema Attribute for full aggregation processes. - `workRelationships.StartDate` - The worker's start date according to the Workers Attribute for single account aggregation. - `DateStart` - The worker's start date according to the Atom Feeds Attribute for delta aggregation processes. In the following table, each row represents a single mapped account attribute. You configure which attribute name in each account data file that the connector uses for the attribute. With the information provided earlier, you can map the attribute like it is in the first row. Two other attributes, `PERSON_NUMBER` and `WORKER_TYPE`, are provided as additional examples. | CSV/Schema Attribute | Workers Attribute | Atom Feeds Attribute | | --- | --- | --- | | HIRE\_DATE | workRelationships.StartDate | DateStart | | PERSON\_NUMBER | PersonNumber | PersonNumber | | WORKER\_TYPE | workRelationships.WorkerType | PeriodType | To map an attribute: 1. In the **CSV/Schema Attribute** field, enter the attribute's name in the CSV file extracted from the Oracle HCM source. 2. In the **Workers Attribute** field, enter the corresponding Workers API attribute name of the extract column header. 3. In the **ATOM Feeds Attribute** field, enter the corresponding Atom feeds API attribute name of the extract column header. 4. (*Optional*) Select **Add Another** to add another row to the list to map an additional attribute. Repeat steps 1-3 as needed for each attribute. 5. Select **Save**. > [!NOTE] > > If you want to map an attribute, but there is no corresponding parameter in either the Workers Attribute or Atom Feeds available from Oracle, reach out to Oracle's support team create a new parameter. ## JSON Path Mapping > [!WARNING] > > The `PERSON_NUMBER` attribute should not be updated in the JSON Path Mapping. > [!NOTE] > > **Screenshot** > > [![JSON Path Mapping]()]() ### Full Aggregation The Oracle HCM Cloud connector will aggregate the attributes associated with the primary work relationship and corresponding assignments based on the dates. In order to change this behavior, specify the attribute value as specified below in JSON Path Mapping. This will enable the customer to fetch the work relationship and Job Information in accordance with your requirements. The following API response is an example of how to specify the JSON path query for the `workRelationships` attribute: ```json "workRelationships": [ { "PeriodOfServiceId": 300000034528102, "LegislationCode": "IN", "WorkerType": "E", "PrimaryFlag": true, "StartDate": "2022-08-11", "assignments": [ { "AssignmentId": 300000034528108, … } ] }, "PeriodOfServiceId": 300000034528226, "LegislationCode": "IN", "WorkerType": "N", "PrimaryFlag": false, "StartDate": "2022-08-23", "assignments": [ {"AssignmentId": 300000034528233, … } ] ``` #### Case 1 If concurrent `workRelationships` are active and you want to fetch the attribute from primary `workRelationships` such as `PeriodOfServiceId`, then the JSON path for attribute mapping is: ```text workRelationships[?(@.PrimaryFlag==true)].PeriodOfServiceId ``` #### Case 2 If concurrent `workRelationships` are active and you want to fetch the attribute from secondary `workRelationships` such as `PeriodOfServiceId`, then the JSON path for attribute mapping is: ```text workRelationships[?(@.PrimaryFlag==False)].PeriodOfServiceId ``` #### Case 3 If multiple `workRelationships` attributes are active, the API response looks like the following: ```json "workRelationships": [ { "PeriodOfServiceId": 300000034528102, "LegislationCode": "IN", "WorkerType": "E", "PrimaryFlag": true, "StartDate": "2022-08-11", "assignments": [ {"AssignmentId": 300000034528108, "AssignmentType": "E", "PrimaryFlag": true, "PrimaryAssignmentFlag": true, … } ] }, "PeriodOfServiceId": 300000034528226, "LegislationCode": "IN", "WorkerType": "N", "PrimaryFlag": false, "StartDate": "2022-08-23", "assignments": [ {"AssignmentId": 300000034528233, "AssignmentType": "P", "PrimaryFlag": false, "PrimaryAssignmentFlag": true, … } ] ``` If you want to fetch the attribute from assignments which is primary and belongs to a particular `AssignmentType` such as `AssignmentId`, then the JSON path for attribute mapping is: ```text workRelationships..assignments[?(@.PrimaryAssignmentFlag==true && @.AssignmentType=='E' && @.PrimaryFlag==true)].AssignmentId ``` 1. Select **Add Another** to add a new entry. 2. In each row, enter a **CSV/Schema Attribute** name, its corresponding **JSON Path**, and **ATOM Feeds Attribute**. 3. (*Optional*) Select **Add Another** to add more rows to the list. 4. Select **Save**. ### Delta Aggregation The Oracle ATOM feed API response is divided into the following parts: - Context - Changed Attributes By default, the Oracle HCM Cloud Connector fetches the information from the `Changed Attributes` section. If you want to change this behavior, the **JSON Path** mapping section can be used. For example, ```json Context" : [ { "PersonNameId" : "300000040265075", "PersonName" : " 7939first", "PersonNumber" : "7939", "WorkEmail" : "test@gmail.com", "PrimaryPhoneNumber" : "", "PersonId" : "300000040265074", "PeriodType" : "E", "WorkerType" : "EMP", "DMLOperation" : "UPDATE", } ], "Changed Attributes" : [ { "OrderName" : { "old" : "test", "new" : "test 7939first" } }, { "ListName" : { "old" : "test", "new" : "test1" } }, { "FirstName" : { "old" : null, "new" : "7939first" } }, { "FullName" : { "old" : "test", "new" : "7939first" } }, }, { "Title" : { "old" : null, "new" : "MR." } }, { "MiddleNames" : { "old" : null, "new" : "7939middle" } } ] }] ``` In the following example, the `PersonName` attribute is not available in `Changed Attributes`. Therefore, the connector will not fetch the value out of the box. To fetch it, you can specify the following JSON path. ```text Context[0].PersonName ``` ## Review and Test Perform a test to confirm the connection to SailPoint. 1. Go to **Review and Test**. 2. Confirm that the entries in each field are correct. If you note any mistakes, return to the section and make corrections. 3. Select **Test Connection**. ## SailPoint Application Onboarding SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface. For more information, refer to [Application Onboarding]() in the SailPoint SaaS documentation.