Prerequisites for Creating a Connection

Subscribe to Oracle HCM Cloud

Subscribe to Oracle HCM Cloud. This action enables you to create an Oracle HCM Cloud user account with the correct privileges. You specify this user account when creating an Oracle HCM Cloud Adapter connection on the Connections page.

For information about specifying these credentials on the Connections page, see Configure Connection Security. For information about subscribing, see Oracle HCM Cloud.

Request Access to Atom Feeds and REST APIs Capabilities on Your Oracle HCM Cloud Instances

Oracle HCM Cloud Atom feeds and Oracle HCM Cloud REST APIs support is available by default in the Oracle HCM Cloud Adapter in Oracle Integration. However, for the Oracle HCM Cloud application, you must first request access to Atom feeds and REST APIs capabilities on your Oracle HCM Cloud instance(s).

See the steps described in My Oracle Support Note 2060899.1. Once these are enabled in your Oracle HCM Cloud application, Atom feeds and REST APIs appear in the Oracle HCM Cloud Adapter in Oracle Integration.

Assign Required Roles to an Integration User

To use the Oracle HCM Cloud Adapter in an integration, you must assign specific roles to an integration user.

Associating the Integration User with the Following Roles and Privileges

You associate the user with the following roles and privileges.

Role	Description
ALL_INTEGRATION_POINTS_ALL_DATA	Starting with release 12, this role is no longer supported. When existing customers upgrade to release 12, users with this role continue using it, although it is hidden from the Security Console. If you create a new integration user in release 12 or later, you cannot assign this role.
ORA_HRC_HUMAN_CAPITAL_MANAGEMENT_INTEGRATION_SPECIALIST_JOB	Human Capital Management Integration Specialist. The role applies to Releases 12 and 13.
AttachmentsUser	Provides access to the Attachments security group to download the log file or the output file with the HCM Integration Service. Starting with Release 12, this role is automatically shipped. You must verify that this role is automatically assigned to the user.
SOAOperator	The SOA Operator role.
FND_MANAGE_CATALOG_SERVICE_PRIV	Role for managing the web services catalog.
For Oracle CRM Cloud implementations, you can also assign the Customer Relationship Management Application Administrator role.	See Customer Relationship Management Application Administrator (Job Role) of Security Reference for CX Sales and B2B Service.

Additional roles may be required as per each interface requirements.

Using the Security Console

Use the Security Console to manage application security such as roles, users, certificates, and administration tasks. Access to the Security Console is provided by the predefined Security Manager role. Access the Security Console in the following ways:

Use the Manage Job Roles or Manage Duties tasks in the Setup and Maintenance work area.
Select Navigator > Tools > Security Console.

Description of the illustration sales_cloud_security.png

Create an HCM-compliant .dat File to Use the HCM Data Loader

If you want to use the HCM Data Loader for bulk-loading and maintaining data, you must create a .dat file that is HCM-compliant. See your Oracle HCM Cloud documentation for instructions.

Upload Files to Oracle WebCenter Content

You must satisfy the following prerequisites if you want to upload a file to Oracle WebCenter Content (Universal Content Manager) with the Oracle HCM Cloud Adapter.

Create a PGP Public Key for Encrypted File Upload:

To upload encrypted files, a PGP public key is required. You must generate the PGP public key and save it for upload. The supported algorithm for the public key is RSA for encryption and the key size must be 1024 bits in length.

The process for uploading files into Oracle HCM Cloud is:
- You encrypt files using the Oracle HCM Cloud public key.
- The data-loading process decrypts files using the Oracle HCM Cloud private key.
See Set up Encryption for File Transfer in HCM Data Loader.
Configure Security and User Access

Once you have configured security groups and doc accounts for the file to upload, you can configure the Oracle HCM Cloud Adapter to upload the file to Oracle WebCenter Content.

Perform Prerequisites to Use the OAuth Authorization Code Credentials Security Policy

You must set up trust between Oracle Fusion Applications and Oracle Identity Cloud Service and create a client application for Oracle Integration if you want to use the OAuth Authorization Code Credentials security policy. Once these tasks are completed, you can successfully configure a connection on the Connections page.

Set Up Trust Between Oracle Fusion Applications and Oracle Identity Cloud Service

Get the JWK signing certificates from the Oracle Identity Cloud Service of Oracle Integration.
1. Get the REST API of the Oracle Identity Cloud Service endpoint that gives you the signing certificate endpoint. For example:
```
/admin/v1/SigningCert/jwk
```
  See All REST Endpoints in REST API for Oracle Identity Cloud Service.
