Introduction

In this installment of our technical series on the Fusion Applications Social Network Integration (FASNI) sample, we're focusing on adding a new Oracle Fusion Applications (FA) business object into Oracle Integration Cloud (OIC). This post serves as a detailed guide for developers working on OIC, aiming to expand FASNI's capabilities through hands-on integration techniques. We will explore the technical steps required to integrate new FA business objects into the OIC environment successfully.

OIC as a Conduit for FASNI API Implementation

OIC's function in the FASNI sample is to implement the FASNI API, which is designed independently of any social platform. The API establishes a standard interface for communication between the Fusion Applications UI and the integration layer. Specifically for Microsoft Teams, OIC adapts the FASNI API, facilitating data exchange and function invocation consistent with the FASNI design principles.

OIC's support for RESTful services and JSON payloads aligns with the requirements of the FASNI API. It also has capabilities for authenticating and interfacing with Microsoft Graph APIs via OAuth, a necessary component for Microsoft Teams integration. Beyond this, OIC is equipped to manage Fusion Applications eventing, an essential feature for monitoring and reacting to changes in FA business objects. For a more in-depth look at event handling within FASNI, see the designated blog post [Link Coming Soon].

Prerequisites For FA Business Object

Introducing a new FA business object with Oracle Integration Cloud begins with several foundational requirements. First, a JSON Web Token (JWT) is essential for secure communication between OIC and FA. This token is passed from the client application to OIC via a custom HTTP header. The JWT serves as a means of authentication and authorization when interacting with the Fusion Applications system, ensuring the data exchange is secure and trusted.

Next, we must establish an explicit identifier for the FA business object. This is achieved by concatenating the object's family and type, separated by a dot. For example, working with an opportunity object within the sales family would be denoted as 'SALES.OPPORTUNITY'. This precise notation is crucial for OIC to accurately identify and interact with the correct FA business object. This concatenated string is the base for all business object-specific configurations in OIC Lookups (see Configure via OIC Lookups vs. Coding). When integrating a new object, it’s essential for Visual Builder Cloud Service (VBCS)/Fusion developers to collaborate with OIC developers to decide on the precise composition of this identifier.

An object instance ID is also required for each specific entity within FA. This unique identifier is the key to accessing a business object's various fields and values. The ID is injected into the FA REST endpoint to guarantee correct data retrieval.

Finally, the integration process is designed to be efficient, ideally involving a single FA REST API call to retrieve the complete details of an object instance. If necessary, it is technically possible to make a secondary call to retrieve the full set of desired fields and values. However, it’s a best practice to identify an FA API capable of retrieving the data simultaneously.

These prerequisites are non-negotiable and the first three are enforced by the FASNI API for a seamless and effective integration between FA business objects, OIC, and Microsoft Teams, setting the stage for a robust and reliable implementation.

For your new FA business object, identify the following before moving to the next section:

1. Object Type (e.g., SALES.OPPORTUNITY ... will come from Fusion UI)
2. Object ID (e.g., OptyNumber ... will come from Fusion UI)
3. FA REST API (e.g., /crmRestApi/resources/11.13.18.05/opportunities/{OptyNumber})
4. Object Fields (e.g., OptyId,OptyNumber,Name,StatusCode,SalesStage,etc.)
5. If necessary, child FA REST API and fields
6. If necessary, any special handling for business object fields/values

Configure via OIC Lookups vs. Coding

In adding a new FA business object with OIC, Lookups are crucial in defining configuration values that dictate how data is retrieved and presented. The Lookups act as parameters that guide the construction of FA REST API calls, specifying which fields and values need to be retrieved in a JSON structure. These configurations are essential for ensuring that the API fetches the right data that will be the focus of the discussion in Microsoft Teams.

Beyond data retrieval, Lookups are also utilized to formulate the naming of channels. This is achieved by applying string templates incorporating field values from the FA business object, resulting in a channel name reflecting the context of the ensuing conversation.

Furthermore, Lookups also play a pivotal role in constructing header block messages for communications and notifications. These messages combine predefined string templates with values extracted from the business object fields. This process creates descriptive messages that convey essential information, facilitating discussions or actions related to the business object. Utilizing this templating strategy greatly reduces the need for hardcoded formatting within the integrations. It externalizes the presentation logic, thereby simplifying maintenance and potentially eliminating the need for code modifications when changes to message format are required.

