Introduction

In this installment of our technical series on Fusion Applications Social Network Integration (FASNI), we examine the generation of custom header messages within Oracle Integration Cloud (OIC) for use in Microsoft Teams conversations concerning Fusion Applications (FA) Business Objects. We'll dissect the current implementation, highlighting the process by which OIC creates and sends these headers, and then delve into methods for customizing them to fit your specific needs.

Current Implementation

FASNI header message generation utilizes OIC Lookups and JavaScript within OIC Libraries. There are two header message types:

1. Microsoft Adaptive Cards: Preferred for their interactivity, customization, and adaptability to the look and feel of the Microsoft Teams applications. They are JSON-structured, and you can explore the capabilities at https://www.adaptivecards.io/designer/.
2. Plain HTML Headers: Utilize standard HTML for text presentation (typically an HTML table). They are straightforward to implement and provide the flexibility of using all the standard HTML markup.

OIC Lookups store template configurations for dynamic insertion of data into header message templates. OIC Libraries supply JavaScript functions for precise data manipulation and formatting aligned with header requirements. Templates utilize placeholders for dynamic data substitution from Fusion Business Objects, optimizing message relevance for Teams. The Adaptive Card format employs an additional layer of placeholders to integrate Business Object labels and values into the Adaptive Card JSON.

Preference for Adaptive Cards stems from their native support within the Teams ecosystem, while both types are integral to FASNI for adaptable business communication.

