Using Business Intelligence

Creating a Business Intelligence Connection

To create a Business Intelligence connection object, use code like the following:

connection = new DeepSeeConnection(username,password,host,application,namespace);

Where:

• username is an InterSystems IRIS username that can access the given host.

• password is the associated password.

• host is the server name for the machine on which InterSystems IRIS is running.

• application is the name of the web application.

• namespace is the name of the namespace to access. If the web application is tied to a namespace, this argument is not needed.

Creating and Using a Business Intelligence Data Controller

The data controller object enables you to interact with Business Intelligence data sources. The primary interaction is as follows:

• In a suitable part of the page logic (such as when the page is loaded or when a button is pressed), create a Business Intelligence data controller and execute a query.

  When you create a data controller, you specify one or two callback functions to be run when data is available; finalCallback is required, but pendingCallback is optional.

• When pending results are available, Business Intelligence calls the method specified by pendingCallback, if specified.

  This method, which you write, uses the results that are available in the data controller object. The method typically draws page contents.

• When the query has completed, Business Intelligence calls the method specified by finalCallback.

  This method, which you write, uses the results that are available in the data controller object. The method typically draws page contents.

Any method that executes a query uses the system described here; see the subsections for details and examples. Other methods return data synchronously.

Creating a Business Intelligence Data Controller and Executing a Query

In a suitable part of the client code (such as within the page initialization logic), do the following:

1. Create a configuration object that has the following properties:

   • connection — Specifies the name of a Business Intelligence data connector object; see the previous section.

   • widget — Specifies the id of the HTML element on the page that will use the data controller

   • type — Specifies the type of data source; use either 'MDX' or 'PIVOT'

   • initialMDX — Specifies an MDX SELECT query; use this if type is 'MDX'

   • pivotName — Specifies the logical name of a pivot table; use this if type is 'PIVOT'

   • showTotals — Specifies whether to display totals. Specify either true or false

2. Create a data controller object with code like the following:

   var dc = new DeepSeeDataController(configuration,finalCallback,pendingCallback);
   

   

   Where configuration is the configuration object from the previous step, finalCallback is the name of a callback function on this page, and pendingCallback is the name of another callback function on this page. finalCallback is required, but pendingCallback is optional.

3. Call the runQuery() method of the data controller. Or run some other method that executes a query, such as runDrillDown() or runListing().

For example:

function initializePage() {
               ...
                    configuration.connection = new DeepSeeConnection(username,password,host,application,namespace);
                    dc = new DeepSeeDataController(configuration,drawChart);
                    dc.runQuery();
            }

Using Data Returned by the Data Controller

The page must also implement the callback function or functions referred to in the previous step. These callbacks should update the page as needed, using data obtained from the data controller object.

In each case, the data controller object is passed to the function as the argument.

The following shows a partial example:

function drawChart(dataController) {

    var resultSet = dataController.getCurrentData();
    ...
    var chartDataPoint;
    var chartLabel;
    var chartData = [];

    for (var i = 1; i <= resultSet.getRowCount(); ++i) {
        for (var j = 1; j <= resultSet.getColumnCount(); ++j) {
            chartDataPoint = resultSet.getOrdinalValue(i,j);
            chartLabel = resultSet.getOrdinalLabel(2,i);
            chartData[chartData.length] = { "country":chartLabel[0],"revenue":chartDataPoint};
        }
    }
    ...

The getCurrentData() method of the data controller returns another object, the result set object. That object provides methods for examining the results of the query. The example here shows some of them.

Use of Slashes in Cube and KPI Names

It is relatively common to use slashes (/) in the logical names of cubes and other items, because the slash character is the token that separates a folder name from a short item name. For example, a cube might have the logical name RelatedCubes/Patients

You can directly use these logical names unmodified in URL parameters (as well as in the request bodies). The applicable Business Intelligence REST services account for logical names that include slashes. The logic, however, requires you to follow a naming convention (depending on which REST services you plan to use). Specifically, do not have an item with a logical name that is the same as the name of a folder used by another logical name. For example, if you have an item called mycubes/test/test1, you should not have an item called mycubes/test.

The reason for this restriction is that when you use a REST service that uses another argument after the logical name, part of the name is interpreted as another argument if the first part of the name matches an existing item. Consider the following REST call:

https://localhost/api/deepsee/v1/Info/FilterMembers/:mycubename/:filterspec

Here mycubename is the logical name of a cube and filterspec is the specification for a filter provided by that cube. Now consider this REST call with mycubes/test/test1 as the name of the cube:

https://localhost/api/deepsee/v1/Info/FilterMembers/:mycubes/test/test1/:filterspec

In order to interpret the slash characters, the system first attempts to find a cube named mycubes and then attempts to find a cube named mycubes/test, and so on. When the system finds the first item that matches the apparent name, the REST call uses that item, and the remainder of the string is interpreted as the next argument.

Notes on the Response Objects

For most of the REST calls, the response objects contain the property Info, which contains information about the request and response. This object contains the property Error, which equals one of the following:

• Null — This indicates that no error occurred.

• An object that contains the properties ErrorCode and ErrorMessage — This object contains details about the error that you can use to determine whether and how to proceed.

If no error occurred, the response object also contains the property Result, which is an object containing the requested values.

In general, your client code should first check the Info.Error property and then determine how to proceed.

For example, a response object might look like this (with white space added for readability):

{"Info":
            {"Error":
                {"ErrorCode":"5001","ErrorMessage":"ERROR #5001: Cannot find Subject Area: 'SampleCube'"}
            }
        }

In contrast, if no error occurred, the Info.Error property is null and the Result contains the result that you requested. For example:

{"Info":
            {"Error":"",
            "BaseCube":"DemoMDX",
            "SkipCalculated":0},
            "Result":
            {"Measures":
                [
                    {"name":"%COUNT","caption":"%COUNT","type":"integer","hidden":0,"factName":""},
                    {"name":"Age","caption":"Age","type":"integer","hidden":0,"factName":"MxAge"}
                ...]
            }
        }