Using Lookups in OIC streamlines the FA business object maintenance process, ensuring that changes to how FA business objects are handled or displayed don't necessitate a complete overhaul of the underlying code. This setup is particularly handy for the maintainers who need to tweak the data representation or API interactions without digging into the nuts and bolts each time. It's about keeping the integration adaptable and the code clean, ensuring updates or maintenance don't become a major coding exercise.

All of the OIC Lookups for the FASNI example can be found in the OIC console under Social_Integration:

Top of Form

Bottom of Form

Base Lookups Extensions

In the realm of OIC, Lookups provide the foundation for dynamically retrieving and managing the specific details of each FA business object. These Lookups are distinguished by a naming convention that combines the Object Type (refer to Prerequisites For FA Business Object) with a unique suffix. The dynamic nature of these Lookups allows for flexible and precise data retrieval tailored to each object.

For any given FA business object, there are four primary Lookups to define:

Authz.Endpoint

This Lookup specifies the REST API endpoint associated with the business object. It's constructed with a specific placeholder, {OBJECT_ID}, which is designed to be substituted with the actual ID of the business object.

Example:

/crmRestApi/resources/11.13.18.05/opportunities/{OBJECT_ID}?onlyData=true

During runtime, OIC will replace {OBJECT_ID} with the relevant business object's ID, and prepend the base URL from the FA.Host Lookup to form the complete endpoint for the API call. This ensures that the integration points precisely to the correct FA API and object instance.

Fields

This Lookup defines the specific fields from the FA business object that the integration needs to access. By listing the required fields in a comma-separated format, you can tailor the API call to retrieve only the most relevant data for the conversation or processing task at hand. This targeted approach not only streamlines the data retrieval process but also optimizes the performance of the integration by avoiding unnecessary data transfer. It's particularly useful when additional fields are needed for subsequent operations like secondary API calls or updates, as these can also be included in the list.

Furthermore, the field values specified in this Lookup are instrumental beyond data retrieval; they are integral to constructing other essential components within the FASNI sample. For instance, a unique field from this list is often used to dynamically generate the social channel's name, ensuring that each channel can be distinctly identified. In addition, these values are collectively used to assemble the header block message, which serves as the contextual introduction in the conversation interface.

Example:

OptyId,OptyNumber,Name,StatusCode,SalesStage,UpsideAmount,CurrencyCode,WinProb,Revenue,LastUpdateDate,LastUpdatedBy

This list is then concatenated to the Authz.Endpoint URL, constructing the full request endpoint. For example, the complete endpoint URL for retrieving opportunity information might appear as:

https://faexample.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/280836?onlyData=true&fields=OptyId,OptyNumber,Name,StatusCode,SalesStage,UpsideAmount,CurrencyCode,WinProb,LastUpdateDate,LastUpdatedBy

ChannelName

This Lookup is designed to dynamically generate the names of social channels in a way that is relevant to the context of the data being used. This is done through a string template that includes placeholders, which are substituted with actual data pulled from the fields of the business object. The result is a channel name that is descriptive and specific to the data.

Example:

Sales Opportunity-{OptyNumber}

In the example above, {OptyNumber} is a template placeholder. This placeholder will be replaced with the actual opportunity number from the data, sourced from the business object's JSON payload. It's essential to ensure that the field used as a placeholder, in this case, OptyNumber, is listed in the Fields Lookup, as this is what the integration will reference to replace the placeholder with the corresponding value.

It is important to understand for Microsoft Teams channel names, there are specific limits and restrictions regarding both the length and the characters that can be used:

1. Length Limit: The maximum length for a Microsoft Teams channel name is 50 characters.
2. Invalid Characters: Channel names in Microsoft Teams cannot contain the following characters or words:
   • Characters such as: ~ # % & * { } + / \ : < > ? | ' " , and two consecutive dots (..).
   • Characters in the ASCII ranges 0 to 1F and 80 to 9F.
   • Specific words like: forms, CON, CONIN$, CONOUT$, PRN, AUX, NUL, COM1 to COM9, LPT1 to LPT9, desktop.ini, and vti.
   • Channel names also cannot start with an underscore (_) or a period (.), nor can they end with a period (.)​​.

These limitations are designed to ensure compatibility and functionality within the Microsoft Teams environment and the broader Microsoft 365 ecosystem.

AdaptiveCardTemplate

