In one of my recent projects, the customer had a requirement to integrate visualizations from Oracle Analytics into Oracle APEX application that is running within Oracle Cloud Infrastructure.
It is not my prime focus, the integrations, so I checked Oracle's documentation first. There is no "cook book" in there, so I looked it up for some good resources on the internet. Actually, you can find quite a lot of content out there, from blog posts, articles, even videos, however most of these are a bit old (not exactly obsolete) as both products have developed rapidly over the last couple of years.
But still, I found some really good ones that I was able to help myself with. For example Mike Durran's blog is usually the ultimate go-to source for these kind of things, and you can find quite a lot of content on this subject there. For example, you definitely want to check his article A Guide to Embedding Oracle Analytics into Oracle APEX.
In this blog post, I will try to describe my experience with integrating Oracle Analytics visualizations into Oracle APEX application, and point out some of the issues I encountered when I was following Mark's guide.
Let's begin with Oracle Analytics first
Our starting point is data visualization that shows company's sales.
There is one thing that we should pay attention to. In Developer options, besides performance statistics, you can find, under Embed tab, developer options that enable developers to embed analytics content in other applications, for example in Oracle APEX.
To embed specific visualization in some other application, developer can simply copy HTML code into another application to display and present Oracle Analytics content.
The following two JavaScript code snippets have to be copied into HTML page at the page level tag:
<script src="https://<your analytics instance>.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/<embeddingMode>/embedding.js" type="application/javascript">
</script>
Pay attention to the embeddingMode part of the URL above. It has to possible values: jet and standalone:
- use jet if analytics content is embedded within an existing Oracle JET application, and
- use standalone when embedding visualization content in a generic application that doesn’t use Oracle JET.
In the case of standalone option, Knockout bindings have to be applied after the visualization is fully loaded. This should be placed inside of a <script> tag after the <oracle-dv> tag (see below), or executed in an onload body handler.
<script>
requirejs(['knockout', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'],function(ko) {
ko.applyBindings();
});
</script>
Finally, the following code will be used to display visualization canvas in other application, Oracle APEX application in our case. The following <oracle-dv> tag will be used:
<oracle-dv project-path="/@Catalog/shared/Demos/CEO Dashboard (Sales)" active-page="insight" active-tab-id="snapshot!canvas!1">
</oracle-dv>
Example above displays canvas1, in the example below, canvas3 will be displayed.
<oracle-dv project-path="/@Catalog/shared/Demos/CEO Dashboard (Sales)" active-page="insight" active-tab-id="snapshot!canvas!3">
</oracle-dv>
REMARKS:
- To open Developer Options click on the Workbook Menu. Developer is the last option in the menu:
- If Developer option is not displayed in the menu, than Developer Options is not enabled. To enable them, click on user icon (top right corner) and choose Profile.
Then, click on Advanced tab and click to Enable developer options:
APEX application
In this example, I have simply created a simple APEX application.
From the three available pages, select 1 - Home.
A new region <body> has been created where all of the coding would happen. Actually in this simple scenario, no real coding will be needed, except a few bits here and there.
Actually, the coding is happening in two places:
- on the
<page>level and - on the
<body>level.
Let's check out the <page> level first. In the two fields: File URLs and Function and Global Variable Declaration, the code snippets that we observed under Developer / Embed tab of data visualization workbook (see details and explanaition above) should be copied:
Once completed, navigate to the <body> region.
In Identification section, Static Content should be selected for Type.
In Source section, enter the following code snipped in HTML Code field:
<iframe src=<iframe src="https://<Oracle Analytics Cloud URL>.analytics.ocp.oraclecloud.com/ui/dv/ui/project.jsp?pageid=visualAnalyzer&viewermode=true&noheader=true&reportmode=full&reportpath=%2F%40Catalog%2Fshared%2FDemos%2FCEO%20Dashboard%20(Sales)" width="1200px" height="900px" frameborder="0"></iframe>
Alternatively I tried to use the code snippet, prepared under Developer, but wasn't able to make it work. Any suggestion, what I was missing or doing wrong is more then welcome!
The following code should have worked, but ...:
<div style='width: 1200px; height: 900px'>
<oracle-dv project-path="/@Catalog/shared/Demos/CEO Dashboard (Sales)" active-page="insight" active-tab-id="snapshot!canvas!1">
</oracle-dv>
</div>
Since, <iframe> based solution worked, I decided to deal with this at some later point.
Here, one would expect OAC Data Visualization can be embedded and run within APEX application. I have found a few blog posts which were claiming this works. However, if you try and run your application now, it won't work. At least, it didn't for me. The reason is that we still need to sort out authentication. APEX is using its own authentication, whereas Oracle Analytics Cloud is using Oracle Identity Cloud (IDCS), and these two are not working together by default.
Identity Cloud Domain
I'll create a new user group for useers who have access to data visualization workbook in Oracle Analytics. This particular step isn't required if user group already exists.
In the next step, newly created group is given access to the analytics instance. For this example, we are assigning ServiceAdmistirator (doesn't have to be) application role to the new group.
And finally, let's create a new application under Integrated applications. There are two parts to it:
- APEX application configuration and
- OAuth configuration.
On creating (adding) a new application, select Confidential application.
Then follow the wizard that guides you through the process of setting a new application.
Important entries are as follows:
- Application URL in URLs section: enter APEX application URL.
- Check Enforce grants as authorization in Authentication and Authorization section
When setting up OAuth enter the following:
-
Resource server configuration: check No resource server configuration
-
Client configuration: check Configure this applicaton as a client now
-
check Authorization code checkbox
-
Redirect URL:
https://<APEX instance URL>.adb.eu-frankfurt-1.oraclecloudapps.com/ords/apex_authentication.callback -
Post-logout redirect URL:
https://<APEX instance URL>.adb.eu-frankfurt-1.oraclecloudapps.com/ords/r/apexdemo/embed-oac-into-apex-application/home
-
Check Add resources checkbox and add your analytics service in the resource list. This is needed to access API of Oracle Analytics application.
-
There is one more thing that is important. Each application provides two variables: Client ID and Client Secret. These are required to create Web Credentials in the next step.
Information about Client ID and Client Secret can be found in OAuth Configuration section under General Information.
Web Credentials
In order to access other applications from APEX application, we need to create Web Credentials using Client ID and Client Secret created and stored in the previous step.
Navigate to the AppBuilder page in APEX and open Workspace Utilities.
From the list of available utilities choose Web Credentials
Web Credentials page opens. Besides Name and Static ID, provide the following information:
- Authentication Type: choose Basic Authentication
- Enter Client ID in Client ID or Username field.
- Enter Client Secret into Client Secrete or Password field. Reenter Client Secret into Verify Client Secrete or Password field.
Authentication Scheme
The last step in our configuration exercise is to create an Authentication Scheme. There are several sections that require settings:
- Name
Provide Authentication Scheme Name and choose Social Sing-in for Scheme Type.
- Settings
Under Settings select Credentials Store that was created in the previous step in Web Credentials step.
Select OpenID Connect Provider for Authentication Provider
In the Discovery URL enter the following URL:
https://<Identity Domain URL>.identity.oraclecloud.com/.well-known/openid-configuration
IDCS Domain URL can be found in Identity Domain Page:
Use Domain URL and add /.well-known/openid-configuration to complete Discovery URL.
Enter profile in Scope field, and sub into Username field.
- Post Log-in Processing
Choose URL for Go to and enter APEX application URL in URL.
Almost Ready to go! Security Attributes
Now, there is only one small bit to do before going live. Still under Shared Components, locate Security Attributes.
Update the following fields and then apply changes:
-
In Authentication section:
- Leave APEX_PUBLIC_USER as Public User
- Select Authentication Scheme that was created in the previous step.
-
In Authorization section:
- Choose No application autorization required for Authorization Scheme
- Choose Custom Code in Source for Roles or Group Schemes
Run APEX Application
We are now ready to go:
or simply enter URL in browser pointing to APEX application:
https://<APEX instance URL>.adb.eu-frankfurt-1.oraclecloudapps.com/ords/r/apexdemo/embed-oac-into-apex-application/home
Conclusion
What to say for the end. As far my exercise goes, it is working nicely. There are quite a few steps, but mostly is about configurations. I had to play a bit to get all pieces working, but anyway it was nice exercise. At least I had to create my first APEX application. I must admit I haven't been playing with these tools since APEX' predecessors WebDB and Oracle Portal 😎.
I hope this post will help someone and I also believe this is not the last post on this topic as there are some interesting use cases to be tested. We also have a case where a customer wants to integration Oracle Analytics Server and APEX, all running on premise. And as I said, any comment to my private email is welcome.