2. Copy the endpoint.
3. Get the Oracle Identity Cloud Service URL from the Oracle Cloud Infrastructure Console or from the Oracle Integration About menu.
4. Add that URL to the front of the signing certificate and use a tool (for example, postman) to invoke the REST APIs. For example:
```
https://IDCS_URL.identity.oraclecloud.com/admin/v1/SigningCert/jwk
```
5. Perform a GET call to retrieve the payloads of the certificates. There are two sections in the payload:
  - Oracle Identity Cloud Service certificate
  - Certificate authority (CA) certificate
  Examples of the type of response you receive are provided. See Retrieve the Tenant's Signing Certificate in JWK Format.
6. Copy both certificate sections into separate files. Note that the headers and footers in the files must be in the following exact format to be successfully uploaded to Oracle Fusion Applications:
```
-----BEGIN CERTIFICATE-----
 content_of_certificate
. . .
. . .
-----END CERTIFICATE-----
```
  You can validate the certificate. For example:
```
openssl x509 -in IDCS.cert -noout -text
```
Upload the certificates to the Oracle Fusion Applications Security Console.
1. Log in to Oracle Fusion Applications as a user with the IT Security Manager role.
2. In the navigation pane, select Tools, then Security Console.
3. Select API authentication in the left navigation pane.
4. Click Create Oracle API Authentication Provider, then click Edit in the upper right.
5. In the Trusted Issuer field, enter:
```
https://identity.oraclecloud.com
```
6. In the Token Types section, select JWT.
7. Click Save and Close.
8. Click Inbound API Authentication Public Certificates, then click Add New Certificate.
9. Enter a name in the Certificate Alias field (for example, MY_IDCS_CERT).
10. In the Import Public Certificate field, click Choose File to upload the first certificate file, then click Save.
11. Repeat these steps to upload the second certificate file.
Create an Oracle Identity Cloud Service resource application to represent the Oracle Fusion Applications resource.
1. Log in to Oracle Identity Cloud Service as the Oracle Identity Cloud Service administrator.
2. In the left navigation pane, click Applications, then click Add.
3. Click Confidential Application.
4. On the Details page, provide a name (for example, FA Resource), and click Next.
5. On the Client page, click Next without making changes.
6. On the Resources page, click Configure this application as a resource server now.
7. Optionally update the value in the Access Token Expiration field.
8. Select Is Refresh Token Allowed.
9. In the Primary Audience field, add the Oracle Fusion Applications URL and port. This is the primary recipient where the token is processed.
```
https://FA_URL:443
```
10. In the Scopes section, click Add.
11. In the Scope field, enter /.
12. In the Description field, enter All.
13. Select Requires Consent.
14. Click Add, then click Next.
15. On the Web Tier Policy and Authorization pages, click Next without making any changes.
16. Click Finish to complete resource application creation.
17. Click Activate to activate your client application. The resource server representing the resource is now active.

(Optional) Create a Local User

Note:

The following step is only required if the Oracle Fusion Applications user is not federated with Oracle Identity Cloud Service or whichever identity provider you are using.

Create an Oracle Identity Cloud Service local user. Carefully review the following table to see if you already have a local user.

Scenario	Do I Need to Create a Local User?
You have an Oracle Fusion Applications user federated with the Oracle Identity Cloud Service that is protecting Oracle Integration.	No. You do not need to create the local Oracle Identity Cloud Service Oracle Fusion Applications user. This is because Oracle Identity Cloud Service already has Oracle Fusion Applications users in its repository.
You do not have federation between Oracle Fusion Applications and the Oracle Identity Cloud Service that is protecting Oracle Integration.	Yes. You must create the local Oracle Identity Cloud Service Oracle Fusion Applications user that you plan to use with the OAuth setup in Oracle Integration.

The Oracle Identity Cloud Service administrator must create a nonfederated local username in Oracle Identity Cloud Service that matches the user in Oracle Fusion Applications. If you have already used and invoked Oracle Fusion Applications REST endpoints, you likely already created a user with the necessary roles and accesses to invoke the REST endpoints of Oracle Fusion Applications. This user must be created in Oracle Identity Cloud Service and have a local user password.

Create the Confidential Client Application for Oracle Integration

Sign in as the Oracle Identity Cloud Service administrator to the Oracle Cloud Infrastructure Console. This administrator must have Oracle Identity Cloud Service instance access.
In the left navigation pane, select Applications, then click Add to add a client application.
Select Confidential Application.
The Add Confidential Application wizard is displayed.
On the Details page, enter an application name, and click Next.
On the Client page, click Configure this application as a client now.
In the Authorization section, select Refresh Token and Authorization Code.

