Subscribe to Atom Feeds in a Scheduled Integration

This use case provides an overview of creating a scheduled orchestrated integration using the Oracle HCM Cloud Adapter to subscribe to Atom feeds. Atom feeds enable you to track changes made to feed-enabled resources in Oracle Global Human Resources Cloud. For any updates of interest to downstream applications such as new hires, terminations, employee transfers, and promotions, Oracle Global Human Resources Cloud publishes Atom feeds. For this use case, the Oracle HCM Cloud Adapter is configured with the Atom feed Employee Update. This feed consists of three updates (PrimaryPhoneNumber, CitizenshipStatus, and CitizenshipId). An FTP Adapter is also configured to write any feed updates to an FTP server.

There are two types of entries published by Oracle Global Human Resources Cloud in any feed:
  • Entries that are already effective.
  • Entries that are effective in the future (known as future dated entries).
Design the integration based on these requirements. If the integration must process future dated entries, there are the following options:
  • Future dated entries are processed on their effective dates.
  • Future dated entries are processed immediately.

Process Future Dated Entries on Their Effective Dates

Oracle Global Human Resources Cloud processes future dated entries on their effective dates. This use case provides an overview of how to design this type of integration.

  1. On the Connections page, create and configure an Oracle HCM Cloud Adapter with the following details:
    1. Specify a name.
    2. In the Configure Connectivity dialog, specify both a service catalog WSDL URL and an interface catalog URL. If the interface catalog URL is not specified, the Subscribe to Updates (via Atom Feed) option is not displayed on the Actions page of the Adapter Endpoint Configuration Wizard.
    3. In the Credentials dialog, select the Username Password Token security policy and specify the login credentials.
  2. On the Integrations page, create a scheduled orchestrated integration.
  3. Drag the Oracle HCM Cloud Adapter into the integration canvas as an invoke connection and configure the Adapter Endpoint Configuration Wizard with the following details:
    1. On the Basic Info page, specify a name (for this example, getData).
    2. On the Actions page, select Subscribe to Updates (via Atom Feed).
    3. On the Operations page, select the following:
      • From the Atom feed list, select Employee Update.

      • Select the Include Business Object in Atom Feeds checkbox to send an HTTP request for each entry in the feed to the Atom server to fetch the latest snapshot of the business resource. The checkbox behavior is as follows:

        • Not selected: Context and changed attributes are used during design time and runtime. The operation name in the mapper does not have the suffix WithBO and the business object is not shown under the operation name element.

        • Selected: Both context attributes and business object attributes are used during design time and runtime. The operation name in the mapper has the suffix WithBO.

      • Select the maximum number of entries to process from the Max entries to process list.

        This sets the value of the page-size query parameter that is sent as part of the request to the Atom server to get the feed. The Atom feed size is limited by this number. The recommendation is to use a small number for this option and have the integration execute more frequently.

  4. Double-click the schedule icon, and select Edit to create a schedule parameter (for this example, named ts). The initial value must be a timestamp to which to start. Entries are received during runtime from this timestamp onwards. The timestamp must be of following format:
    YYYY-MM-DDTHH:MM:SS:sssZ e.g. 2018-06-03T02:34:06.000Z

    where:

    • YYYY: Four-digit year
    • MM: Two-digit month (01=January, and so on)
    • DD: Two-digit day of the month (01 through 31)
    • hh: Two digits of the hour (00 through 23) (am/pm NOT allowed)
    • mm: Two digits of the minute (00 through 59)
    • ss: Two digits of the second (00 through 59)
    • s: Three digits representing a decimal fraction of a second (that is, milliseconds)
    This parameter ensures that new entries are processed every time the integration is invoked. The timestamp of the last processed entry must be stored in this parameter. This value is available across invocations of the integration. For the first request, the updated-min query parameter value is blank, which returns the latest n number of entries in the feed, where n is the value selected for the Max entries to process option on the Operations page.

  5. In the request mapper between the schedule and the Oracle HCM Cloud Adapter, map $ts (timestamp value) to updated-min. The Oracle HCM Cloud Adapter sends the updated-min query parameter to the Atom server when requesting a feed. The Atom server returns a feed with updated entries occurring after newer updates to the timestamp value. This enables new updates to be processed every time and prevents the same update from being processed multiple times.
  6. Add and configure a For Each action below the Oracle HCM Cloud Adapter in the integration canvas.
    Because the Include Business Object in Atom Feeds option was selected on the Operations Page, the mapper shows the business object (Emps), the context (EmployeeUpdateFeedWithBO_Context), the changed attributes (ChangedAttributes), and the timestamp. The timestamp is the updated element from the feed's entry. This is used to track processed entries. This is done with the help of the schedule parameter. The first For Each action iterates through the entries as follows.
    Description of hcm_foreach1.png follows
    Description of the illustration hcm_foreach1.png
  7. Add and configure a second For Each action inside the first For Each action to iterate through the changed attributes.
  8. Add and configure an FTP Adapter inside the second For Each action in the integration.
    For each changed attribute, a file is written to the FTP server. You can also use a REST Adapter connection to send multiple patch requests to an endpoint with these changes.
    Description of hcm_mapper1.png follows
    Description of the illustration hcm_mapper1.png

    At the end of the first loop (for this example, named loop1), the ts schedule parameter is updated with the timestamp of the entry. This is stored in the database and available for subsequent invokes. This value is persisted across subsequent integration runs and also across deactivations and activations. This is how the processed entries are tracked. Because the ts schedule parameter is used in the request mapping, in subsequent invokes it uses its value from the database. Therefore, only new entries are processed.

  9. Add an Assign action at the bottom of the first For Each action (loop1). The assign activity is placed at the end of loop1 for fault tolerance. If a fault occurs when writing to the FTP location, the updated timestamp of the last processed entry is used for the next invoke. Description of hcm_assign.png follows
    Description of the illustration hcm_assign.png

    The updated_timestamp element is selected from the update element (entry in the feed) as the value for schedule parameter ts as follows.


    Description of hcm_mapper2.png follows
    Description of the illustration hcm_mapper2.png

    When the integration is invoked by the schedule, a file is created in the FTP directory for each of the changed attributes. The complete design of the integration is as follows:
    Description of hcm_summary.png follows
    Description of the illustration hcm_summary.png

Process Future Dated Entries Immediately

Oracle Global Human Resources Cloud processes future dated entries immediately, as soon as they are published. This use case provides an overview of the differences between designing an integration to process future dated entries on their effective dates and designing an integration to process future dated entries immediately.

  • On the Operations page, select Process Future Dated Entries Immediately. Enabling this checkbox changes the request map to have a different query parameter, published-min.
  • In the request mapper between the schedule and the Oracle HCM Cloud Adapter, map $ts (timestamp value) to published-min.

  • To make future dated entries available immediately in the feed, you must send published_timestamp as published-min in the request. published_timestamp must also be persisted in the ts scheduled parameter to process new entries in subsequent invokes of the flow. ts must store the published_timestamp as follows.

Summary

In summary, the following changes are required in the integration for handling future dated entries.

Future Dated Entries Options Request Parameters Mapper View Timestamp Stored in Schedule Parameter
Processed immediately published-min
published-min in mapper view
published_timestamp
Processed on their effective dates updated-min
updated-min in mapper view
updated_timestamp