Before you Begin

This 15-minute tutorial shows you how to create and install a custom data action plug-in.

Background

Data action plug-ins leverage the data actions framework to provide custom, data-driven actions that are integrated into Oracle Analytics. You develop your custom data action using Oracle Analytics Desktop and then deploy your data action to Oracle Analytics.

In this tutorial, you create a custom data action plug-in that converts currency from one monetary denomination to another, for example, from Euros to US Dollars.

When your content author invokes a data action, the Data Action Manager passes the request context to the data action plug-in responsible for handling the request. For example, in a visualization with a custom data action plug-in, a content author selects a data point, selects the context menu, and then selects your custom data action. The result of the data action appears in the visualization.

When you run the bicreateenv command, the following folder is created to hold the resources for your custom data action plug-in:

  • The value, currencylayer.CurrencyConversionDataAction, reflects the ID you specified when you called bicreateplugin.
  • The nls folder contains the files used to externalize strings so your plug-in can provide National Language Support (NLS). The strings in the files under nls\root act as the default strings to use whenever translations for the requested language aren't available.
  • The message.js file located in the /nls folder is where you should add your plug-in's externalized strings. Add an entry for each language you are supporting with localized strings. Add a corresponding folder under the nls folder for each locale with translations. Each folder must contain the same set of files, with the same file names as those that you added to the default messages.js file located in the nls\root folder.
  • The currencyconversiondataaction.js module contains the starting point for your custom data action.
  • The currencyconversiondataactionstyles.css enables adding CSS styles for use in your data action user interface.
  • The plugin.xml registers your plug-in and its files with Oracle Analytics.

This is the first tutorial in the series, Create and Deploy a Custom Data Action. Read the tutorials in the order listed.

What Do You Need?

  • Access to a Windows development environment
  • Register for an access key with https://currencylayer.com/ for the third-party Currency Conversion HTTP API
  • Download and install Oracle Analytics Desktop

You need a basic understanding of the following:

  • JavaScript
  • RequireJS
  • JQuery
  • KnockoutJS

Generate the Data Action Plug-in Template

In this section, you create a data action from a template. The following commands set up your development environment and populate it with a HTTP API Data Action, called currencylayer.CurrencyConversionDataAction.

  1. At a command prompt, specify the root folder of your Oracle Analytics Desktop installation, for example: 
    set DVDESKTOP_SDK_HOME=C:\Program Files\Oracle Analytics Desktop

    If using Windows command prompt, leave the command prompt open in the background.

  2. Specify the location for storing your custom plug-ins using the following:

    set PLUGIN_DEV_DIR=C:\temp\dv-custom-plugins

    Each plug-in is added to a sub-folder of the specified location.

  3. Add the DV SDK Command Line Tools to your path using:

    set PATH=%DVDESKTOP_SDK_HOME%\tools\bin;%PATH%

  4. Create the folder for the folder used to store the custom plug-ins using the following:

    mkdir %PLUGIN_DEV_DIR%

  5. Change the folder to the folder specified as the storage location for your custom plug-ins using the following:

    cd %PLUGIN_DEV_DIR%

  6. Run the command to create the environment variables using the following:

    bicreateenv

  7. Create the files needed to start developing a custom HTTP API Data Action using the following:
    bicreateplugin -pluginxml dataaction -id currencylayer.CurrencyConversionDataAction -subType httpapi

    The following folders are created:

    %PLUGIN_DEV_DIR%\src\customdataaction
   company-mydataaction\
      extensions\
         oracle.bi.tech.plugin.dataaction\
            company.mydataaction.json
     nls\
         root\
            messages.js
         messages.js
      mydataaction.js
      mydataactionstyles.css
      plugin.xml

Edit the Data Action Knockout Model

In this section, you edit the currencyconversiondataaction.CurrencyConversionDataActionKOModel class. This class stores the metadata for each instance of your data action.

This tutorial exposes the currencylayer API access key in the user interface to make the content authors at your customer companies enter their own access key. Use this approach when you are creating a data action for other companies. If you are creating the data action for your internal users, you don't need to display the API access key field in the user interface.

You must enter your API key for the data action to work.

  1. Locate currencyconversiondataaction.js in C:\<your_folder>\dv-custom-plugins\src\customdataaction\currencylayer-currencyconversiondataaction\.
  2. In the currencyconversiondataaction.CurrencyConversionDataActionKOModel class, remove the sURL, eHTTPMethod, and sPOSTParams arguments from the constructor.
  3. Add the following new arguments the content author needs to provide for the data action.
    • sAPIKey - Stores the API access key assigned to you when you signed up for access to the currencylayer API.
    • eFromCurrency - Stores a default currency code for the source currency.
    • eToCurrency - Stores a default currency code for the target currency.
  4. Pass the static values (sID and sName) to the base constructor for the values that remain the same for all instances of this data action.
  5. Set the default values for the sAPIKey, eFromCurrency, and eToCurrency properties.
  6. Assert that the values for the new arguments are valid. Add public observable properties to the class for each of the properties required by the data action.

    Your knockout model code should look similar to this sample.

