Tools for Creating DeepSee Web Clients
Introduction and Samples
[Back] [Next]
Go to:

This chapter introduces the JavaScript and REST APIs for DeepSee. These APIs let you execute MDX queries and retrieve information about DeepSee model elements. This chapter discusses the following:

Creating a Web Application
In any scenario (whether you use the JavaScript API or you use the REST services directly), a Caché web application is responsible for handling the requests. You can use the system-defined web application (/api/deepsee) or you can create and use a different web application. The requirements for this web application are as follows:
Introduction to the DeepSee JavaScript API
The DeepSee JavaScript API is provided by the file DeepSee.js, which is in the install-dir/CSP/broker directory. This JavaScript library enables you to interact with DeepSee from a client that is based on JavaScript. The functions in this library are a wrapper for a REST-based API for DeepSee. (You can also use the REST API directly; it is introduced later in this chapter.)
To use this library:
  1. Create a web application as described in the previous section.
    Or use the web application /api/deepsee, which is provided as part of the Caché installation.
  2. In your JavaScript client code:
    1. Include the files DeepSee.js and zenCSLM.js. (The latter is a library used by Zen; it is in the same directory.)
    2. Create a DeepSee connection object. This contains information needed to connect to a Caché server.
    3. Create a DeepSee data controller object that uses the connection object.
      The data controller object enables you to interact with a DeepSee data source, which you specify either via an MDX query or via the name of a pivot table.
    4. Use the runQuery() method of the data controller. If the data source is an MDX query, DeepSee executes that query. If the data source is a pivot table, DeepSee executes the query defined by the pivot table.
    5. Invoke other methods of the data controller object to examine the query results, to drill down or drill through, and so on.
    The following subsections give the details.
The library DeepSee.js also provides utility functions that provide information about DeepSee model elements. Use these to obtain lists of available cubes, available measures in a cube, and so on.
Creating a DeepSee Connection
To create a DeepSee connection object, use code like the following:
		connection = new DeepSeeConnection(username,password,host,application,namespace);
Creating and Using a DeepSee Data Controller
The data controller object enables you to interact with DeepSee data sources. The primary interaction is as follows:
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 DeepSee 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:
  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);
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.
Introduction to the DeepSee REST API
Internally, the JavaScript API described earlier in this chapter uses the DeepSee REST API, which you can also use directly. To use the DeepSee REST API:
  1. Create a web application as described in earlier in this chapter.
    Or use the web application /api/deepsee, which is provided as part of the Caché installation.
  2. In your JavaScript client code, create and send HTTP requests to the desired target REST services.
    If you are using the dispatch class %Api.DeepSee, use a target URL of the following form:
    Where baseURL specifies the server, namespace is the target namespace, and RESTcallname is the actual rest call (for example, /Info/Cubes). For example:
    If you are using the dispatch class %DeepSee.REST.v1, use a target URL of the following form:
    For example:
    The client must accept JSON. The Accept header of the request must either specify application/json or not declare a format.
  3. Examine the response objects and use as applicable.
Use of Slashes in Cube and KPI Names
It is relatively common to use slashes (/) in the logical names of DeepSee 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 DeepSee 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:
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:
In order to interpret the slash characters, DeepSee first attempts to find a cube named mycubes and then attempts to find a cube named mycubes/test, and so on. When DeepSee 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:
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):
      {"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:
DeepSee provides samples for the JavaScript library and for the REST API.
Samples That Use DeepSee.js
For samples that use the DeepSee JavaScript library (DeepSee.js), see the directory install-dir/CSP/samples. The sample HTML page testDataController.html demonstrates most of the methods of the JavaScript API. To use this sample, open a URL of the following form in your browser:
Where localhost:57772 is the server and port on which Caché is running.
The sample HTML page test3rdPartyCharts.html demonstrates how to use the API in combination with a third-party charting library. For this sample, use a URL of the following form:
Sample That Uses REST API
For a sample that uses the REST API, open a URL of the following form in your browser:
Where localhost:57772 is the server and port on which Caché is running.
This displays the web page DeepSee.RESTClient, a class in the SAMPLES namespace. This class is a test page that enables you to exercise each REST call within the context of a Caché web application. You can use this page in two ways:
Below these options, the page has a table that lists all the DeepSee REST calls. To try a REST call:
  1. Select the row that corresponds to the call.
    The lower left part of the page then displays details for that call.
  2. If needed, enter values into the labeled input fields (such as :cube). These input fields represent values that are required as part of the URL.
  3. If needed, type the request body into the larger box. Or select Browse... and upload a file that contains the request body.
  4. Press Submit.
  5. If you are prompted for a username and password, enter those and then press Login.
The page then displays the response body in the lower right area. Above the response, the page shows the actual URL that was used.
It is also useful to access the developer tools in your browser and to use them to see the request and response.