Visual Builder Component for Embedding Oracle Analytics — Part 1
--
Introduction
This is the first of a series of blogs explaining how application developers can use an Oracle Visual Builder (VB) component for embedding Oracle Analytics Cloud (OAC) Data Visualization projects.
Part 1 — Introduction
Part 2 — Layout and Sizing
Part 3 — Using Filters
Part 4 — Navigation
Part 5 — Mobile Apps
Part 6 — Token Authentication
Part 7 — Events
Using this component, it’s possible to create custom web and mobile analytical applications using Visual Builder with visualisations sourced directly from Oracle Analytics Cloud.
I’ll assume you already have some experience with VB, but if you’re just getting started, there are plenty of excellent resources and tutorials available to help you get up to speed. See ‘Get Started with Visual Builder’ if you don’t already have a VB instance available in your Oracle Cloud Tenancy.
Web components are a standard way of simplifying web development through creation of custom HTML tags. The OAC web component for VB specifically manages the existing OAC embedding framework (embedding.js and <oracle-dv>) within the context of a VB application.
If you are new to embedding OAC projects, I have an introductory blog that will help you get started.
Pre-Requisites to Using the Component
Both the Oracle Analytics Cloud instance and Oracle Visual Builder instance must be in the same Oracle Cloud Tenancy and using the same Oracle Identity Cloud Service (IDCS) for identity management. Any users who need to use the VB application must have the appropriate access / privileges for both OAC and VB.
Before you can embed analytics content into a VB application, there is some configuration required. You need to add the domain (up to the .com) of the VB application you are embedding into as a safe domain entry in the OAC console. For example, add:
https://<Your-VB-Instance>.builder.ocp.oraclecloud.com
and check the ‘Embedding’ box for that entry.
In VB, select settings, and add the OAC instance URLs to the ‘Allowed Origin’ section. You also need to add the URL for the IDCS instance that is used by both OAC and VB. A way to find the IDCS URL is to navigate to the link you’d use to log in to OAC and you’ll be redirected to the IDCS login page. Capture this URL (up to the .com) and add it to the VB ‘Allowed Origins’.
If you get any issues with logging in and viewing content, you may also need to add the instance URLs to the Oracle IDCS configuration ‘Allow Cross-Origin Resource Sharing (CORS).
Installing the Component
Assuming that you have already created a web application in VB, e.g., using one of the app templates, you will find the OAC component in the VB ‘Components Exchange’ section by searching for ‘analytics’. You’ll see a component called ‘Oracle Analytics Project’.
Install this component in your VB application.
Once installed, you can manage any available updates to this component from this area of the VB product. You can also see a description of the component and details on how to use it if you click on the component name once it’s been installed.
Note: you need to install the analytics component for each new application that you wish to embed analytics projects into.
Using the Component
Navigate back to your web application, where you’ll now see the ‘Oracle Analytics Project’ listed in the available components.
The easiest way to get started is to add a ‘Flex Container’ component to your application page, then drag the analytics component into the container. You will see a message to ‘Configure analytics host and project path’.
You need to reference the host of your analytics cloud instance e.g.,
https://<your-oac-instance >.analytics.ocp.oraclecloud.com
You can get the analytics project path reference from the developer menu, embedding tab in OAC. Typically, when embedding into an application that is intended to be accessed by multiple users, you’ll want to make sure to embed an OAC project that is stored in the ‘shared’ area of the catalog.
You’ll notice a number of options that are available in the ‘Oracle Analytics Project’ Component. The easiest option to try out is the check box to show or hide the filter bar. If you don’t see any analytics canvas, make sure you have a page structure similar to the screenshot above, i.e. with a Row, Container, Component hierarchy.
Also note that VB has a ‘Live’ mode that you may need to select if you want to see changes / interactivity with the embedded canvas.
In subsequent blogs, I’ll cover how to add multiple canvases and define layout, and describe in more detail how to use the filter and token options of the component.
