Fusion Applications Social Network Integration is a new sample the A-Team have produced and published as a downloadable solution, complete with source code.

As announced in this blog article, we have recently announced the availabiltiy of a code sample which demostrates how a customer can integrate Oracle Fusion Applications with Microsoft Teams.  The sample implements a range of functionality from allowing users the ability to create conversations for a business object , receiving change events from Oracle Fusion etc. 

This document details the architecture and design patterns used in this solution and should be read in conjunction to the documentation available in the code sample. The code sample is downloadable from https://www.oracle.com/middleware/technologies/fusion-applications-downloads.html

 For this solution we implemented the following design principles:

• Conversation data is only ever stored in Microsoft Teams, within the solution it is only viewed not stored
• Users can only view conversations, within Fusion, if they can view the business object. This preserves that authorization is centralised within Oracle Fusion Applications
• Users do not need to be added to the conversation within Microsoft Teams to view a conversation but if they want to participate then they will be added.
• Any changes to business objects in Oracle Fusion will result in a message being posted , and the associated header message, in the Microsoft Teams conversation 
• Oracle managed services used
• Solution is designed to be extensible in that we could support new social networks in the future and allow the customer the add features (e.g. add a data sink to a custom database)

Architecture

User Interface

The user interface is built using the Oracle VBCS service. This is a low code development environment which integrates natively with Oracle Integration Cloud Integration and natively supports single sign on with Oracle Fusion. Oracle Integration Cloud Service comes in a licensable SKU which includes Visual Builder Cloud Service, this is advantageous as it means VBCS and Integration cloud are hosted on the same server and only one single sign on association needs to be done with Oracle Fusion.

Oracle VBCS also comes with an inbuilt 5GB fully manage database, this is used to store metadata (not conversation data) . This database is fully managed by Oracle VBCS.

When the VBCS page is embeded the VBCS application it makes calls to Oracle Integration Cloud. These calls only three parameters to be passed (to OIC)

• fusionObjectId
  • This is the ID for the object for which the conversation is being created for. When embedding the iFrame into the Fusion Applications page, the object Id is obtained using either Page Composer Expression Language (EL) or for application Composer it is done via groovy scripts.
• fusionObjectType
  • This defines the object type which corresponds to the object id passed. For example, for a requisition this would be PROCUREMENT.REQUISITION
• JWT Token
  • OIC requires a JWT token so that it can call Fusion Applications as the user to perform the AuthZ checks. This JWT token is sent securely within the REST call to OIC and not on the URL/URI

OIC uses these values to validate that the user has access to the object and for the creation of the conversations in Microsoft Teams.

Integration Layer

The Integration layer used in this solution is called “Oracle Integration Cloud”, aka OIC, which is a part of Integration Cloud Service. This service provides several REST endpoints that VBCS can call and in turn calls to Microsoft Teams are performed.

The API used between VBCS and OIC is generic and not specific to Microsoft Teams as the backend. In the future it would be possible to switch out Microsoft Teams and implement an integration layer for Slack, Zoom etc for very little, if any, changes to the UI.

OIC provides several integration flows but the most important one is the one which queries conversation data.

When we call OIC requesting conversation data, VBCS passes the objectId, objectType and a JWT token.

OIC then does several steps:

1. It queries the object in Oracle Fusion using the same user credentials (JWT token). This is our AuthZ check, “Is the user able to query the object?”.
   • If we get data, then the user has access to this object, and we can proceed - If not then an error is returned to the user.
   • In practice unless a user is bypassing the user interface and calling the REST APIs directly we should never encounter this not AuthZ error.
   • This process has been implemented to enforce AuthZ check.
2. For performance reasons we also query any data we need for future operations.
3. When the conversation was created, in the create conversation flow, we stored a mapping between the objectId and objectType to a Microsoft Teams "Team ID" within the VBCS Database. 
4. We query this metadata from VBCS and then using the Team ID we query the converation from Microsoft Teams
5. We can now can return the conversation data to the user interface in a canonical format which is not Microsoft Teams specific.

The integration layer also contains APIS for the creation of channels, the querying of Microsoft Teams metadata etc. For more information please see the documentation in the download package.

VBCS DB

The embedded VBCS Database contains three business objects. We use these objects to store metadata for the integration. The most important one being the mapping between the fusion object ID / Type tuple and the Microsoft Teams team id. The inbuilt 5Gb database will be suitable for most users but if needed VBCS runtime allows us to associate an Autonomous Oracle Database to VBCS for customers who require greater database storage.

Embedding the iFrame Info Oracle Fusion

The VBCS application is embedded within Oracle Fusion using an iFrame. For App Composer pages the iFrame is embedded using the "mashup" approach and uses groovy script to send the parameters to VBCS. For pages which are page composer based, custom HTML5 (CSS/HTML/JavaScript) is added to the pages. This html5 snippets embed the VBCS UI within an iFrame and control the openinig/closing of a side drawer using CSS.

Application Composer

For Application Composer (aka App Composer) the UI is a traditional web mash up where we embed the VBCS UI within a mashup. We pass the object type and object ID using a very simple groovy script.

Page Composer

For page composer objects things are a little different. On the desired page we use page composer to add a html component to the page.

This html component contains html, and CSS, to:

• Define an invisible region (using a DIV), which becomes the drawer.
• Some CSS to style the drawer, but more importantly CSS classes which show/hide the draw in a nice aesthetic way.
• An iFrame, the iFrame SRC path has parameters and these parameters are dynamically created using page composer expression language. This is required so that we can create the src and add the objectId and objectType.
• A button, which executes one line of JavaScript, and this is the enable the “show” drawer functionality by using a CSS class.

For more information please see the installation guide for the Fusion Applications and Microsoft Teams Integration, whilst this document focuses on the installation of the sample it also contains all the technical details on how the solution works. The sample can be downloaded from https://www.oracle.com/middleware/technologies/fusion-applications-downloads.html