Drilling in Web Intelligence reports

To provide drilling functions in Web Intelligence reports you can implement the process described in The drilling process, or use the drill bar to filter the query.

Drilling information

You can access drilling information by examining the contents of the universe (the drill hierarchies and dimensions), or by examining the drill bar.

Drill hierarchies defined in a universe

Use Report.getNamedInterface("DrillInfo") to get the DrillInfo class.

To get the hierarchies used in the report, use DrillInfo.getDrillHierarchies. A hierarchy is used if one of its dimensions is included in the query for the report.

To get the dimensions and details that are not included in a hierarchy but are used in the report, use DrillInfo.getFreeDimensions.

The DrillBlock object gets the drill hierarchies and dimensions for just one block (table or graph) in the report.

Drill bar

DrillBar exposes drill and report filters, and specific drill objects added by the user. A drill object can be a dimension, or a detail.

Defining the drill operation

A drill operation is defined in terms of the drill path. The drill path is represented in REBean by the DrillPath interface, and consists of a set of parameters such as the IDs of the objects (dimensions) from and to which the user is drilling. Defining the drill operation, therefore, involves setting the parameters of the drill path object.

To define the drill operation:

  1. Enter drill mode.
  2. Define the query string parameters, if required.
  3. Get the parameters of the drill request.
  4. Set the drill path.

Entering and leaving drill mode

You need to put Web Intelligence into a special mode so that it can perform the drilling functions. There are two modes: ReportMode.Viewing and ReportMode.Analysis.

Calling DrillInfo.beginDrill puts a report in ReportMode.Analysis (drill) mode. Calling DrillInfo.endDrill stops the drill session and puts a report in ReportMode.Viewing mode.

Defining the query string parameters

In Web Intelligence users drill with hyperlinks and a popup menu, which are generated by Web Intelligence using Javascript functions and style sheets (see Generating the HTML and viewing a drilled report).

You can redefine the query string parameters with the DrillOption class, then use the new names to retrieve the details of the user's drill request and, hence, to set the drill path.

Note:    You cannot change the name and path of the image used to indicate the drill up hyperlinks. This is always ApplicationName/images/cdz/drillup.gif

Example:    Defining the query string parameters

The following JSP code fragment shows how to define the query string parameters used to pass drill information to the Javascript functions that generate the hyperlinks and popup menu, which provide the user with drilling functions.

//set up the query string parameters used for drilling

DrillOption option = info.getDrillOption();

option.setBlockHolder("Block");

option.setBlockSynchronized(true);

option.setCallBackScript("drillHandler.jsp?ReportIdx=0");

option.setCallBackFrame("_self");

option.setDrillActionHolder("Action");

option.setToHolder("To");

option.setFromHolder("From");

option.setFilterHolder("Filter");

option.setHierarchyHolder("Hierarchy");

option.setStorageTokenHolder("Token");

Note:    Notice that you can add your own query string parameters to the call back script definition. Depending on the architecture of your application, and how you manage storage tokens (document state) you might need to include the storage token in the call back script definition. If you do this, remember that drilling methods such as beginDrill and executeDrill generate new tokens for the document.

Getting the parameters of the drill request

To get the parameters of the drill request use request.getParameter and request.getParameterValues. For example:

String token = request.getParameter("Token");

String block = request.getParameter("Block");

String action = request.getParameter("Action");

String[] to = request.getParameterValues("To");

String[] from = request.getParameterValues("From");

String[] hierarchy = request.getParameterValues("Hierarchy");

String[] filter = request.getParameterValues("Filter");

Setting the drill path

The drill path defines the drill operation. To set the drill path:

  1. Get the drill path.
  2. Set the drill action.
  3. See "@@@You have forgotten to tag the text with the Hyperlink Custom Text style." below.

  4. Set the block id.
  5. Set the object id of the drill to element.
  6. Set the object id and filter of the drill from element.
Setting the action: up, down, by, or slice

A user's drill actions are classified by how they move through the drill hierarchies.
Drill actionResulting report engine action

Up

The report engine replaces the current object with its parent in the drill hierarchy.

Down

The report engine replaces the current object with its child in the drill hierarchy.

By

The report engine replaces the current object with an object that is not adjacent to it in the drill hierarchy.

Slice

The report engine adds or removes the filtered values.

 

Different drill actions

You set the drill action with DrillPath.setAction.

The actions are enumerated by DrillActionType.

Setting the from and to parameters

To set the from and to parameters of the drill, you define the elements of the drill. The elements of the drill are the dimensions involved in the drill action and are represented by the DrillElements interface. There is a DrillElements object for the to and for the from dimensions. Individual from and to elements are represented by DrillFromElement and DrillToElement.

For each drill operation:

  1. Get the drill from and to elements with DrillPath.getTo and DrillPath.getFrom.
  2. Add drill elements to each collection.
  3. Set the object IDs of each drill element using the values you retrieve from the query string.
  4. For each from element, set the filter, if any.

Note:    The filter remains for drill-by actions between dimensions in the same hierarchy. However for drill-up actions the filter is removed.

Note:    For example, in the Time Period hierarchy, if you drill down to Quarters from Year = 2003, all the quarters for 2003 are displayed, then if you drill by Year, only Year= 2003 is displayed. However if you drill up from Quarters to Year, all the values for Years are displayed.

Example:    Setting the drill path

The following code fragment shows how to set the values of the drill path. The parameters of the drill (action, from, to, block) are retrieved as described in Getting the parameters of the drill request.

DrillPath drill = info.getDrillPath();

//set the ACTION

if (action.equals("down"))

    drill.setAction(DrillActionType.DOWN);

