Use Data Actions to Connect to Canvases, External URLs, Oracle Analytics Publisher Reports, and Use in External Containers

A Data Action link can pass context values as parameters to external URLs, filters to other projects or to visualizations embedded in external containers.

When a link navigates to a project, the data context is displayed in the form of canvas scope filters in the filter bar. The links data context may include attributes associated with the selections or cell from which the link was initiated.

Create Data Actions to Connect Visualization Canvases

You can create data actions to navigate to a canvas in the current project or to a canvas in another project.

You can also use data actions to transfer context-related information (for example, an order number) where the link displays details about an order number in another visualization or project.

  1. Create or open a project and confirm that you’re working in the Visualize canvas.
  2. Click Menu on the project toolbar and click Data Actions.
  3. Click Add Action and enter a name for the new navigation link.
    • You can use only letters and numbers in the navigation link’s name.
    • You can add multiple navigation links.
  4. Click the Type field and select Analytics Link.
  5. Click the Anchor To field and select the columns from the current visualization to associate with this data action. Don't select measure columns or hidden columns. If you don't specify a value for the Anchor To field, then the data action applies to all data elements in the visualizations.
  6. Click the Project field and select the project you want to use for the anchor:
    • Use This Project - Select if you want to link to a canvas in the active project.

      Columns that you select must be in the current visualization.

    • Select from Catalog - Select to browse for and select the project that you want to use.
  7. Click the Canvas Link field and select the canvas that you want to use.
  8. Click the Pass Values field and select which values you want the data action to pass.
    For example, if in the Anchor To field, you specified order number column, then in the Pass Values field, select Anchor Data to pass the specified column values.
    • All - Dynamically determines the intersection of the cell that you click and passes those values to the target.
    • Anchor Data - Ensures that the data action is displayed at runtime, but only if the required columns specified in the Anchor To field are available in the view context.
    • None - Opens the page (URL or canvas) but doesn't pass any data.
    • Custom - Enables you to specify a custom set of columns to pass.
  9. Click OK to save.

Create Data Actions to Connect to External URLs from Visualization Canvases

You can use data actions to navigate to an external URL from a canvas so that when you select a column such as the supplier ID, it displays a specific external website.

  1. Create or open a project and confirm that you’re working in the Visualize canvas.
  2. Click Menu and select Data Actions.
  3. Click Add Action and enter a name for the new navigation link.

    You can add multiple navigation links.

  4. Click the Type field and select URL Navigation.
  5. Click the Anchor To field and select the columns that you want the URL to apply to. If you don't specify a value for the Anchor To field, then the data action applies to all data elements in the visualizations.
  6. Enter a URL address and optionally include notation and parameters.

    For example, where http://www.example.com?q=${keyValuesForColumn:"COLUMN"} is displayed like www.oracle.com?q=${keyValuesForColumn:"Sales"."Products"."Brand"} The column names that you select here are replaced with values when you invoke the data action.

  7. Click OK to save.
  8. In the Canvas, click a cell, or use Ctrl-click to select multiple cells.
  9. Right-click and select from the menu the navigation name that you created earlier.
    Selecting the cells determines the values to pass to the parameters (that is, the URL tokens).

Create Data Actions to Connect to REST APIs from Visualization Canvases

You can use HTTP API data actions in a canvas so that when you select a column, it sends the value to a REST API which returns a response from the external website.

