Oracle Integration - HCM Cloud Directory Synchronization Lab

Background

Oracle Integration provides native connectivity to Oracle and non-Oracle Software as a Service (SaaS) and On-premises applications, such as Oracle ERP Cloud, Oracle Service Cloud, HCM Cloud, Salesforce, Workday, EBS, SAP, NetSuite and so on. Oracle Integration adapters simplify connectivity by handling the underlying complexities of connecting to applications using industry-wide best practices. To connect to a system, you just need to create a connection that requires minimal connectivity information.

Use Case

This use case explores how to use of Oracle Integration with Oracle HCM REST and ATOM services to provide information to an identity management system hosted by a customer.

The following diagram shows the interaction between the systems involved in this use case:

Before You Begin

Some steps in this tutorial have a icon next to them. Click this icon to copy the snippet of text to your clipboard and then paste where needed.

Your instructor will provide you the information you need to access the environments used in this lab.

For this lab we will provide you the following:

• Oracle Integration
• HCM Cloud
• FTP Server

Get Your Oracle Integration (OIC) Environment

Select your OIC Environment and enter your User Number to get the information needed to access Oracle Integration.

Select your OIC environment: 

User Number:  OK

• OIC URL:

  Select your OIC Environment to get your OIC URL.

• OIC User Name:

  Select your OIC Environment to get your OIC Username.

  Enter your User Number to get your OIC Username.

• OIC Password: Your password will be provided by the instructor.

Get Your HCM Cloud Environment

Select your HCM Cloud Payables environment to get the information needed to access Oracle HCM Cloud.

HCM Cloud Environment: 

• HCM Cloud URL:

  Select your HCM Cloud environment to get your HCM Cloud URL.

• HCM Cloud User Name:

  Select your HCM Cloud environment to get your HCM Cloud Username.

• HCM Cloud Password: Your password will be provided by the instructor.

Get Your FTP Environment

Select your FTP Environment to get the information to access the FTP server:

FTP Environment: 

• FTP Server:

  Select your FTP environment to get your FTP Server.

• FTP Port:

  Select your FTP environment to get your FTP Port.

• Protocol:

  Select your FTP environment to get your FTP Protocol.

• FTP User Name:

  Select your FTP environment to get your FTP Username.

• FTP Password: Your password will be provided by the instructor.

Sign In

1. Open your Oracle Integration instance.

   Select your OIC Environment to get your OIC URL.

2. Enter your user name and password.

   Select your OIC Environment to get your OIC Username.

   Enter your User Number to get your OIC Username.

   Your password will be provided by the instructor.

3. Click Sign In.

   The Home page appears.

   You are now logged in and ready to use Oracle Integration.

   

Create the Integration

1. On the Home page, click Integrations, and then click Integrations.
2. On the Integrations page, click Create.
3. In the Select Integration Style dialog, select Scheduled Orchestration.
4. Click Select.
5. In the Create New Integration dialog, configure the integration:

   1. What do you want to call your integration?

      Enter Directory Synchronization

      Enter your User Number to specify your unique integration name.

   2. In the What does this integration do? field, enter:

      This integration shows you how to use the HCM Cloud adapter with the REST adapter to generate a file for Identity Management.

6. Click Create.

Configure the Schedule Action

Configure the schedule action to get the last time the integration polled the ATOM service. This avoids pulling duplicate records from the ATOM feed.

1. Select the Schedule action.
2. Click .

3. Click .

   A new row appears.

4. Click the Parameter Name column and change the name to ATOMLastRunDateTime.
5. Click the Description column and enter Last successful processed ATOM pull.

6. In the Value column, enter --01T00:00:00.000Z.

   This sets the initial date to get the data from the HCM ATOM feed for the last six months.

7. Click Close.
8. Click Save.

Schedule the Next ATOM Polling

Schedule the current ATOM polling to the current date and time. The next time the integration runs, this will be the ATOMLastRunDateTime variable.

1. Click and from the Data section, drag Assign to the Integration canvas, and place it after the Schedule activity.

   

   The Create Action dialog appears.

2. In the Name field, enter assignCurrentTimeStamp.

3. Click Create.

   The Assign page appears.

4. Click .
5. Click the Variable column and change the name to ts.

6. In the Value column, click .

   The Expression Builder appears.

7. In the Expression field, enter concat(substring-before(/nssrcmpr:schedule/nssrcmpr:startTime,"."),".000Z").

8. Click Validate.

   A message confirming the expression is valid appears.

9. Click Close.