This is the first of two types of header block message templates. For Microsoft Teams look and feel, and what comes with the FASNI sample, this is the preferred and recommended type. Specific to Microsoft Teams, this template defines the structure of an Adaptive Card used for the header block message. Adaptive Cards allow for rich, interactive content in Teams, and the template sets up the card format to be filled with object data.

Example Adaptive Card (MESSAGES.AdaptiveCardTemplate in OIC Lookups):

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "Container",
      "style": "emphasis",
      "items": [
        {
          "type": "TextBlock",
          "horizontalAlignment": "Left",
          "color": "Dark",
          "text": "{OBJECT_TITLE}",
          "wrap": true,
          "size": "ExtraLarge",
          "weight": "Bolder"
        }
      ],
      "padding": "Default",
      "spacing": "None"
    },
    {
      "type": "Container",
      "separator": true,
      "style": "accent",
      "items": [
        {
          "type": "TextBlock",
          "size": "Large",
          "weight": "Bolder",
          "color": "Dark",
          "text": "{OBJECT_HEADER}",
          "wrap": true,
          "style": "heading"
        },
        {
          "type": "Container",
          "padding": "None",
          "items": [
            {
              "type": "FactSet",
              "facts": {OBJECT_FIELDS_ARRAY}
            }
          ]
        }
      ],
      "padding": "Default",
      "spacing": "None"
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.2",
  "padding": "None"
}

Example Object Details (FAMILY.TYPE.AdaptiveCardTemplate in OIC Lookups):

{
  "objectTitle": "Opportunity Summary",
  "objectHeader": { "Name": "Name" },
  "fields": [
    {
      "Sales Stage:": "SalesStage"
    },
    {
      "Status:": "StatusCode"
    },
    {
      "Amount:": "Revenue CurrencyCode"
    },
    {
      "Win Probability:": "WinProb"
    }
  ]
}

In the examples above, we have an Adaptive Card structure and the JSON structure containing business object field names that will be replaced with their corresponding values, sourced from the business object's JSON payload. Since Adaptive Cards are simply a JSON structure, the label for the field is the JSON key and the corresponding value is the business object field name. So the list of business object fields above are: Name,SalesStage,StatusCode,Revenue,CurrencyCode,WinProb. It's essential to ensure that these fields are listed in the Fields Lookup, as this is what the integration will reference to replace the placeholder with the corresponding values.

To construct a complete Adaptive Card for use in a Microsoft Teams conversation, the relevant object details are integrated into the predefined Adaptive Card template. Specifically, the 'objectTitle', 'objectHeader', and 'fields' from the object details are inserted in place of the placeholder strings enclosed in curly braces within the template. Each placeholder is replaced with its corresponding value from the object details, thereby customizing the card with specific information for display.