In the Redirect URL field, enter your Oracle Integration instance URL. For example:

Note:

If you don't know the following information, check with your administrator:

If your instance is new or upgraded from Oracle Integration Generation 2 to Oracle Integration 3.
The complete instance URL with the region included (required for new instances).

For Connections… Include the Region as Part of the Redirect URL? Example of Redirect URL to Specify…

For Connections…	Include the Region as Part of the Redirect URL?	Example of Redirect URL to Specify…
Created on new Oracle Integration 3 instances	Yes.	`https://OIC_instance_URL.region.ocp.oraclecloud.com/icsapis/agent/oauth/callback`
Created on instances upgraded from Oracle Integration Generation 2 to Oracle Integration 3	No. This applies to both: New connections created after the upgrade Existing connections that were part of the upgrade	`https://OIC_instance_URL.ocp.oraclecloud.com/icsapis/agent/oauth/callback`

Created on new Oracle Integration 3 instances

Yes.

https://OIC_instance_URL.region.ocp.oraclecloud.com/icsapis/agent/oauth/callback

Created on instances upgraded from Oracle Integration Generation 2 to Oracle Integration 3

No.

This applies to both:

New connections created after the upgrade
Existing connections that were part of the upgrade

https://OIC_instance_URL.ocp.oraclecloud.com/icsapis/agent/oauth/callback

For the OAuth authorization code to work, the redirect URI must be set properly.

Under Resources, click Add Scope to add appropriate scopes.
If the Oracle Fusion Applications instance is federated with the Oracle Identity Cloud Service instance, the Oracle Integration cloud service application is listed among the resources for selection. This enables the client application to access Oracle Integration.
Search for the Oracle Fusion Applications resource application created in Set Up Trust Between Oracle Fusion Applications and Oracle Identity Cloud Service.
Select the resource and click >.
Select the scope, then click Add.
Click Next without making changes on the Resource and Web Tier Policy pages.
On the Authorization page, click Finish.
The Application Added dialog shows the client ID and client secret values.

Copy and save these values. You need this information when creating a connection for the OAuth Authorization Code Credentials security policy on the Connections page.

Note the following details for successfully authenticating your account on the Connections page.

If The...	Then...
Oracle Identity Cloud Service safeguarding Oracle Integration and the Oracle Fusion Applications resource application are the same.	Log in to Oracle Integration using the local Oracle Fusion Applications user created earlier. You must create a connection and click Provide Consent on the Connections page for authentication to succeed.
Oracle Identity Cloud Services safeguarding Oracle Integration and the Oracle Fusion Applications resource application are different.	Log in to Oracle Integration using a general Oracle Integration developer account, create a connection, and click Provide Consent on the Connections page. You need to log in to the Oracle Fusion Applications resource Oracle Identity Cloud Service application using the local Oracle Fusion Applications user account created earlier.

Activate the application.

Avoid Potential Errors When Testing Your Connection with a Nonfederated User Account

After you configure the OAuth Authorization Code Credentials security policy on the Connections page, you must test your connection.

If you are logged in to Oracle Integration with an Oracle Integration user account and click Provide Consent to test the OAuth flow, consent is successful. However, when you test the connection, it fails with an Unauthorized 401 error.

This error occurs because the Oracle Integration user account with which you logged in is not part of Oracle Fusion Applications.

Log out of Oracle Integration and log back in with a user account that exists in Oracle Fusion Applications.
Return to the Connections page and retest the connection.
The connection is successful this time.

Verify the Status of Location-Based Access Control (LBAC)

Check if you have enabled Location-Based Access Control (LBAC) for Fusion Applications (for Oracle HCM Cloud).

If LBAC is enabled, you must allowlist (explicitly allow identified entities access) the Oracle Integration NAT Gateway IP address in your LBAC. If you do not perform this task, you can receive a 401 Access Denied error or 403 Forbidden error from Oracle Fusion Applications.

See How Location-Based Access Works in Securing SCM and Doc ID 2615294.1 at Oracle Support Services.

Specifying the Oracle HCM Cloud Service Catalog Service WSDL or Event Catalog URL

You must specify a mandatory Oracle HCM Cloud service catalog service WSDL (for accessing business objects) and optionally an event catalog URL (for accessing event subscriptions).

Obtaining the Oracle HCM Cloud Catalog Service WSDL