10. Click Validate.

    A message confirming the action is valid appears.

11. Click Close.
12. Click Save.

Access the HCM Cloud ATOM Feed

Let's use the HCM Cloud adapter to access the HCM Cloud ATOM feed.

1. Hover over the outgoing arrow for the assignCurrentTimeStamp activity and click .
2. In the Search field, type HCM Cloud.
3. Select HCM Cloud.
4. In the Basic Info page, name the endpoint: getNewHireATOMFeed.
5. Click Next.
6. In the Actions page, select Subscribe to Updates (via ATOM Feed).
7. Click Next.
8. On the Operations page, from the Select an ATOM Feed list, select Employee New Hire.

9. From the Max entries to process list, select 250.

   This ensures that most customers have all their new hires appear in the ATOM Feed response.

10. Click Next.

    A summary of the properties you configured appears.

11. Review the summary and click Done.
12. Click Save.

Define the Data Mapping

A Map action named Map to getNewHireATOMFeed is automatically created. We'll define this data mapping.

1. Select the Map to getNewHireATOMFeed action.

2. Click .

   The Data Mapping page appears.

3. In the Target section, expand ApplicationPullParameter.

4. Map the $ATOMLastRunDateTime field in the Sources section, to the updated-min field in the Target section.

   To map an element, select the element from the Sources section, then while clicking your mouse move it towards the target element. When you reach the target element the line turns green and a check mark appears.

5. Click Validate.

   A message confirming the mapping is valid appears.

6. Click Close.
7. Click Save.

Count the New Hires

The ATOM feed doesn't return the total number of new hires, so we'll configure an assign action to calculate the number of new hires.

1. Click and from the Data section, drag Assign to the Integration canvas and place it after the getNewHireATOMFeed activity.

   

   The Create Action dialog appears.

2. In the Name field, enter countOfNewHires.

3. Click Create.

   The Assign page appears.

4. Click .
5. Click the Variable column and change the name to countOfNewHires_assignment_1.

6. In the Value column, click .

   The Expression Builder appears.

7. In the Component section, expand Functions, and then expand Node-set.
8. Drag the Count to the Expression field.
9. In the Source section, locate the element EmployeeNewHireFeed_Update located under employeeNewHireFeedResponse, that is in turn located under $getNewHireATOMFeed.

10. Select the nodeSet parameter in the expression.

11. Drag the EmployeeNewHireFeed_Update function to the Count function in the Expression field.

12. Click Validate.

    A message confirming the expression is valid appears.

13. Click Close.

14. Click Validate.

    A message confirming the action is valid appears.

15. Click Close.
16. Click Save.

Check for New Records

Let's check if the ATOM feed returned new records, and define what to do next.

1. Click and from the Collection section, drag Switch to the Integration canvas and place it after the countOfNewHires activity.

   

   Two flow branches appear in the flow:

   • Undefined: this branch checks the countOfNewHires. If the expression evaluates to true, the instance follows the flow in this branch.
   • Otherwise: the instance follows this branch when the routing expression for the initial branch resolves to false.

Define the IF conditional flow

1. Select Undefined.

2. Click .

   The Expression Builder appears.

3. Define an expression to check if the ATOM feed contains any new hires:

   1. In the Expression Name field, enter no new hires.
   2. In the Source section, select $countofNewHires_assignment_1.

   3. Click .

      

      The $countofNewHires_assignment_1 variable appears in the first part of the expression, and a green check mark appears next to the variable.

   4. In the New Condition box, enter 0.0 in the field after the equal operator.

   5. Click Validate.

      A message confirming the expression is valid appears.

   6. Click Close.
4. Click Save.

5. Click and from the End section, drag Stop to the Integration canvas and place it after the IF no new hires condition.

   This lets the integration complete if there aren't any new hires.

   

Define the Otherwise Flow

1. Click and from the Data section, drag Assign to the Integration canvas and place it after the Otherwise activity.

   The Create Action dialog appears.

   This assign activity creates a temporary variable to store the file reference of a stage file activity.

2. In the Name field, enter StageFileRef.
3. Click Create.
4. Click .

5. Click in the Value column, and enter "" in the Expression field.

6. Click Validate.

   A message confirming the expression is valid appears.

7. Click Close.

8. Click Validate.

   A message confirming the action is valid appears.

9. Click Close.
10. Click Save.

Process the Records

Let's iterate over the new hires that you got from the ATOM feed in a JSON file, and retrieve the record for each new hire using the HCM Cloud REST service.

