Monday, August 10, 2020

Embedding Oracle Analytics Dynamically - Part I

Oracle Analytics visualizations can easily be embedded into external websites, custom portal, applicative pages.... We will start exploring this capability in this blog entry. We will be creating our own custom website and we include Oracle Analytics content as a part of it. We will also explore the various steps involved to do this embedding of Analytics content. Let us start with a bare minimum HTML code for our website displaying the name and a few texts.

To understand the embedding context from a technical perspective, the functionality is supported by an underlying Javascript file that needs to be hosted on your destination website. Depending on the technology used in the client web portal, one of the following embedding modes is used:


Our objective is to leverage a public OAC instance and to embed its Sample Project visualizations into our own website. The first step for us will be to include the javascript file providing the embedding functionality inside the <head> tag of our website. In this case since our website is a simple HTML file, the embedding mode will be standalone mode. 

We can find reference to this script as well as it's address directly from within our own Analytics canvas, by clicking on the top right hamburger menu, selecting option developer and once there, clicking the Embed tab

This tab will show us all the urls we need to use in our own website html to embed our content

So we could simply copy the urls for the various canvas provided above in the embed tab of the developer menu, and simply paste them in our webpage html as is.

But we will go into a bit more details in our example. Embedding Oracle Analytics content is done through HTML API called <oracle-dv> tag. We need to include this tag as a part of our HTML code to enable embedding. Before we delve into the details of the code, following are the list of attributes that are supported for <oracle-dv> HTML tag.

  • project-path: Specify project in repository to render.
  • active-page: Optional and options to choose are Canvas or Narrate
  • active-tab-id: Optional. Specify the id of the canvas.
  • filters: Optional.
  • project-options:  Optional. Below are the options you can pass:
    • bShowFilterBar: Values should be true or false;Shows or hides filter bar.
    • bDisableMobileLayout: Values should be true or false; Disables or enables mobile layout.

We will be using project-path attribute to embed the Analytics content into our website. 

Now coming back to the code, the next step is include <oracle-dv> tag and set the project-path attribute to the path of the project that we want to embed. Now our HTML code for the website should look something like this.

Also included towards the bottom of the HTML code are the Knockout bindings. We are using the knockout model's declarative bindings to assign the value to the project-path attribute. Knockout bindings are generally executed either in a body onload handler or in a <script> tag after the <oracle-dv> tag. In this case we have used a <script> tag after the <oracle-dv> tag.

We are now one step away from including Oracle Analytics content into our website. The final step is to include the domain name of our website into the list of safe domains in the OAC instance from which we want to embed an Analytics project.

Since we are hosting the website on a localserver, we have added an entry for 127.0.0.1 along with the port number. If we want to do embedding on a public web server, add the domain name/ ip address of the web server to the list of safe domains. A refresh of the OAC instance is needed for the safe domains to kick in and now our website should look something like this


The rest of this blog will now be focused on how to pass filters from our website to the embedded Analytics contents.

As mentioned before, <oracle-dv> supports filter attributes. In order to pass filters to the embedded content, we need to construct filter object with the following attributes.

  • sColFormula: Specify the three-part column formula of the column to be used as a filter.  This MUST BE three parts. Create a project within DV using the column, then go to the Developer menu item and look up the column formula to get the three part forumula.
  • sColName: Specify a unique name for this column.  This must be non-empty.
  • sOperator: One of in, notIn, between, lessOrEqual, greaterOrEqual.  in and notIn apply to List filters.  between, lessOrEqual, greaterOrEqual apply to numeric filters
  • isNumericCol: Whether or not this is a numeric filter or a list filter.  Values should be true or false.
  • isDateCol : Flag indicating whether date column - values should be true or false and is a mandatory attribute - Note: This is set to true only for date and not for year, month,quarter etc. If this flag is set, fill aDisplayValues attribute with the date/s.
  • bIsDoubleColumn: Whether or not this column has double column values behind the display values.   Values should be true or false.
  • aCodeValues: When bIsDoubleColumn is true, this array will be used.
  • aDisplayValues: When bIsDoubleColumn is false, this array will be used for filtering and for displaying values within the UI. 
We will be passing filter values on the Order Priority Column from our website to the embedded content. The HTML code should look like the one shown below.


We are passing the value "Critical" on Order Priority column to act as a filter to the embedded DV content and our website will render the DV content with the context of the filter passed through our HTML code.

In the above pic, we can see the filter on the Order Priority column with the value "Critical" and all the visualizations in the DV canvas has re-rendered based on the filter. Similarly you can create an array of filter objects to pass filters on multiple columns. 

To make our website user interface more intuitive, a drop down with various values of Order Priority column has been created. On the selection of a particular value from the drop down, appropriate filters are passed on the Order Priority column to the embedded content.


In the next blog, we will focusing on how to use data actions to pass values from the embedded DV content to our website. Thanks for reading this blog !



Posted by at

No comments:

Post a Comment