About Data Action Plug-ins and the Data Actions Framework

Data Action Categories

The data action categories include Navigate to URL, HTTP API, Navigate to Canvas, and Event actions:

Navigate to URL: Opens the specified URL in a new browser tab.
HTTP API: Uses the GET/POST/PUT/DELETE/TRACE commands to target an HTTP API and doesn't result in a new tab. Instead the HTTP status code is examined and a transient success or failure message is displayed.
Navigate to Canvas: Enables the user to navigate from a source canvas to a target canvas in either the same or a different visualization. Any filters that are in effect in the source canvas are passed to the target canvas as external filters. When the target canvas opens, it attempts to apply the external filters to the visualization. The mechanism by which external filters are applied isn't described here.
Event Actions: Publishes an event using the Oracle Analytics event router. Any JavaScript code (for example, a third-party plug-in) can subscribe to these events and handle their custom response accordingly. This provides the maximum flexibility because the plug-in developer can choose how the data action responds. For example, they can choose to display a user interface or pass data to multiple services at once.

Both the Navigate to URL and HTTP API data action category types can use a token syntax to inject data or metadata from the visualization into the URL and POST parameters.

URL Token Replacement

HTTP data actions can replace tokens in URLs with values from the context passed to the data action. For example, qualified data reference values, filter values, username, workbook path, and canvas name.

Token	Notes	Replace With	Example	Result
`${valuesForColumn:COLUMN}`	NA	Column display values from the qualified data reference.	`${valuesForColumn: "Sales"."Products"."Brand"}`	`BizTech,FunPod`
`${valuesForColumn:COLUMN, separator:"/"}`	Any token that can potentially be replaced with multiple values supports the optional separator option. The `separator` defaults to a comma (,) but you can set it to any string. You can escape double quotes inside this string by using a backslash (\).	Column display values from the qualified data reference.	`${valuesForColumn: "Sales"."Products"."Brand"}`	`BizTech,FunPod`
`${valuesForColumn:COLUMN, separationStyle:individual}`	Any `separationStyle` defaults to `delimited` but you can set it to `individual` if the user needs to generate separate URL parameters for each value.	Column display values from the qualified data reference.	`&myParam=${valuesForColumn: "Sales"."Products"."Brand"}`	`&myParam=BizTech&myParam=FunPod`
`${keyValuesForColumn:COLUMN}`	NA	Column key values from the qualified data reference.	`${keyValuesForColumn:COLUMN}`	`10001,10002`
`${env:ENV_VAR}`	Supported environment variables are: `sProjectPath`, `sProjectName`, `sCanvasName`, `sUserID`, and `sUserName`.	An environment variable.	`${env:'sUserID'}`	`myUserName`

Data Action Context

You can define a context that is passed when the user invokes a data action.

You define how much of the context is passed to the data action when you create the data action.

Qualified Data Reference

When the data action is invoked a qualified data reference is generated for each marked data point using an array of LogicalFilterTree objects. A LogicalFilterTree consists of multiple LogicalFilterNode objects arranged in a tree structure. This object includes:

The attributes on the row or column edges of the data layout.
The specific measure on the measure edge that addresses each marked cell.
The specific measure value for each marked cell.
Key values and display values.

Environment Variables

In addition to the data and metadata describing each marked data point, certain data actions may need further context describing the environment from where the data action is invoked. Such environment variables include:

Project Path
Project Name
Canvas Name
User ID
User Name

Data Action Code Design

You create data actions using API classes.

There are four concrete classes of data action that inherit from the AbstractDataAction class:
- CanvasDataAction
- URLNavigationDataAction
- HTTPAPIDataAction
- EventDataAction
You can create new types of data actions using the data action plug-in API.
The registry of data action types is managed by the DataActionPluginHandler.
Code that creates, reads, edits, deletes, or invokes instances of data actions does so by publishing events.
Events are handled by the DataActionManager.

Data Action Model Classes

There are several different types of data action model classes.

AbstractDataAction

This class is responsible for:

Storing the Knockout Model (subclasses are free to extend this with their own properties).
Defining the abstract methods that subclasses must implement:
- + invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) <<abstract>>
  Invokes the data action with the passed context - should only be called by the DataActionManager.