WSDL Requirements	Where Do You Get the WSDL
The URL must be that of a service catalog service WSDL. The service catalog service enables clients to retrieve information about all public Oracle Fusion Application service endpoints available for that instance. The information it returns is specific to the particular cloud instance and also reflects the new services that may have been introduced in patches applied to the instance. This service is used to programmatically discover the SOAP services available on the cloud instance and retrieve the necessary metadata to invoke the SOAP services to manage business objects.	The developer creating an Oracle HCM Cloud connection must work with the Oracle HCM Cloud service administrator to get the concrete WSDL URL for the service catalog service provisioned for the specific SaaS application. The concrete WSDL URL must be supplied while creating the connection.

WSDL Requirements

Where Do You Get the WSDL

The URL must be that of a service catalog service WSDL. The service catalog service enables clients to retrieve information about all public Oracle Fusion Application service endpoints available for that instance. The information it returns is specific to the particular cloud instance and also reflects the new services that may have been introduced in patches applied to the instance. This service is used to programmatically discover the SOAP services available on the cloud instance and retrieve the necessary metadata to invoke the SOAP services to manage business objects.

The developer creating an Oracle HCM Cloud connection must work with the Oracle HCM Cloud service administrator to get the concrete WSDL URL for the service catalog service provisioned for the specific SaaS application. The concrete WSDL URL must be supplied while creating the connection.

Prerequisites

This section describes how to derive the external virtual host and port for a tokenized service WSDL. The topology information in the Topology Registration setup task contains the external virtual host and port for the domains and applications. The following instructions describe the steps for deriving the values using the service catalog service WSDL URL as an example: https://atf_server:port/fndAppCoreServices/ServiceCatalogService.

To access the Review Topology page, the ASM_REVIEW_TOPOLOGY_HIERARCHY_PRIV entitlement must be granted to the user's job role. The entitlement is granted to the ASM_APPLICATION_DEPLOYER_DUTY duty role, which is inherited by the duty roles ASM_APPLICATION_DEVELOPER_DUTY and ASM_APPLICATION_ADMIN_DUTY.

If the menu items and tasks described in the following procedure are not available in your cloud instance, your user account is missing the required role. Contact your cloud instance security administrator for assistance.

Log in to the cloud instance.
Click the Navigator icon in the global area in the top part of the window, then chose Setup and Maintenance under the Tools heading.
Select Review Topology under the Topology Registration section in the Tasks regional area on the left side of the window.
Click the Detailed tab in the middle of the window.

The tab shows the list of domains configured in the cloud instance.

Description of the illustration osc_get_wsdl_detals.png

Map the token name for the service path value to the domain name in the Topology Manager:

Token Name in Service Path	Domain Name
atf_server	CommonDomain
crm_server	CRMDomain
fin_server	FinancialDomain
hcm_server	HCMDomain
ic_server	ICDomain
prc_server	ProcurementDomain
prj_server	ProjectsDomain
scm_server	SCMDomain

Expand the domain name and select any external virtual host and port for the J2EE applications that are deployed on the domain. In the sample window, the values for this particular instance are fs-your-cloud-hostname and 443, respectively.

Description of the illustration osc_get_wsdl_detals2.png
Replace the domainName_server:PortNumber with the external virtual host and port identified in the previous step. For example:

https://fs-your-cloud-hostname:port/fndAppCoreServices/ServiceCatalogService?wsdl

Obtaining the Event Catalog URL

You must know the CRM URL format to access the CRM application user interface. Follow the URL format to determine the event catalog URL. For example, if the CRM URL format is:

https://fusxxxx-crm-ext.us.oracle.com/customer/faces/CrmFusionHome

Then the event catalog URL is:

https://fusxxxx-crm-ext.us.oracle.com/soa-infra

For Fusion Applications Releases 10 Through 12

Obtain the Oracle Fusion Applications Releases 10 through 12 service catalog service WSDLs and interface catalog URLs through the following methods.

Obtain the Service Catalog Service WSDL for Releases 10 Through 11

WSDL Requirements	Where Do You Get the WSDL?
The URL must be that of a service catalog service WSDL. The service catalog service is a Fusion Application service that returns a list of external services available for integration. It allows clients to retrieve information about all public Fusion Application service endpoints available for that instance. The service catalog service enables clients to retrieve information about all public Oracle Fusion Application service endpoints available for that instance. The information it returns is specific to the particular cloud instance and also reflects the new services that may have been introduced in patches applied to the instance. This service is used to programmatically discover the SOAP services available on the cloud instance and retrieve the necessary metadata to invoke the SOAP services to manage business objects.	The developer creating an Oracle HCM Cloud connection must work with the Oracle HCM Cloud service administrator to get the concrete WSDL URL for the service catalog service provisioned for the specific SaaS application.