The example has been formatted for readability, but when saved in the OIC Lookups it should be compacted into a single line. There are online sites that provide this capability (e.g., https://jsonformatter.org/).

If you want to develop a different Adaptive Card template, you can explore the editor hosted by Microsoft: https://www.adaptivecards.io/designer/. Remember to update the fillAdaptiveCard OIC Libraries function to accommodate your new template.

MessageTemplate

This is the second of two types of header block message templates, and it is being documented here for completeness. It's important to note that it should not be used in conjunction with the AdaptiveCardTemplate since these templates are mutually exclusive; you should configure the MessageTemplate only if you are not using the AdaptiveCardTemplate. Including both Lookups within the same configuration is not recommended, as they serve similar purposes but are tailored for different presentation contexts.

It is an HTML string template used for constructing the header block message. This template should be crafted to define the HTML structure of the message, which will be populated with data from the business object. To avoid strange behavior with the HTML rendering, only use single quotes (') in the HTML and avoid double quotes (").

Example:

<table style=border-collapse:collapse;border:1px solid #ddd'><tbody><tr><th colspan='2' style='padding:10px;text-align:center'>Opportunity<br>{Name}</th></tr><tr><td style='padding:5px'><strong>Status</strong></td><td style='padding:5px'><strong>Sales Stage</strong></td></tr><tr><td style='padding:5px'>{StatusCode}</td><td style='padding:5px'>{SalesStage}</td></tr><tr style='height:15px'></tr><tr><td style='padding:5px'><strong>Amount</strong></td><td style='padding:5px'><strong>Win Probability</strong></td></tr><tr><td style='padding:5px'>{UpsideAmount}</td><td style='padding:5px'>{WinProb}</td></tr></tbody></table>

In the example above, multiple placeholders are represented by business object field names in curly braces {}. These placeholders will be replaced with the corresponding values of the business object data, sourced from the business object's JSON payload. It's essential to ensure that these fields are listed in the Fields Lookup, as this is what the integration will reference to replace the placeholder with the corresponding values.

A View From OIC

Secondary Call Extensions

When an FA business object’s data cannot be retrieved with a single API call, it may be necessary to couple the first API call with a second to retrieve all the desired fields. The following two Lookups are very much like the Authz.Endpoint and Fields (detailed above), but with a twist: the Child.Endpoint can contain placeholders for values retrieved from the Authz.Endpoint call.

Child.Endpoint

This Lookup defines the REST API endpoint for secondary data associated with the business object. It includes a placeholder within the endpoint that will be replaced with the actual value of the fields retrieved with the Authz.Endpoint call.

Example:

/fscmRestApi/resources/11.13.18.05/purchaseRequisitions/{RequisitionHeaderId}/child/summaryAttributes?onlyData=true&finder=DeliveryAndAmountSummaryFinder

In the example above, {RequisitionHeaderId} is a dynamic placeholder that will be substituted with the unique identifier of the requisition, enabling OIC to retrieve specific summary attributes related to that requisition. Just like with the Authz.Endpoint, the OIC integration will prepend the base URL from the FA.Host Lookup to form the complete endpoint for the API call. This ensures that the integration points precisely to the correct FA API and object instance.

Child.Fields

This Lookup defines the specific fields from the FA business object’s secondary call that the integration needs to access. The details are like the Fields Lookup in the Base Lookups Extensions section.

Example:

RequisitionTotalAmount,RequisitionNonRecoverableTaxAmount,RequisitionApprovalAmount

A View From OIC

Special Lookups Extensions

QueryFields

This Lookup is a precision tool used when you need to filter and retrieve specific data from a JSON structure based on certain criteria. It is particularly useful for scenarios where the data of interest is only a subset of a larger set, identifiable by specific conditions.

Example:

Amount:AccountClass=Receivable

The example above pairs the target field "Amount" with a query that filters the results based on the condition specified after the colon. To better understand how the query works, we will reference the following JSON snippet:

  "receivablesInvoiceDistributions": [
    {
      "AccountClass": "Tax",
      "Amount": 480
    },
    {
      "AccountClass": "Revenue",
      "Amount": 16000
    },
    {
      "AccountClass": "Tax",
      "Amount": 1040
    },
    {
      "AccountClass": "Tax",
      "Amount": 0
    },
    {
      "AccountClass": "Receivable",
      "Amount": 17520
    },
    {
      "AccountClass": "Rounding Distribution",
      "Amount": 0
    }
  ]

In the above JSON (from Receivables Invoice), we are interested in extracting the "Amount" value only when the "AccountClass" equals "Receivable". The QueryFields Lookup directs an Oracle Integration Cloud JavaScript library function to sift through the JSON payload and dynamically retrieve the amount where the account class is "Receivable". The function will parse the JSON and return the value 17520 from the distribution where "AccountClass" matches "Receivable".

This dynamic querying capability of QueryFields can be applied to other business objects that share a similar data retrieval pattern, simplifying the process of extracting precise data points based on given criteria.

A View From OIC

CalculatedFields

This Lookup is unique in that it necessitates direct intervention in the form of JavaScript coding within OIC. This Lookup is used when the value of a field is not simply retrieved from the FA business object but instead must be derived through a calculation. For scenarios involving multiple computations, the Lookup can accommodate several fields, each separated by a comma, enabling a single Lookup entry to manage numerous calculated values per business object.

Example:

TransferPrice

The example above is for Supply Chain Transfer Orders, where the transfer price cannot be directly fetched but is instead calculated by multiplying RequestedQuantity by UnitPrice. Such calculations are not hard-coded within the integration flow. Instead, they're encapsulated within the OIC Libraries. This abstraction of the calculation logic to the library level offers a significant advantage: updates to the calculation can be made by simply modifying the OIC Library, then deactivating and reactivating the Conversation Gate integration. This avoids the more cumbersome process of entirely deploying a new version of the Conversation Gate.

When you need to incorporate additional logic for calculated fields, you would typically adjust the calculateObjectValue function, which has the signature calculateObjectValue(objectType, objectJSONString, fieldToCalculate). For those looking to implement or modify such logic, reviewing the existing JavaScript library is advisable to understand the current calculation workflow and how best to introduce new logic.

A View From OIC

Code When Only Necessary

In most cases, OIC’s design and framework facilitate the integration of FA business objects through configuration, specifically using Lookups. However, there might be exceptions where the out-of-the-box capabilities of OIC do not suffice for your new business object. In such situations, custom coding within OIC becomes necessary, particularly within two integrations: the Conversation Gate and the MS Teams Message Utils.

Conversation Gate

The Conversation Gate plays a dual role in the integration process:

1. User Access Validation: It confirms whether the requesting user has the permissions to access the business object. This is done by successfully calling the FA REST API, constructed with the business object type and ID. The details of this process, including any special handling required for other business objects, can be found in the CheckFusionAccess scope of the integration.
2. JSON Response Generation: For standard objects, the integration simply returns the API response as a JSON string. However, there is an AddCalculatedFields scope that comes into action when calculated fields need to be appended to the REST response post-retrieval, as indicated in the Lookups section.

MS Teams Message Utils

This integration handles various message-related operations within Microsoft Teams. One key operation, getFieldValues, formats the business object results into a "canonical" representation of key/value pairs, easing the management of channels, messaging, and business object update workflows. Should your new business object necessitate unique result handling, modifications to this operation are likely required to accommodate such requirements.

OIC Libraries (SocialIntegration)

The FASNI OIC framework significantly benefits from using JSON strings to handle business object data. While OIC's default toolset may have direct JSON string manipulation limitations, OIC Libraries provide a robust workaround. The integration process becomes more powerful and flexible through custom functions available in OIC Libraries.

These libraries have been employed for various tasks within the FASNI sample. They enable the extraction of fields from JSON Web Tokens (JWT), such as user IDs, and support the generation of channel names. Additionally, they facilitate the computation and formatting of fields, the integration of data with Microsoft Teams Adaptive Card templates, and the construction of dynamic payloads, among other uses.

To truly understand and leverage the SocialIntegration library’s capabilities, export the library, extract its contents, and review the available functions and their implementations.

Verification

Validating the configuration and implementation of your new FA business object involves several steps, largely due to the necessity of a valid JSON Web Token (JWT) and the need to reference specific data within your FA instance. To conduct a thorough verification, you should have:

1. A valid JWT for your Fusion Instance
2. A configured business object type (e.g., SALES.OPPORTUNITY)
3. A valid business object ID for the object type

With these in hand, you can utilize the getFieldValues operation in the MS Teams Message Utils integration, which can be executed using tools like Postman or curl. This operation will test the critical touchpoints of your integration.

Here's a curl command template tailored for your FA business object:

curl --location 'https://YOUR_OIC_HOST/ic/api/integration/v1/flows/rest/MS_TEAMS_MESSAGE_UTILS/1.0/messages/fieldValues' \
--header 'jwt: YOUR_FA_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YOUR_OIC_BASE64_ENCODED_CREDENTIALS' \
--data-raw '{
    "objectType": "YOUR.OBJECT_TYPE",
    "objectId": "YOUR_OBJECT_ID",
    "objectJSONString": ""
}

Replace YOUR_OIC_HOST, YOUR_FA_JWT_TOKEN, YOUR_OIC_BASE64_ENCODED_CREDENTIALS, YOUR.OBJECT_TYPE, and YOUR_OBJECT_ID with your actual credentials and data. A successful response will return the field details for the object in JSON format.

If it is successful, you will get results like the following (this is from a SALES.OPPORTUNITY call):

{
  "fieldDetails" : "{\"OptyId\" : \"3000003149\",\"OptyNumber\" : \"276842\",\"Name\" : \"Example Opportunity\",\"StatusCode\" : \"OPEN\",\"SalesStage\" : \"01 - Qualification\",\"UpsideAmount\" : \"0\",\"CurrencyCode\" : \"USD\",\"WinProb\" : \"10\",\"Revenue\" : \"0\",\"LastUpdateDate\" : \"2023-08-31T14:05:51.328+00:00\",\"LastUpdatedBy\" : \"JOE.EXAMPLE\"}"
}

Once the integration passes this test, it's time to coordinate with your VBCS/FA UI developer for the final adjustments, ensuring the new business object functions correctly from the Fusion UI perspective.

Conclusion

This post aims to equip you with the knowledge to seamlessly integrate a new FA business object with Oracle Integration Cloud. By following these guidelines, developers can ensure a smooth and efficient integration process within the FASNI framework.