else if (action.equals("up"))

    drill.setAction(DrillActionType.UP);

else if (action.equals("slice"))

    drill.setAction(DrillActionType.SLICE);

else if (action.equals("by"))

    drill.setAction(DrillActionType.BY);

//set the BLOCK

drill.setBlockID(block);

//set the TO drill elements

if (to.length > 0) {

    DrillElements toElements = drill.getTo();

    for (int j = 0;j < to.length; j++) {

        DrillToElement toElement =

                                    (DrillToElement) toElements.add();

        toElement.setObjectID(to[j]);

    }

}

//set the FROM drill elements

if (from.length > 0) {

    DrillElements fromElements = drill.getFrom();

    for (int k = 0; k < from.length; k++) {

        DrillFromElement fromElement =

                                (DrillFromElement) fromElements.add();

        fromElement.setObjectID(from[k]);

        if ((filter != null) && (filter.length > 0))

                                        fromElement.setFilter(filter[0]);

    }

}

This example assumes that there is only one value in the array filter—fromElement.setFilter(filter[0]). This is true for simple drilling, however, to handle more sophisticated drilling you need to use all the values in the array of filters. Also, in the part that sets the filter, you can add the condition
'if !action.equals("up")' since there is no filtering in a drill-up operation, however, if you set a filter for a drill-up operation, it is ignored.


Generating the HTML and viewing a drilled report

To generate the HTML for the report execute the drill with DrillInfo.executeDrill, then view the generated HTML using HTMLView.getString (see Displaying the drilled report. See also Viewing an individual report in HTML).

In drill mode (ReportMode.Analysis) when you call Report.getView(OutputFormatType.HTML) Web Intelligence generates HTML that uses scripts and style sheets to provide the drilling interface.

Copying the Java script files for drilling

The Java script files used to create the drilling user interface are stored in
/businessobjects/enterprise11/desktoplaunch/viewers/cdz/. Copy the following files from this directory to the same directory as your script that displays the HTML view of the report.

These scripts use the styles defined in bomenu.css and the .gif files in the images folder of wijsp. To get these files, copy the following to the directory containing the copied Java script files:

Referencing the Java script files for drilling

The HTML generated by Report.getView references these files and you need to include this in your header with HTMLView.getString("head", false).

For an example of how to do this, see Displaying the drilled report.

Displaying the drilled report

To display the drilled report, call HTMLView.getStringPart("body", false).

Alternatively you can call HTMLView.getString() which retrieves both the appropriate HTML header and the drilled report, however, it means you can't add supplementary HTML to the page.

Example:    Displaying the drilled report

The following JSP code fragment illustrates how to display a report after executing the drill.

<%

HTMLView objHTMLView = null;

htmlView = (HTMLView) rep.getView(OutputFormatType.HTML);

String htmlHeader = htmlView.getStringPart("head", false);

%>

<html>

    <!-- DRAW HEADER -->

    <head>

        <link rel="stylesheet"

                type="text/css" href="style/bomenu.css">

        <%=htmlHeader%>

    </head>

        <!-- DRAW REPORT-->

        <%=htmlView.getStringPart("body", true)%>

</html>


    Manually handling out of scope drill requests

Once you have set the DrillTo and DrillFrom elements you can detect if a drill dimension is not in scope with DrillDimension.isInScope, and if the defined drill operation contains out of scope dimensions with DrillInfo.willGoOutOfScope.

If the DrillDimension is outside the scope of analysis you can manually extend the scope of analysis with DrillInfo.extendScopeOfAnalysis. This method returns a DrillElements collection to which you can add the extra drill dimensions that the user wants to include in the analysis.

You commit the changes you make to the scope of analysis by calling DrillInfo.executeDrill.

If you want to add a query filter to the extended scope of analysis, use DrillInfo.addQueryConditions. This returns a DrillElements collection to which you can add the ID of the filter dimensions and the associated filter values. You commit this change with DrillInfo.executeDrill. See also, Adding query conditions using the drill bar.

Adding objects that have prompts

If you extend the scope with an object that contains an @Prompt in its universe definition, you need to fill the prompts it raises before you execute the drill. See Handling prompts to find out how to do this.

Filtering with a drill bar

The DrillBar object exposes the drill filters and specific objects added by the user.

By default, the drill bar is initialized with the report filter, but it can be customized by the user to add or remove drill objects. Drill objects can be dimensions, or details.

In the example below, the DrillBar object contains three objects, the Country dimension filtered on the US value, the Resort dimension filtered on the Bahamas Beach value, and the unfiltered Service Line object.

 

You access the drill bar with DrillInfo.getDrillBar, and you add and remove objects to and from the drill bar with DrillBar.add and Drillbar.remove.

Note:    When you remove an object from the drill bar, it is automatically removed from the report filter.

Adding query conditions using the drill bar

You can use the filters in the drill bar to add query conditions when extending the scope of analysis. For example, if the drill bar has the filter Country = US, when the scope is extended you can use this object to form a query condition before executing the SQL. This limits the amount of information returned into the cube to results for Country = US, and is more rapid than retrieving the results for all the values of Country.

The filters set in the drill bar can affect other result objects. For example, if you set the filter Month = February, the results for Quarter are automatically limited to Quarter = Q1; you cannot view the results for Month = February and Quarter = Q3.

Note:    Changing the query affects all the reports in the document. If you add a condition to the query, information in other reports in the document might change.

For more information see Manually handling out of scope drill requests.

Taking a snapshot of a drill

You can use DrillInfo.snapshot to put aside a drilled view and continue drilling. This method adds a report containing the current view to the document's report list and report map.



Business Objects
http://www.businessobjects.com/
Support services
http://www.businessobjects.com/services/support/