Introduction

In our ongoing technical series on Fusion Applications Social Network Integration (FASNI), we turn our attention to capturing changes in Fusion Business Objects within Oracle Integration Cloud (OIC). This discussion explores two primary change capture strategies: Business Object events from Oracle Fusion Applications (FA) and configuring OIC for pull-based scheduled updates. In both scenarios, once changes to the designated Business Object fields are detected, the updates are pushed to the Microsoft Teams header block message, ensuring that the Teams platform consistently displays the most up-to-date information.

The event-based change capture strategy in OIC operates by responding to a general update to a Business Object within FA. It is then OIC's responsibility to discern whether the update pertains to the specific fields of interest. If the change is relevant, OIC proceeds to push this information to the associated Microsoft Teams header block message, ensuring that the communication platform mirrors the latest data.

Conversely, the pull-based method in OIC serves as an alternative to the event-based model, particularly for FA business objects that do not support event-driven change notifications. This strategy entails configuring OIC to periodically poll FA business objects for changes. It's a vital approach for ensuring data updates within Microsoft Teams when real-time event notifications are off the table.

This blog post will take you through the technical intricacies of extending and executing these strategies. The aim is to establish a FASNI framework capable of delivering as soon as possible updates or maintaining a regular cadence of data synchronization, depending on your specific requirements.

Configuration and Code Changes

While the ideal implementation of the FASNI framework in OIC aims for configuration-based setups and extensions, the reality of change capture often requires code modifications. This necessity arises from OIC's need to establish specific connections when interfacing with FA. Each call from OIC to a Business Object REST API in FA requires unique authentication through a "service user", given that these transactions are system-initiated and not tied to an individual end-user.

It's important to highlight that a single "service user" can be provisioned to interact with multiple Business Objects, assuming the proper access rights are in place. This approach can offer efficiencies in the change capture process by reducing the overhead of managing multiple service accounts.

As we venture into the change capture implementations for FASNI, we will outline the required configurations in OIC and identify the orchestrations that need to be updated or introduced. The rest of this blog post aims to equip you with the knowledge to implement the necessary code changes efficiently, ensuring that your integration responds accurately to changes within FA and communicates them effectively to Microsoft Teams.

Event-Based Change Capture

Understanding the event capabilities of FA Business Objects is a critical step in setting up event-based change capture in OIC. Not all Business Objects support change events, and even when they do, the event payload may not always include modifications to the fields we're tracking. Consequently, a preliminary investigation into the Business Object's event generation behavior is essential. As an example, the OIC ERP Adapter has specific capabilities for Oracle ERP Cloud, detailed as follows:

Oracle ERP Cloud Adapter Capabilities

After identifying the appropriate adapter, the next step is to incorporate an instance of that connection into your OIC setup, using it as the trigger in a new integration. It's imperative to understand that the specifics of configuring FA events within OIC are beyond the scope of this post. For the precise configuration steps, one should consult the existing documentation tailored to the Business Object in question.

Business Object Family

As previously discussed, configuring a connection for each Business Object with a dedicated "service user" is necessary for accessing its data within FA. FASNI's implementation in OIC utilizes a strategy where a Business Object's "family type" correlates to a specific OIC connection. For instance, the object type 'SALES.OPPORTUNITY' combines a "family type" ('SALES') with an "object type" ('OPPORTUNITY'). In practice, a single connection is employed for all Business Objects within the 'SALES' family, streamlining calls to FA.

This correlation flow can be found in the "Get Object JSON String" integration. Currently, the FASNI framework in OIC supports the following "family types":

• CONTRACTMANAGEMENT
• GENERALACCOUNTING
• JOURNALACCOUNTING
• ORDERMANAGEMENT
• PAYABLES
• PROCUREMENT
• PRODUCTMANAGEMENT
• RECEIVABLES
• SALES
• SUPPLYCHAINEXECUTION

The critical point to understand is that if you encounter a new or unsupported "family type" while working with a Business Object, the "Get Object JSON String" integration requires an update. This involves adding a new branch to the switch statement within the integration and replicating the activities from an existing branch for your new "family type". Ensuring the outbound call to FA utilizes the correct OIC connection is key. Any oversight here would result in the default action of the switch statement, which is to stop the flow, leading to missed updates.

Integration Pattern

In the context of event-based change capture with a new OIC integration, the workflow following the configuration of your FA event connection tends to be straightforward. To best understand this pattern, let's examine an existing integration flow for Sales Opportunity events:

The flow contains several components structured as follows:

1. Scope Main Activities
   • Incorporate Fault Handlers for any errors that occur during the two main integration calls.
   • These handlers are set to terminate the flow (Stop Action) in case of faults.