It is important to point out that there are several multi-line examples for OIC Lookups below. These examples have been formatted for readability, but when saved in the OIC Lookups, they should be compacted into a single line. There are online sites that provide this capability (e.g., https://jsonformatter.org/).

Microsoft Adaptive Cards

For Microsoft Teams integration, Adaptive Cards are the preferred header block message type due to their native support with Microsoft Teams. The implementation involves two OIC Lookups: BUSINESSOBJECT.TYPE.AdaptiveCardTemplate and MESSAGES.AdaptiveCardTemplate.

BUSINESSOBJECT.TYPE.AdaptiveCardTemplate

This Lookup defines the standard JSON structure for FA Business Object fields, specifying field labels and placeholders for values. An example structure might look like this:

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

1. It follows a strict JSON format, with keys representing labels and values corresponding to the field names from the FA REST API JSON payload.
2. Any fields absent in the FA payload will retain their placeholder text in the final Adaptive Card.

MESSAGES.AdaptiveCardTemplate

This Lookup contains the Adaptive Card JSON template. It uses placeholders within curly braces that are dynamically replaced by the corresponding labels and values from the FA Business Objects. The design assumes a uniform Adaptive Card layout across different Business Objects, with specificity in detail. An example Adaptive Card template is:

{
  "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"
}

The key takeaways from the example are:

1. It serves as a universal layout for all Business Objects utilizing Adaptive Cards.
2. Placeholders denoted by keywords within curly braces are replaced with actual data from the FA Business Objects.

Generating the Adaptive Card Header Block Message

The OIC MS Teams Message Utils orchestration, via the getMessageForCreateChannel operation, processes header block messages. When an Adaptive Card is identified as the message type, the orchestration calls the fillAdaptiveCard function from an OIC Library. This function takes the Adaptive Card template, Business Object template, and FA REST API JSON payload, merging the payload data with the Business Object JSON. Subsequently, it combines this data-filled Business Object JSON with the Adaptive Card template. The fully composed Adaptive Card is then returned and posted to the Teams channel, serving as the cornerstone of the discussion.

Customizing the Adaptive Card Message Type

Customizing Adaptive Cards for FA Business Objects in Microsoft Teams is streamlined with the use of the Adaptive Cards Designer (https://www.adaptivecards.io/designer/). This tool aids in visually constructing and modifying the card's layout and interactive elements.

When adapting BUSINESSOBJECT.TYPE.AdaptiveCardTemplate, the JSON structure is tailored to match the FA REST API JSON payload schema. Fields, labels, and data types should be methodically mapped to the payload's structure to ensure accurate data representation.

For MESSAGES.AdaptiveCardTemplate, the designer tool can be employed to refine the card's aesthetic and functional attributes. The resultant JSON should maintain placeholder consistency to facilitate the correct merging of data at runtime.

A crucial part of customization involves updating the JavaScript function responsible for merging data into these templates. This function, fillAdaptiveCard, performs the necessary logic to:

1. Parse the FA REST API JSON payload.
2. Replace placeholders in the BUSINESSOBJECT.TYPE.AdaptiveCardTemplate with actual data.
3. Merge this data-filled template into the MESSAGES.AdaptiveCardTemplate to create the final Adaptive Card JSON.

The current fillAdaptiveCard JavaScript function is designed with a resilient structure that seamlessly accommodates the introduction of new fields, eliminating the need for changes to the function when expanding the BUSINESSOBJECT.TYPE.AdaptiveCardTemplate. It dynamically parses and maps data from the FA REST API JSON payload into the specified placeholders within the template. This built-in flexibility allows for the automatic incorporation of new fields into the Adaptive Card without manual adjustments to the function.

While the function is robust, significant design changes to the AdaptiveCardTemplate could necessitate updates to the function to ensure compatibility. In such cases, as long as the signature and return type of the function remain the same, the fillAdaptiveCard function can be retained and adapted to align with the new template design. Developers should review the function's logic to confirm that it correctly interprets the revised structure and integrates new interactive elements or data formats as required.

In the event of a design overhaul, it’s advisable to revisit the function to apply necessary updates. This might involve adjusting the data mapping logic, handling additional conditional statements, or incorporating new JSON structures. Ensuring the function aligns with the updated Adaptive Card template will maintain the integrity of the dynamic data replacement process and the overall functionality within Microsoft Teams.

Testing remains a critical step post-customization to confirm that the Adaptive Cards render correctly and interact as intended within the Teams environment, providing a consistent and effective user experience.

Plain HTML Headers (BUSINESSOBJECT.TYPE.MessageTemplate in OIC Lookups)

Documented for reference, the use of Plain HTML Headers is a secondary approach compared to the preferred Microsoft Adaptive Cards. Implementing this message block type for a Business Object requires exclusive selection; it cannot be used concurrently with an Adaptive Card configuration for the same object. Below is an example of an HTML MessageTemplate:

<table style='border-collapse:collapse;border:1px solid #ddd'>
    <tr>
        <th colspan=2 style='padding:5px;text-align:left;background-color:#f2f2f2'>Purchase Order {OrderNumber}
    <tr>
        <td style='padding:5px'><strong>Supplier</strong>
        <td style='padding:5px'><strong>Supplier Site</strong>
    <tr>
        <td style='padding:5px'>{Supplier}
        <td style='padding:5px'>{SupplierSite}
    <tr style='height:15px'>
    <tr>
        <td style='padding:5px'><strong>Buyer</strong>
        <td style='padding:5px'><strong>Amount</strong>
    <tr>
        <td style='padding:5px'>{Buyer}
        <td style='padding:5px'>{Total}
    <tr style='height:15px'>
    <tr>
        <td style='padding:5px'><strong>Procurement BU</strong>
        <td style='padding:5px'><strong> </strong>
    <tr>
        <td style='padding:5px'>{ProcurementBU}
        <td style='padding:5px'>
    <tr style='height:15px'>
    <tr>
        <td style='padding:5px' colspan=2><strong>Description</strong>
    <tr>
        <td style='padding:5px' colspan=2>{Description}
</table>

The key takeaways from the example are:

1. Use single quotes within your HTML templates to prevent parsing issues within OIC Lookups.
2. Placeholders wrapped in curly braces correspond to field names in the FA REST API JSON payload.
3. Absent fields in the payload will result in their placeholders being displayed in the final message.

OIC processes header block messages via the MS Teams Message Utils orchestration, specifically the getMessageForCreateChannel (/messages/createChannel) operation. This operation iterates through the FA JSON payload, substituting placeholders in the MessageTemplate with actual field values. After all replacements, the completed HTML header block message is returned to the caller and posted to the designated Microsoft Teams channel, anchoring the conversation.

Customizing the Plain HTML Message Type

Customization of the Plain HTML message type in OIC is a straightforward process that involves altering the HTML templates stored within the OIC Lookups. These templates act as blueprints for generating the HTML header blocks used in Microsoft Teams conversations.

When customizing these templates, developers should consider the following:

1. HTML Template Structure: The HTML must be properly formatted to ensure it is rendered correctly within Teams. This means using inline styles, not external stylesheets.
2. Data Binding: Placeholders within the HTML template, denoted by curly braces (e.g., {FieldName}), correspond to the data fields from the FA REST API JSON payload. When adding new fields to the HTML template, ensure they match the names of the fields in the FA JSON payload for correct data binding.
3. Single Quotes: HTML tags containing quoted information must leverage single quotes to avoid strange behaviors with OIC Lookups.
4. Testing: After customization, thoroughly test the templates by sending test messages within a development environment. This ensures that the HTML appears as expected in Teams and that all data fields are populating correctly.

Conclusion

In conclusion, the ability to effectively customize message types in OIC for use within FASNI is integral to enhancing business communication. By leveraging the robust design of OIC Lookups and Libraries, organizations can tailor both Plain HTML and Adaptive Card message types to suit specific business needs. The Plain HTML message type offers a straightforward, widely compatible format for simple notifications, while Adaptive Cards provide a rich, interactive experience for users.

Adaptive Cards, being the preferred choice, allow for dynamic and visually appealing messages that can be intricately customized using the Adaptive Cards Designer tool. The fillAdaptiveCard JavaScript function in OIC provides a resilient framework for integrating data from Fusion Applications (FA) REST API, and while it is designed to accommodate new fields with minimal effort, significant template redesigns may necessitate function updates to preserve functionality.

The guidelines discussed emphasize the importance of meticulous customization, thorough testing, and adherence to best practices. By doing so, organizations can ensure that their integration of FA Business Objects with Microsoft Teams is seamless, efficient, and provides an engaging user experience. Ultimately, these customizations serve to streamline communication, improve workflow visibility, and contribute to the overall agility of business operations.