1. Click and from the Collection section, drag For Each to the Integration canvas and place it after the StageFileRef activity.

   

   The Create Action dialog appears.

2. In the Name field, enter ForEachEntry.

3. Select the EmployeeNewHireFeed_Update element located under EmployeeNewHireFeedResponse, that is in turn located under $getNewHireATOMFeed.

   The EmployeeNewHireFeed_Update represents an individual new hire in the JSON ATOM feed result.

4. Click .

   The EmployeeNewHireFeed_Update element appears in the Repeating Element field.

5. In the Current Element Name field, enter CurEntry.
6. Click Create.
7. Click Save.

Write New Records to Stage

Let's write each new record to a stage file.

1. Download the newEmployeeFile.csv file.

2. Click and from the Data section, drag Stage File to the Integration canvas and place it after the For Each activity.

   

   The Configure Stage File Action dialog appears.

3. Name your action: WriteRecordToStage.
4. Click Next.

5. On the Configure Operation page, enter the following values:

   1. From the Choose Stage File Operation list, select Write File.
   2. Click next to the Specify the Name field.

   3. In the Expression field enter "newCandidateRecord.csv".

      This will be the name of the temporary file that Oracle Integration writes to stage.

   4. Click Save, and then click OK.
   5. Click Exit Expression Builder.
   6. Click next to the Specify the Output Directory field.
   7. In the Expression field enter "/tmp".
   8. Click Save, and then click OK.
   9. Click Exit Expression Builder.
   10. Select Append to Existing File.
6. Click Next.
7. On the Schema Options page, click Next.

8. On the Format Definition page, enter the following values:

   1. Click the Choose File/Browse.

   2. Navigate to the location where you stored the newEmployeeFile you downloaded earlier and select it.

      A table with the structure of the csv file appears.

   3. In the Record Name field, enter User.
   4. In the Recordset Name field, enter NewUser.

9. Click Next.

   A summary of the properties you configured appears.

10. Review the summary and click Done.
11. Click Save.

Define the Data Mapping

A Map action named Map to WriteRecordToStage is automatically created. We'll define this data mapping.

1. Select the Map to WriteRecordToStage action.

2. Click .

   The Data Mapping page appears.

3. In the Sources section, expand CurEntry, then EmployeeNewHireFeed_Update, and then EmployeeNewHireFeed_Context.
4. In the Target section, expand NewUser, and then User.

5. Map the following fields in the Sources section to the fields with the same name in the Target section:

   • PrimaryPhoneNumber
   • PersonId
   • PersonName
   • EffectiveStartDate
   • EffectiveDate
   • WorkerType
   • PeriodType
   • PersonNumber
   • WorkEmail

   To map an element, select the element from the Sources section, then while clicking your mouse move it towards the target element. When you reach the target element the line turns green and a check mark appears.

   

6. Click Validate.

   A message confirming the mapping is valid appears.

7. Click Close.
8. Click Save.

Assign the File Reference

1. Click and from the Data section, drag Assign to the Integration canvas and place it after the writeRecordToStage activity.

   

   The Create Action dialog appears.

2. In the Name field, enter assignStageFileRef.

3. Click Create.

   The Assign page appears.

4. Click .
5. From the Variable column select $StageFileRef_assignment_1.

6. In the Value column, click .

   The Expression Builder appears.

7. In the Source section, locate the element WriteResponse located under WriteResponse, that in turn is located under $WriteRecordToStage.
8. Expand WriterResponse, then expand ICSFile, and click Load more.
9. Select FileReference.
10. Click .

11. Click Validate.

    A message confirming the expression is valid appears.

12. Click Close.

13. Click Validate.

    A message confirming the action is valid appears.

14. Click Close.
15. Click Save.

Upload the File to the FTP Server

Let's use the FTP adapter to upload the stage file to the FTP server. The FTP server represents the customer's system.

1. Using an FTP Client of your choice, log in to the FTP server.

   • FTP Server:

     Select your FTP environment to get your FTP Server.

   • FTP Port:

     Select your FTP environment to get your FTP Port.

   • Protocol:

     Select your FTP environment to get your FTP Protocol.

   • FTP User Name:

     Select your FTP environment to get your FTP Username.

   • FTP Password: Your password will be provided by the instructor.

2. If the following directory doesn't exist in the FTP server, create it:

   /upload/public_ftp//out

   Enter your User Number.

3. Go back to Oracle Integration.

4. Hover over the outgoing arrow after the for loop and click .