You must configure the domain that you're trying to connect to as a safe domain before you create an HTTP API data action. See Register Safe Domains.

  1. Create or open a project and confirm that you’re working in the Visualize area.
  2. Click Menu and then select the Data Actions tab.
  3. Click Add Action and enter a name for the new HTTP API data action. For example, enter HTTP API Example.

    You can add multiple HTTP API data actions.

  4. Click the Type field and select HTTP API.
  5. Click the Anchor To field and select the columns that you want the HTTP API data action to apply to. Don't select measure columns or hidden columns. If you don't specify a value for the Anchor To field, then the data action applies to all data elements in the visualizations.
  6. Click the HTTP Method field and select an appropriate value (that is, GET, POST, PUT, DELETE) to send to the REST API.
  7. Enter the URL for the REST API that starts with http or https and optionally includes replacement tokens.

    Replacement tokens in the URL pass contextual values to a data action (for example, data values, user name, project path, canvas name).

    For example, you can pass a column value (for example, a value for the Category column) to a REST API (for example, the Google books API) using: http://www.googleapis.com/books/v1/volumes?q=${valuesForColumn:"Category"} The value that you select from a cell in the Category column (for example, "Books") passes to the REST API.

  8. If you selected the POST method, a field is displayed where you enter each parameter on a separate line.

    You enter each parameter as a name-value pair with the name and value separated by "=". You can use the same URL token syntax in the name-value pairs as required by the API that you're calling.

    For example:

    • paramName1=paramValue1
    • paramName2=${valuesForColumn:"Product"}
  9. Click OK to save.
  10. Click a data point in the visualization.

    For example, you might select "Books" from the Category column.

  11. Right-click and select HTTP API Example to display the result.

    The selected data-points determine which values to pass to the URL tokens.

    A success or failure message is displayed confirming the REST API has been successfully invoked using the selected value.

Use Data Actions to Connect to Oracle Analytics Publisher Reports

A data action link can pass context values as URL parameters in Oracle Analytics Publisher reports.

When you click a link to open a Publisher report, the link might include attributes associated with the column selected in the visualization.

About Creating Data Actions to Connect to Oracle Analytics Publisher Reports

You can create a data action to link to an Oracle Analytics Publisher report.

You configure a data action to pass selected column values from a visualization to display in a Publisher report.

  • You must store your Publisher report in a local folder.

  • When the Publisher report uses the analysis as the data model, prompts in the underlying analysis must have User Input value set to Choice List to enable selected values to pass to prompts in the Publisher report.

  • You can pass lists of values and list filters to display as prompts in your Publisher report. However, you can't pass number filters, date filters, or expression filters.

Create Data Actions to Connect to Oracle Analytics Publisher Reports

You can create an analytics data action link to transfer selected data points from an Oracle Analytics project to an Oracle Analytics Publisher report.

The Oracle Analytics project, Publisher report, and analysis can be in different folders.

  1. Open an Oracle Analytics project that uses the data model used in the Publisher report.
  2. Click Menu on the project toolbar and click Data Actions.
  3. Click Add Action and enter a name for the new navigation link.
  4. Click the Type field and select Analytics Link.
  5. Enter a name for the data action in the Name field.
  6. Click the Target field, select Select from Catalog, then browse to select the Publisher report that you want the data action to pass data to, and click OK.
  7. Verify that Parameter Mapping is set to Default.
  8. Verify the Pass Values field value is set to All.
  9. Click OK.
  10. Select data points in the visualization and choose the data action to test that the values are passed to the Publisher report.

Create Custom Column Names in Data Actions to Pass in Oracle Analytics Publisher Report URLs

You can create a data action link that passes custom column names in the URL of an Oracle Analytics Publisher report.

  1. Open an Oracle Analytics project.
  2. Click Menu on the project toolbar and click Data Actions.
  3. Click Add Action and enter a name for the new navigation link.
  4. Click the Type field and select Analytics Link.
  5. Enter a name for the data action in the Name field.
  6. Click the Target field, select Select from Catalog, then browse to select the Publisher report that you want the data action to pass data to, and click OK.
  7. Click Parameter Mapping and select Set Custom Mapping to specify custom column names to pass as URL parameters to the Publisher report.
  8. Click Add Row and click Select a Column for each column that you want to pass to the Publisher report using a custom name.
  9. Click Enter Parameter and enter a custom name for each column name that you want to replace.

    The custom name passes to the Publisher report in the URL.

  10. Verify the Pass Values field value is set to All.
  11. Click OK.
  12. Select data points in the visualization and choose the data action to verify that the custom column names are displayed in the URL of the Publisher report.