Edit the getAJAXOptions() Method

In this section, you edit the getAJAXOptions() method. The method is called when the data action is invoked. It has properties responsible for formulating the HTTP Request to the third-party API and handling the response. You need to call the currencylayer API and handle the JSON response that it returns.

  1. Locate the getAJAXOptions() method in the code: 
    currencyconversiondataaction.CurrencyConversionDataAction.prototype.getAJAXOptions = function (oDataActionContext)
      {
         jsx.assertInstanceOfModule(oDataActionContext, "oDataActionContext", "obitech-reportservices/dataactionmanager", "DataActionContext");
         var oAJAXOptions = currencyconversiondataaction.CurrencyConversionDataAction.superClass.getAJAXOptions.call(this, oDataActionContext);
         // TODO: Modify the properties in oAJAXOptions.
         // Typically, this involves providing custom "success" and "error" functions that are called when the HTTP API has provided a response.
         return oAJAXOptions;
      };
  2. In the getAJAXOptions() method, do the following:
    • Get the AJAX options object from the superclass.
    • Get the selected data-point value to convert.
    • Provide a new success function that handles the response from the currencylayer API, performs the currency conversion on the selected data-point value, and displays the result on the screen.

    After editing the getAJAXOptions() method, your getAJAXOptions code should look similar to this sample.

Edit the getGadgetInfos() Method

The getGadgetInfos() method provides an array of the GadgetInfos used by the data actions dialog to display the user interface elements required for creating and editing this type of data action. The GadgetInfos for data action Name, AnchorToColumns, and PassValuesColumns gadgets are provided by the superclass.

You need to add these gadgets to enable the content author to enter the following data action properties:

  • currencylayer API Access Key
  • From Currency Code
  • To Currency Code

Use code similar to this sample.

Edit the Data Action Dependencies

In the previous section, you created code that depends on some other modules that aren't loaded by your data action plug-in. You need to edit the list of required modules found at the top of the currencyconversiondataaction.js file to add these module dependencies:

  • obitech-application/gadgets
  • obitech-application/extendable-ui-definitions

This code uses the RequireJS API to load dependencies. The define() method is part of the RequireJS API.

Locate the define() in the currencyconversiondataaction.js, and then add obitech-application/gadgets, and obitech-application/extendable-ui-definitions to the list of arguments.

Your dependencies code should look similar to this sample.

Edit the Data Action's validate() Method

When the content author clicks OK in the Data Actions dialog, the validate() method is called. The method returns a DataActionError if the data action properties is incorrect, or NULL if the data action is valid.

In this section, you add code to validate the API access key to ensure that it isn't missing. Use the key that was provided when you registered to use the currency conversion API.

  1. Locate currencyconversiondataaction.CurrencyConversionDataAction.prototype.validate = function() in the currencyconversiondataaction.js file.
  2. Add the validate() code similar to this sample.

    Your edited currencyconversiondataaction.js file should look similar to this sample.

Edit messages.js

In this section, create messages for the three strings used to introduce the fields added to the data action user interface and the string used by the error message in the validate() method:

  • API_KEY
  • FROM_CURRENCY
  • TO_CURRENCY
  • errors.MISSING_API_KEY
  1. Open the messages.js file located in C:\Temp\dv-custom-plugins\src\customdataaction\currencylayer-currencyconversiondataaction\nls\root.
  2. Edit your code to look similar to the following:
    define({
   "API_KEY": "CurrencyLayer API Key",
   "FROM_CURRENCY": "From Currency",
   "TO_CURRENCY": "To Currency",
   "CURRENCYCONVERSIONDATAACTION_DISPLAY_NAME": "Currency Conversion",
   "CURRENCYCONVERSIONDATAACTION_SHORT_DISPLAY_NAME": "Currency Conversion",
   errors: {
      "MISSING_API_KEY": "The API Key is missing for Currency Conversion Data Action: {0}"
   }
});

Test Your Data Action

In this section, you use Oracle Analytics Desktop to test your data action from its source location without installing it.

  1. Close Oracle Analytics Desktop, if it's running.
  2. Run Oracle Analytics Desktop in SDK mode using the following command:
    
    cd %PLUGIN_DEV_DIR%
    .\gradlew run
  3. Create a project to test your plug-in.

Learn More