- + getGadgetInfos(oReport): AbstractGadgetInfo[] <<abstract>>
  Constructs and returns the GadgetInfos responsible for rendering the user interface fields for editing this type of data action.
- + validate() : DataActionError
  Validates the data action and returns null if valid or a DataActionError if it's invalid.
Providing the default implementation for the following methods used to render generic parts of the data action user interface fields:
- + getSettings():JSON
  Serializes the data action's Knockout Model to JSON ready to be included in the report (uses komapping.toJS(_koModel)).
- + createNameGadgetInfo(oReport) : AbstractGadgetInfo
  Constructs and returns the GadgetInfo that can render the data action's Name field.
- + createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo
  Constructs and returns the GadgetInfo that can render the data action's Anchor To field.
- + createPassValuesGadgetInfo(oReport) : AbstractGadgetInfo
  Constructs and returns the GadgetInfo that can render the data action's Pass Values field.

Subclasses may not need all of the GadgetInfos that the base class provides so they may not need to call all of these methods. By separating out the rendering of each field in this way, subclasses are free to pick and choose the gadgets they need. Some subclasses may even choose to provide a different implementation of these common data action gadgets.

CanvasDataAction, URLNavigationDataAction, HTTPAPIDataAction, EventDataAction

These are the concrete classes for the basic types of data actions. These classes work by themselves to provide the generic user interface for these types of data action. They can also act as convenient base classes for custom data action plug-ins to extend.

CanvasDataAction: Used to navigate to a canvas.
URLNavigationDataAction: Used to open a web page in a new browser window.
HTTPAPIDataAction: Used to make a GET/POST/PUT/DELETE/TRACE request to an HTTP API and handle the HTTP Response programatically.
EventDataAction: Used to publish JavaScript events through the Event Router.

Each class is responsible for:

Implementing the abstract methods from the base class.
- invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
  This method should invoke the data action by combining the properties defined in the KOModel with the specified DataActionContext object.
- getGadgetInfos(oReport): AbstractGadgetInfo[]
  This method should:
  - Create an array containing AbstractGadgetInfos.
  - Call individual createXXXGadgetInfo() methods pushing each AbstractGadgetInfo into the array.
  - Return the array.
Providing the additional methods for creating the individual gadgets that are specific to the particular subclass of data action.

Subclasses of these concrete classes may not need to use all of the gadgets provided by their superclasses in their custom user interfaces. By separating out the construction of each gadget in this way, subclasses are free to pick and choose the gadgets they need.

DataActionKOModel, ValuePassingMode

The DataActionKOModel class provides the base KOModel shared by the different subclasses of AbstractDataAction. See DataActionKOModel Class.

Data Action Service Classes

There are several different data action service classes.

DataActionManager

Description of analytics-data-actions-manager-class-diagram.png follows

Description of the illustration analytics-data-actions-manager-class-diagram.png

All communication with DataActionManager uses ClientEvents.DataActionManager which implements event handlers for:

Managing the set of data actions defined in the current workbook.
Invoking a data action.
Retrieving all the data actions defined in the current workbook.
Retrieving all the data actions that are applicable to the current marked data points.

DataActionContext, EnvironmentContext

When a data action is invoked, the DataActionContext class contains the context that's passed to the target.

getColumnValueMap()
Returns a map of attribute column values keyed by attribute column names. These define the qualified data reference for the data points that the data action is invoked from.
getLogicalFilterTrees()
Returns a LogicalFilterTrees object describing the qualified data references for the specific data points that the data action is invoked from (see the InteractionService for details).
getEnvironmentContext()
An instance of the EnvironmentContext class describing the source environment such as:
- getProjectPath()
- getCanvasName()
- getUserID()
- getUserName()
getReport()
Returns the report that the data action is invoked from.

DataActionHandler

The DataActionHandler class registers the various data action plug-ins. Its API is broadly consistent with the other plug-in handlers (for example, VisualizationHandler).

The DataActionHandler class provides the following public methods:

getClassName(sPluginType:String) : String
Returns the fully qualified class name for the specified data action type.
getDisplayName(sPluginType:String) : String
Returns the translated display name for the specified data action type.
getOrder(sPluginType:String) : Number
Returns a number used to sort lists of the types of data action into the preferred order.

The DataActionHandler class provides the following static methods:

getDependencies(oPluginRegistry:Object) : Object.<String, Array>
Returns a dependency map covering all the registered data action types.
getHandler(oPluginRegistry:Object, sExtensionPointName:String, oConfig:Object) : DataActionPluginHandler
Constructs and returns a new instance of the DataActionHandler class.

DataActionUpgradeHandler

The DataActionUpgradeHandler class is called by the UpgradeService when a report is opened.

The DataActionHandler class provides two main methods:

deferredNeedsUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext) : Promise
Returns a Promise that resolves to a Boolean indicating whether the specified data action must be upgraded (true) or not (false). The method decides whether the data action must be upgraded by comparing the data action instance with the data action's constructor.
performUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext, oUpgradeContext) : Promise
Carries out the upgrade on the specified data action and resolves the Promise. The upgrade itself is carried out by calling the upgrade() method on the data action (only the specific subclass of data action being upgraded is qualified to upgrade itself).
getOrder(sPluginType:String) : Number
Returns a number used to sort lists of the types of data action into the preferred order.

Data Action Code Interactions

A data action interacts with Oracle Analytics code when it creates a user interface field, and when a user invokes a data action.

Create the Field for a New Data Action Instance

This interaction starts when Oracle Analytics wants to render a data action user interface field. To do so, it:

Creates a PanelGadgetInfo that acts as the parent GadgetInfo for the GadgetInfos that the data action returns.
Calls getGadgetInfos() on the data action.
Adds the data action's GadgetInfos as children of the PanelGadgetInfo created in the first step.
Creates the PanelGadgetView that renders the PanelGadgetInfo.
Sets the HTMLElement that's the container of the PanelGadgetView.
Registers the PanelGadgetView as a child HostedComponent of a HostedComponent that's already attached to the HostedComponent tree.
This renders the data action's gadgets inside the Panel gadget in the order they appear in the array returned by getGadgetInfos().

Invoke a Data Action

This interaction starts when the user invokes a data action through the Oracle Analytics user interface (for example, from the context menu on a data point in a visualization).

In response to the user interaction, the code:

Publishes an INVOKE_DATA_ACTION event containing the data action's ID, the DataVisualization that the data action is invoked from, and a TransientVizContext object.
The DataActionManager handles this event by:
1. Obtaining the data action instance from its ID.
2. Obtaining the LogicalFilterTrees for the marked data points in the specified DataVisualization.
3. Constructing a DataActionContext that contains all the information to pass to the data action's target.
4. Calling invoke(oDataActionContext) on the data action.

Example Data Action plugin.xml File

This topic shows an example plugin.xml file for a CanvasDataAction data action.

Example plugin.xml

<?xml version="1.0" encoding="UTF-8"?>
<tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
               xmlns:viz="http://plugin.frameworks.tech.bi.oracle/extension-points/visualization"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               id="obitech-currencyconversion"
               name="Oracle BI Currency Conversion"
               version="0.1.0.@qualifier@"
               optimizable="true"
               optimized="false">
 
 
   <tns:resources>
      <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
      <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
         <tns:extensions>
            <tns:extension name="js" resource-type="script"/>
         </tns:extensions>
      </tns:resource-folder>
   </tns:resources>
 
 
   <tns:extensions>
      <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
         <tns:configuration>
         {
            "resourceBundle": "obitech-currencyconversion/nls/messages",
            "properties":
            {
               "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
               "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
               "order": 100
            }
         }
         </tns:configuration>
      </tns:extension>
   </tns:extensions>
 
 
</tns:obiplugin>

Data Action Plug-in Files and Folders

The following files and folders are used to implement data action plug-ins.

bitech/client/plugins/src/

report
- obitech-report
  - scripts
    - dataaction
      - dataaction.js
      - dataactiongadgets.js
      - dataactionpanel.js
      - dataactionupgradehandler.js
obitech-reportservice
- scripts
  - dataaction
    - dataactionmanager.js
    - dataactionhandler.js