Invoke Data Actions from Visualization Canvases

You can invoke data actions from a canvas to other canvases and URLs.

  1. Create or open a project. Confirm that you’re working in the Visualize canvas.
  2. On the canvas that contains a Data Action link leading to another canvas or URL, perform the following steps:
    1. Right-click a data element, or select multiple elements (using Ctrl-click).
    2. Select Data Actions from the context menu.
    3. Complete the Project Properties dialog.
    The name of the data actions that apply in the current view context are displayed in the context menu.
    All the values defined in the Anchor To field must be available in the view context in order for a data action to be displayed in the context menu.
    The following rules apply to matching data elements passed as values with data elements on the target canvas:
    • If the same data element is matched in the target project's canvas, and if the target canvas doesn't have an existing canvas filter for the data element, a new canvas filter is added. If there is an existing canvas filter, it’s replaced by the value from the source project's canvas.

    • If the expected data set is unavailable but a different data set is available, the match is made by using the column name and data type in the different data set, and the filter is added to that.

    • If there are multiple column matches by name and data type, then the filter is added to all those columns in the target project or canvas.

    The data action navigates to the target cell or URL that is mapped and filters the data displayed based on the values specified in the Data Actions dialog.

    The Pass Values context, set in the Pass Values field, consists of data elements used in the visualization from which the data action is invoked. The Pass Values context doesn't include data elements in the project, canvas, or visualization level filters.

Create Data Actions in Visualizations Embedded in External Containers

You can embed visualizations in external containers (for example, an HTML page or consumer’s application page), and you can include data actions in the visualization. An embedded data action allows you to interact with the embedded visualization in the external container. In the external container, you can also retrieve the set of data elements values that were selected in the visualization. You can add any number of embedded data actions.

The Publish Event is one such data action type, which can be defined in a visualization. When the Publish Event data action is invoked on the visualization, it enables external applications to receive the visualization context. In this situation, the word “context” means the set of data element values at the selected location in the visualization.

  1. Create or open a project. Confirm that you’re working in the Visualize canvas.
  2. In the project menu select Data Actions.
  3. Click Add Action, and enter a name in the Name field for the new data action.

    For example, DV Embedded Content DA1. You can use letters and numbers in a data action’s name.

  4. Click Type and select Publish Event.
  5. Click Add Data or Select Data in the Anchor To field, and select one or more data elements that you want to pass values when the data action is applied. Don't select measure columns or hidden columns.
  6. Enter an Event Name. The event name is provided in the external container and is passed when you publish the context event. The word “context” here means the set of data element values at a selected location in the visualization. If the data action is used across multiple projects or multiple data elements in a project, provide a unique event name for easier tracking.

    For example, if you entered DV Embedded Content DA1 as the action name, then in the Event Name field, you might enter Event from DA1 to indicate which data action the event comes from.

  7. Click the Pass Values field and select which values you want the data action to pass to the consumer.

    For example, if in the Anchor To field you specified Order Number, then in the Pass Values field, select Anchor Data to pass the Order number values.

    Values Description
    All Dynamically determines the intersection of the cell that you click (for example, "Product and Year") and passes those values to the target.
    Anchor Data Ensures that the data action is displayed at runtime, but only if the required columns specified in the Anchor To field are available in the view context.
    None Opens the page (URL or canvas) but doesn't pass any data. For example, you might want to navigate to www.oracle.com without passing any context.
    Custom Enables you to specify a custom set of columns to pass.
  8. Click OK to save.

    After saving the project, you can embed the project in external containers. The external container shows the embedded visualizations. When you right-click the visualization and it includes applicable data actions, they’re displayed in the visualization in a drop-down menu. If you click an embedded data action, it determines the context information for the visualization and passes that information to the navigation action service to process it. The navigation service raises an event with the context payload information. You can subscribe to this event to receive the payload in the event callback and use the payload in other areas.

  9. In the external container, you execute data actions that contain embedded content by following these steps:
    1. Add or modify the path location of the project.
    2. Subscribe to the published event for the visualization.
    3. Define an event listener and an event callback.