WSDL Requirements

Where Do You Get the WSDL?

The URL must be that of a service catalog service WSDL. The service catalog service is a Fusion Application service that returns a list of external services available for integration. It allows clients to retrieve information about all public Fusion Application service endpoints available for that instance.

The service catalog service enables clients to retrieve information about all public Oracle Fusion Application service endpoints available for that instance. The information it returns is specific to the particular cloud instance and also reflects the new services that may have been introduced in patches applied to the instance. This service is used to programmatically discover the SOAP services available on the cloud instance and retrieve the necessary metadata to invoke the SOAP services to manage business objects.

The developer creating an Oracle HCM Cloud connection must work with the Oracle HCM Cloud service administrator to get the concrete WSDL URL for the service catalog service provisioned for the specific SaaS application.

This section describes how to derive the external virtual host and port for a tokenized service catalog service WSDL. The topology information in the Topology Registration setup task contains the external virtual host and port for the domains and applications. The following instructions describe the steps for deriving the values using the service catalog service WSDL URL as an example: https://atf_server:port/fndAppCoreServices/ServiceCatalogService.

To access the Review Topology page, the ASM_REVIEW_TOPOLOGY_HIERARCHY_PRIV entitlement must be granted to the user’s job role. The entitlement is granted to the ASM_APPLICATION_DEPLOYER_DUTY duty role, which is inherited by the duty roles ASM_APPLICATION_DEVELOPER_DUTY and ASM_APPLICATION_ADMIN_DUTY.

If the menu items and tasks described in the following procedure are not available in your cloud instance, your user account is missing the required role. Contact your cloud instance security administrator for assistance.

Log in to the cloud instance.
Click the Navigator icon in the global area in the top part of the window, then chose Setup and Maintenance under the Tools heading.
Select Review Topology under the Topology Registration section in the Tasks regional area on the left side of the window.
Click the Detailed tab in the middle of the window.

The tab shows the list of domains configured in the cloud instance.

Description of the illustration osc_get_wsdl_detals.png

Map the token name for the service path value to the domain name in the Topology Manager:

Token Name in Service Path	Domain Name
atf_server	CommonDomain
crm_server	CRMDomain
fin_server	FinancialDomain
hcm_server	HCMDomain
ic_server	ICDomain
prc_server	ProcurementDomain
prj_server	ProjectsDomain
scm_server	SCMDomain

Expand the domain name and select any external virtual host and port for the J2EE applications that are deployed on the domain. In the sample window, the values for this particular instance are fs-your-cloud-hostname and 443, respectively.

Description of the illustration osc_get_wsdl_detals2.png
Replace the domainName_server:PortNumber with the external virtual host and port identified in the previous step. For example:

https://fs-your-cloud-hostname:port/fndAppCoreServices/ServiceCatalogService?wsdl

Obtain the Service Catalog Service WSDL For Release 12

To obtain the physical endpoint of your instance, perform the following steps:

Log in to the Fusion Applications home page. For example:
```
https://acme.fs.us2.oraclecloud.com/homePage/faces/FuseWelcome
```
Where acme is the system name and fs is a Fusion Applications domain.
Copy https://acme.fs.us2.oraclecloud.com/ and append fndAppCoreServices/ServiceCatalogService?WSDL. For example:
```
https://acme.fs.us2.oraclecloud.com/fndAppCoreServices/ServiceCatalogService?WSDL
```

Obtain the Interface Catalog URL

The interface catalog URL takes the following format:

https://fusxxxx-fs-ext.us.oracle.com/helpPortalApi/otherResources/latest/interfaceCatalogs

For Fusion Applications Releases 13 and Later

Obtain the Oracle Fusion Applications Release 13 and later service catalog service WSDLs and interface catalog URLs through the following methods.

Obtain the Service Catalog Service WSDL

To obtain the physical endpoint of your instance, perform the following steps:

Log in to the Fusion Applications home page. For example:
```
https://acme.fa.us6.oraclecloud.com/fscmUI/faces/FuseWelcome
```
Where acme is the system name and us6 is the data center.
Copy https://acme.fa.us6.oraclecloud.com/ and append it with fscmService/ServiceCatalogService?WSDL. For example:
```
https://acme.fs.us2.oraclecloud.com/fscmService/ServiceCatalogService?WSDL
```

Obtain the Interface Catalog URL

The interface catalog URL takes the following format:

https://fusxxxx-fa-ext.us.oracle.com/fscmRestApi/otherResources/latest/interfaceCatalogs