2. Conversation Check
   • Begin by checking for an existing conversation through the retrieval of the Visual Builder Object from the database.
   • If no conversation is found, the flow ends via the Fault Handler.
   • Integration: VB Object CRUD
   • Operation: getChannelByObject

3. Update Channel Header Block Message
   • Upon successfully retrieving a row for the Visual Builder Object, the integration to update the Microsoft Teams header block message is invoked.
   • Errors in this invocation are managed by the Fault Handler, which will terminate the flow.
   • Integration: MS Teams Channels
   • Operation: updateHeaderBlock

After setting up your orchestration to mirror the SALES_OPPORTUNITY Events pattern, activation of the integration is the final step. No further configuration in OIC is necessary. To verify the setup, you can perform a modification to your FA Business Object through the Fusion console. A successful integration will reflect these changes in the Microsoft Teams header block message.

Pull-Based Change Capture

When event-based change capture is not an option for a Business Object, the pull-based method becomes our go-to solution within OIC. This approach hinges on the data available from the FA REST API. Specifically, we look for "LastUpdateDate" and "LastUpdatedBy" fields; their presence typically indicates suitability for pull-based change capture.

If your Business Object has these fields, setting up pull-based change capture involves several key steps:

1. OIC Lookups
   • Set up OIC Lookups that are pertinent to your Business Object. This will ensure that the integration can correctly interpret and handle the Business Object data.
2. Pull Updates From Fusion Integration
   • Add a branch in a switch statement for your Business Object.
3. OIC REST Connection
   • Establish a connection using an FA "service user" with the necessary permissions to access the Business Object data.
4. Scheduled OIC Integration
   • Configure a scheduled integration within OIC that periodically invokes the "Pull Updates From Fusion" integration, specifying your Business Object type (for example, 'SALES.OPPORTUNITY').
5. OIC Library Function Updates
   • Depending on your requirements, you may need to update the "getCommonObjects" library function in OIC to accommodate the new Business Object.

These components collectively form the backbone of the pull-based change capture mechanism. Each will be explained in further detail throughout this section. Although this may appear to be a complex setup at first, the design intent is to minimize code changes and streamline the process as much as possible. This approach allows for a more configuration-driven method, aligning with our overarching goal to enhance maintainability and scalability within the FASNI framework.

OIC Lookups

OIC Lookups are integral to the operation of pull-based change capture. If these configurations are not in place, the integration will stop when it detects the missing Lookups. There are two essential Lookups to configure:

1. FAMILY.TYPE.Pull.Endpoint
   • This Lookup specifies the FA REST API endpoint that retrieves a list of object type IDs within a certain timeframe.
   • The endpoint usually resembles the Authz.Endpoint Lookup but is modified to utilize the 'q' parameter for querying.
   • The 'q' parameter constructs a query using LastUpdateDate>{FROM_DATE}.
   • Both the {FROM_DATE} and {OFFSET} placeholders are mandatory and are dynamically substituted during the pull process.
2. FAMILY.TYPE.Pull.ObjectId
   • This Lookup defines the field name for the object type ID, essential for uniquely identifying an object instance.
   • While it is typically a single field name, certain objects have complex IDs necessitating multiple comma-separated field names.

Here’s an example for the CONTRACTMANAGEMENT.CONTRACT object type, illustrating a complex ID requiring multiple fields:

CONTRACTMANAGEMENT.CONTRACT.Pull.Endpoint,/fscmRestApi/resources/11.13.18.05/contracts?onlyData=true&q=LastUpdateDate>{FROM_DATE}&limit=500&offset={OFFSET}

CONTRACTMANAGEMENT.CONTRACT.Pull.ObjectId,"Id,MajorVersion"

As seen in the example, multiple fields are specified for complex IDs. However, it's important to note that most Business Object IDs comprise a single field.

Pull Updates From Fusion Integration

Much like the event-based implementation, the pull-based flow in OIC utilizes a strategy where a Business Object's "family type" correlates to a specific OIC REST connection. For instance, the object type CONTRACTMANAGEMENT.CONTRACT' combines a "family type" ('CONTRACTMANAGEMENT') with an "object type" ('CONTRACT'). In practice, a single connection is employed for all Business Objects within the 'CONTRACTMANAGEMENT' family, streamlining calls to FA.

This correlation flow can be found in the "Pull Updates From Fusion" integration and "GetBusinessObjectUpdates" scope. Currently, the FASNI framework in OIC supports the following "family types":

• PROCUREMENT
• CONTRACTMANAGEMENT

The critical point to understand is that if you encounter a new or unsupported "family type" while working with a Business Object, the "Pull Updates From Fusion" integration requires an update. This involves adding a new branch to the switch statement within the integration and replicating the activities from an existing branch for your new "family type". Ensuring the outbound call to FA utilizes the correct OIC connection is key. Any oversight here would result in the default action of the switch statement, which is to stop the flow, leading to missed updates.