Execute Data Actions that Contain Embedded Content

When you configure a data action that contains embedded content, you can embed the project for that data action into containers such as an HTML page or an application web page.

Note:

The examples in this section apply to embedded data actions when the embedding application doesn’t use Oracle JET technology. See:

Executing Data Actions

The embedded visualization is displayed within the HTML container. When you right-click the visualization, any applicable data actions are displayed in the visualization. When you click a Publish Event data action, it determines the context information for the visualization and passes that information to the navigation action service to process it. The service process for the navigation action raises an event called “oracle.bitech.dataaction” with the context payload information. You can subscribe to this event and receive the payload in the event callback, and you can make further use of the payload as required.

The following project is embedded inside a HTML page. The project shows the revenue (in Dollars) for lines of business (for example Communication, Digital, Electronics) across organizations (For example fFranchises Org, Inbound Org, International Org) —

Description of revenue-p3-lob-d3-organization.gif follows
Description of the illustration revenue-p3-lob-d3-organization.gif

Event and Payload Format and Context

The following examples enable an event to be published when the embedded data action is invoked by one or more data cells that have been right-clicked and the data action selected from the menu that’s displayed in the embedded project.

The examples below are from a JSON file (for example, obitech-cca/cca/component.json).

Event Format

"events": {
   "oracle.bitech.dataaction": {
      "description": "Generic DV Event published from an embedded data visualization.",
      "bubbles": true,
      "cancelable": false,
      "detail": {
         "eventName": {
         "description": "The name of the published BI Event",
         "type": "string"
      },
      "payload": {
         "description": "The payload contains context and related information to the event published",
         "type": "object"
      }
   }
}

Payload Format

{"context":[
   "or": [
      "and":[
         {"contextParamValues":[...],
          "contextParamValuesKeys":[...],
          "colFormula":"...",
          "displayName":"...",
          "isDoubleColumn":true/false,
          "dataType":"..."
         }
      ]
   ]
 ]
}

Passing a single value for a single column in the Pass By Context

In this example, when you click a column cell, what gets passed is an object with context information about the column. In this case, the organization name is passed.

{
   "context": [
      {
         "contextParamValues": [
            "Inbound Org."
         ],
         "contextParamValuesKeys": [
            "Inbound Org."
         ],
         "colFormula": "\"A - Sample Sales\".\"Offices\".\"D3  Organization\"",
         "displayName": "D3  Organization",
         "isDoubleColumn": false,
         "dataType": "varchar"
      }
   ]
}

Passing a single value for each column in the Pass By Context

In this example, when you click a column cell (for example Inbound Org, and Digital products), what gets passed when you click the Embedded DA1 menu option to select the embedded action is the revenue value in Dollars for the selected line of business and organization. For example, the revenue for Digital products from the Inbound Org is passed, which is $1, 458,738.42 in this example.

Description of pass-value-revenue-p3-lob-d3-organization-02.gif follows
Description of the illustration pass-value-revenue-p3-lob-d3-organization-02.gif
{
   "context": [
      {
         "contextParamValues": [
            "Digital"
         ],
         "contextParamValuesKeys": [
            "Digital"
         ],
         "colFormula": "\"A - Sample Sales\".\"Products\".\"P3  LOB\"",
         "displayName": "P3  LOB",
         "isDoubleColumn": false,
         "dataType": "varchar"
      },
      {
         "contextParamValues": [
            "Inbound Org."
         ],
         "contextParamValuesKeys": [
            "Inbound Org."
         ],
         "colFormula": "\"A - Sample Sales\".\"Offices\".\"D3  Organization\"",
         "displayName": "D3  Organization",
         "isDoubleColumn": false,
         "dataType": "varchar"
      }
   ]
}

Passing multiple values in the Pass By Context

In this example, when you click two row cells (for example Inbound Org and International Org for Digital products) and click the Embedded DA1 menu option to select the embedded action, what gets passed is the revenue value in dollars for the two selected cells for organization and lines of business. For example, clicking the revenue for Digital products from the two selected organizations (Inbound Org and International Org) passes the values $1, 458,738.42, and $915,528.97.

Description of pass-multiple-values-revenue-p3-lob-d3-organization-03.gif follows
Description of the illustration pass-multiple-values-revenue-p3-lob-d3-organization-03.gif
{
   "context": [
      {
         "or": [
            {
               "and": [
                  {
                     "contextParamValues": [
                        "Digital"
                     ],
                     "contextParamValuesKeys": [
                        "Digital"
                     ],
                     "colFormula": "\"A - Sample Sales\".\"Products\".\"P3  LOB\"",
                     "displayName": "P3  LOB",
                     "isDoubleColumn": false,
                     "dataType": "varchar"
                  },
                  {
                     "contextParamValues": [
                        "Inbound Org."
                     ],
                     "contextParamValuesKeys": [
                        "Inbound Org."
                     ],
                     "colFormula": "\"A - Sample Sales\".\"Offices\".\"D3  Organization\"",
                     "displayName": "D3  Organization",
                     "isDoubleColumn": false,
                     "dataType": "varchar"
                  }
               ]
            },
            {
               "and": [
                  {
                     "contextParamValues": [
                        "Digital"
                     ],
                     "contextParamValuesKeys": [
                        "Digital"
                     ],
                     "colFormula": "\"A - Sample Sales\".\"Products\".\"P3  LOB\"",
                     "displayName": "P3  LOB",
                     "isDoubleColumn": false,
                     "dataType": "varchar"
                  },
                  {
                     "contextParamValues": [
                        "International Org."
                     ],
                     "contextParamValuesKeys": [
                        "International Org."
                     ],
                     "colFormula": "\"A - Sample Sales\".\"Offices\".\"D3  Organization\"",
                     "displayName": "D3  Organization",
                     "isDoubleColumn": false,
                     "dataType": "varchar"
                  }
               ]
            }
         ]
      }
   ]
}

Use these steps to configure the sample HTML page shown below.

  1. Add or modify the path location of the project.

    See <======== 1 below.

  2. Subscribe to the published event called ‘oracle.bitech.dataaction’.

    See <======== 2 below.

  3. Define an event listener and an event callback.

    See <======== 3 below.

Example of an HTML Page with Visualization that Receives Events

The following HTML page has a visualization embedded and can receive events. The HTML page is configured to listen for the event “oracle.bitech.dataaction.”

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"><html>
   <head>
      <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
      <title>Standalone DV CCA Demo</title>
      <script src="http://hostname:port/bali/ui/api/v1/plugins/embedding/standalone/embedding.js" type="text/javascript"></script>
   </head>
   <body>
      <h1>Standalone DV CCA Embedded Data Action Demo</h1>
      <div id="mydiv" style="position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)" >
         <oracle-dv project-path="/shared/RR/sample"></oracle-dv>         <=============== 1
      </div>
      <script>
         requirejs(['knockout', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'], function(ko) {
          ko.applyBindings();
         });
           
      </script>
      <script>
         var eventName = 'oracle.bitech.dataaction'; <========== 2
         var element = document.getElementById("mydiv");
         if (element) {
         var oEventListener = element.addEventListener(eventName, function (e) { <================= 3
         console.log("***** Payload from DV ***** ");
         console.log("eventName = " + e.detail.eventName);
         console.log("payload = " + JSON.stringify(e.detail.payload));
         console.log("***** Payload from DV end ***** ");
         }, true);
         }
      </script>
   </body>
</html>