5. In the Search field, type FTP File.

6. Select FTP File Server.

7. Name your endpoint: WriteStageFileToFTP
8. Click Next.

9. On the Operations page, enter the following values:

   1. From the Select Operation list, select Write File.
   2. From the Select a Transfer Mode group, select ASCII.

   3. In the Output Directory field, enter:

      /upload/public_ftp//out

      Enter your User Number.

   4. In the File Name Pattern field, enter newCandidateRecord%yyyyMMddHHmmss%.csv.

      This pattern will append the year, month, date, and time to the prefix newCandidateRecord. For example, if you wrote the file on April 18^th 2018 at 08:21:00 A.M., the file name would be newCandidateRecord20180418082100.csv

10. Click Next.
11. On the Schema page, from the Do you want to specify the structure for the contents of the file? group, select No.
12. Click Next.

13. Click Next.

    A summary of the properties you configured appears.

14. Review the summary and click Done.
15. Click Save.

Define the Data Mapping

A Map action named Map to WriteStageFileToFTP is automatically created. We'll define this data mapping.

1. Select the Map to WriteStageFileToFTP action.

2. Click .

   The Data Mapping page appears.

3. In the Target section, expand ICSFile.
4. Map the $StageFileRef_assignment_1 field in the Sources section, to the FileReference field in the Target section.

5. Click Validate.

   A message confirming the mapping is valid appears.

6. Click Close.
7. Click Save.

Save the Last Run Date

The last step in the integration is to store the date and time you polled the ATOM feed. The next time this integration runs, it will use this date and time to avoid retrieving duplicated results.

1. Click and from the Data section, drag Assign to the Integration canvas and place it after the end of the Switch activity, before the Stop activity.

   

   The Create Action dialog appears.

2. In the Name field, enter assignATOMLRD.

3. Click Create.

   The Assign page appears.

4. Click .
5. From the list in the Variable column, select ATOMLastRunDateTime (Schedule Parameter).

6. In the Value column, click .

   The Expression Builder appears.

7. In the Source section, scroll down and select $ts
8. Click .

9. Click Validate.

   A message confirming the expression is valid appears.

10. Click Close.

11. Click Validate.

    A message confirming the action is valid appears.

12. Click Close.
13. Click Save.

Define the Tracking Fields

Let's configure a business identifier that will identify the integration in reports and monitoring.

1. On the Integration canvas, click , and then select Tracking.

   

   The Business Identifiers for Tracking dialog appears.

2. From the Source section, select startTime, and then click .
3. Click Save.
4. On the Integration canvas, click Save, and then click Close.

Activate the Integration

1. On the Integrations page, locate your integration and hover over it.

   The name of your integration is Directory Synchronization .

   Enter your User Number to get your unique integration name.

   When you hover over the integration, a set of actions appear in the Status column.

   
2. Click .

3. Select Enable Tracing, and then select Include Payload.

   Typically these options are disabled in production environments, but we'll enable them for the purpose of this lab.

4. Click Activate.

   The activation will complete in a few seconds. If the activation succeeds, a confirmation message appears at the top of the page, and the status will change to ● Active.

Run the Integration

1. After the status changes to active, click .

   
2. Click Submit Now.

3. In the Submit Now dialog, click Submit Now.

   

4. Click Submit.

   A confirmation message with a request ID appears.

   

5. Click the request ID link in the confirmation message

   The Track Runs page appears.

6. Click the Run ID link.

   The Track Instances page with the tracking summary for the integration appears.

7. Click the start Time link.

   This is the tracking field you configured earlier.

   

   The flow for your instance appears. The flow is colored in green to indicate that it ran successfully.

8. Click Close.
9. In the Navigation Menu, click , then click Integrations, and then click Integrations.
10. Locate your integration and click .

11. Click Submit Now.

    The Schedule Parameters page appears.

    Notice that the Current Value is updated with the date that you last ran the integration.

    
12. Click Submit.

Verify the File Was Uploaded to the FTP

1. Using an FTP Client of your choice, log in to the FTP server.

   • FTP Server:

     Select your FTP environment to get your FTP Server.

   • FTP Port:

     Select your FTP environment to get your FTP Port.

   • Protocol:

     Select your FTP environment to get your FTP Protocol.

   • FTP User Name:

     Select your FTP environment to get your FTP Username.

   • FTP Password: Your password will be provided by the instructor.
2. Browse to your directory:

   /upload/public_ftp//out

   Enter your User Number.

3. Verify that the file was uploaded to your directory.