OIC REST Connection

A recurring theme in this blog post is the necessity of an OIC connection, configured with an appropriate "service user", to support change capture workflows. For pull-based change capture, this means an OIC REST connection that facilitates the retrieval of data from FA for your Business Object. The FASNI implementation within OIC is equipped with four REST connections to cover a wide range of Business Objects:

1. PRC_IMPL REST - Social Integration
2. CRM_IMPL REST - Social Integration
3. FIN_IMPL REST - Social Integration
4. SCM_IMPL REST - Social Integration

These predefined connections can be utilized, or you may opt to configure a new one specific to your needs. While configuring OIC REST connections is outside the scope of this blog post, existing documentation should be your guide for the setup process (Create Connections). Additionally, examining the configuration of the existing predefined connections can provide valuable insights into their setup and usage.

Scheduled OIC Integration

For pull-based change capture, while manual initiation is possible through tools like the OIC test harness, Postman, or curl, automating this process is more efficient. Utilizing OIC's scheduling feature allows for automatic and periodic triggering of the 'Pull Updates From Fusion' integration.

The creation of a scheduled integration is a process documented elsewhere (Create Scheduled Integrations). Hence, we won't duplicate those instructions here. Instead, we focus on the practical application of these schedules at the Business Object level within FASNI. This granular approach permits tailored control over how often each Business Object is checked for updates. However, there’s no reason why you cannot leverage a more course-grained approach where multiple Business Object pull requests are grouped together in one scheduled integration.

Here's a high-level overview of the flow for a scheduled pull-based change capture:

Once you have mirrored the above flow in your scheduled integration, activation and initiation of the schedule are straightforward processes. However, the correct configuration of OIC Lookups is crucial before this activation. If these Lookups are not properly set, the integration will identify the misconfiguration and halt the flow. Ensuring that these Lookups are accurately configured is a pivotal step, as it directly influences the success and reliability of the updates to your Microsoft Teams header block message with the latest changes.

OIC Library Function Updates

The logic for pull-based change capture in OIC requires a comparison between the list of Business Object IDs in the Visual Builder database and the changes within FA. The aim is to compile a list of Business Object IDs that have undergone changes and have associated conversations, which is used to trigger updates to the Microsoft Teams header block message.

This comparison, essentially finding the union of the two datasets, is performed by a JavaScript function within OIC named "getCommonObjects". The function is preconfigured to handle the payload structures of all known pull-based update Business Object types. However, when introducing a new Business Object with a structure not previously accounted for, adjustments to "getCommonObjects" may be necessary.

To update this function, developers should use their preferred code editor and thoroughly test the changes locally before implementing them into the OIC library. It's crucial to ensure that the function can accurately process the new payload format of the Business Object in question.

You'll find "getCommonObjects" utilized in the 'Pull Updates From Fusion' integration, specifically within the 'SetupForUpdateLoop' Assign activity. It's here that the function plays a pivotal role, and any modifications must be meticulously verified to maintain the integrity of the integration process.

Testing

Validating the setup of your pull-based change capture integration is a critical step. Begin by updating the Business Object instance via the FA console.

First Method: Direct Testing of the Integration

To test the "Pull Updates From Fusion" integration directly, bypassing the scheduled flow, you can use tools such as the OIC test harness, Postman, or curl. This method is executed as a PATCH request with the following sample payload:

{
 "objectType": "CONTRACTMANAGEMENT.CONTRACT"
}

The OIC test harness is preferable for its comprehensive tracing and debugging capabilities. If you opt for another tool, remember that you'll need to toggle between that and the OIC console for monitoring purposes.

Here's what the OIC test harness looks like:

Second Method: Scheduled Integration Testing

Alternatively, you can activate the schedule for the integration and then perform updates in the FA console. To monitor the integration:

1. Navigate to the 'Monitor Integrations' section in the OIC console.
2. Wait for the scheduler to initiate the "Pull Updates From Fusion" integration.
3. Once initiated, monitor the integration's progress and completion.

Following the completion of the "Pull Updates From Fusion" integration, inspect the OIC instance details and the Microsoft Teams conversation for confirmation that the updates have been successfully applied to the header block message.

Conclusion

In conclusion, this blog post has walked you through the process of setting up both event-based and pull-based change capture in OIC for new business object types from Fusion Applications. By following the detailed steps for configuring REST connections, leveraging OIC Lookups, updating library functions, and conducting thorough testing, you should be well-equipped to ensure that updates are seamlessly reflected in your Microsoft Teams header block messages. I hope this guide proves to be a valuable resource in fulfilling your change capture integration requirements.