Customizing Webintelligence En

Customizing Web Intelligence with REBean

BusinessObjects Enterprise XI

Windows and UNIX

Copyright If you find any problems with this documentation, please report them to Business Objects S.A. in writing at [email protected] © Business Objects S.A. 2004. All rights reserved.

Trademarks Business Objects, the Business Objects logo, Crystal Reports, and Crystal Enterprise are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the United States and other countries. All other names mentioned herein may be trademarks of their respective owners.

Patents Business Objects owns the following U.S. patents, which may cover products that are offered and sold by Business Objects: 5,555,403, 6,247,008 B1, 6,578,027 B2, 6,490,593 and 6,289,352.

Contents
Chapter 1 Introduction 7
Chapter 2 Introduction to WebIntelligence SDK 9Packages for customizing WebIntelligence . . . . . . . . . . . . . . . . . . . . . . . . 10Migrating to BusinessObjects XI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11A typical Web Intelligence SDK application . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3 Application Essentials 15“Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16BusinessObjects Enterprise sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Implementing “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22User preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Reporting essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 4 Document Management 33Document types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Document state: storage tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Organizing documents in categories and folders . . . . . . . . . . . . . . . . . . . . 39Working with documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Document properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 5 Viewing Web Intelligence Reports 61Viewing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Handling prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Displaying a report map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 6 Drilling in Web Intelligence Reports 79Introduction to drilling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Drilling in Web Intelligence reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Customizing Web Intelligence 3

Chapter 7 Building and Editing Data Providers 91

Data providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Building a data provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Executing queries and retrieving the data . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 8 Formatting Reports 103Creating and editing the document structure . . . . . . . . . . . . . . . . . . . . . . 104Creating and editing cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Page layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Appendix A Working with Recordsets 119Anatomy of a recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Appendix B Business Objects Information Resources 123Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Customer support, consulting and training . . . . . . . . . . . . . . . . . . . . . . . . 125Useful addresses at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127


Examples
Referencing BusinessObjects Enterprise SDK 17Instantiating the ISessionMgr class 18HTML form for gathering a user’s login information 19Establishing a session 20Printing a user’s preferences 26Setting a user’s report panel preference to Java 28Adding a new preference to a user’s profile 29Importing the REBean package 31Instantiating a ReportEngine object 31Storage token life cycle 36how to check that a user has the right to create categories 40Recursively traversing the category tree 41Retrieve a user’s Inbox and Favorites folder IDs 43Creating a new folder or category 45Moving and renaming categories or folders 46Retrieve the properties for a category 46Displaying a document list 49Save a Web Intelligence document 50Scheduling a document 51Retrieve the list of groups to which a user belongs 52Sending a document to folders and categories 53Send a document to the inbox of groups of users 55Getting the name of a Web Intelligence document using REBean 58Adding a property to a Web Intelligence document 58Viewing all the reports in a Web Intelligence document 63Viewing a report in a Web Intelligence document 63Viewing a report in Microsoft Excel format 64Handling a single, simple prompt 66Dynamically creating input names 68

Examples

Handling many, simple prompts 68Displaying a simple list of values 70Handling multivalued prompts 72Handling multicolumn lists of values 72Order of filling a hierarchy of nested prompts 74Handling nested prompts 74Refreshing a list of values containing nested prompts 75Traversing the report map for a Web Intelligence document 77Defining the query string parameters 84Setting the drill path 86Displaying the drilled report 88Launching the Web Intelligence Java Report Panel 96Building a data provider 98Creating a simple condition 100Structure of a complex condition 101Including a prompt in a condition 101Creating a blank document 104Creating a document structure 107Creating an attachment 109Editing the sections of a report 109Building a report: adding expressions to axes 112Accessing the values in a recordset 121

6 Customizing Web Intelligence

Customizing Web Intelligence

Introduction

chapter

IntroductionAbout this guide1
About this guide
This guide describes the processes and procedures for creating web applications using BusinessObjects Enterprise SDK and the Web Intelligence Report Engine SDK REBean package.

Who should read this guideTo use the BusinessObjects Enterprise SDK and Web Intelligence Report Engine SDKs you need a working knowledge of the concepts of distributed computing systems, HTTP server technology, and JSP development. You also need a basic knowledge of the products in the BusinessObjects product line. Familiarity with Web Intelligence is assumed.

Business Objects information resourcesFor more information and assistance, see “Business Objects Information Resources” on page 123. This appendix describes the Business Objects documentation, customer support, training, and consulting services, with links to online resources.



Introduction to WebIntelligence SDK

chapter

1
Overview
WebIntelligence SDK consists of a number of Java packages. Typically, every application that uses these packages must implement the same kinds of workflows.This chapter briefly introduces WebIntelligence SDK and the workflows a typical application needs to implement.

Packages for customizing WebIntelligenceThere are four packages for customizing Web Intelligence:• Web Intelligence SDK

You use Web Intelligence SDK to customize Web Intelligence.• BusinessObjects Enterprise SDK

The "platform package," provides platform functions of the Business Objects servers, and document scheduling.

• Web Intelligence Report Engine SDKThis package plugs into Business Objects Enterprise SDK. It provides the functions of the Web Intelligence Report Engine.

BusinessObjects Enterprise SDK is called the platform package because it exposes the platform functions of the Business Objects servers. Web Intelligence Report Engine exposes the functions of the Web Intelligence Report Engine.

Web Intelligence documents

Metadata (universe)

ViewRefreshAnalyze

Explore†

Create†

Format†

Web Intelligence SDK

Crystal Enterprise DocumentsViewRefreshAnalyze

BusinessObjects Enterprise SDK

Platform functionsManage sessions and usersManage documents and categoriesList universes, documentsSchedule


1
Migrating to BusinessObjects XI
If you already have a business intelligence solution based on previous versions of Developer Suite you might need to migrate your solution. Migration affects the following areas:• referencing components of the Business Objects platform• controlling user sessions• listing and navigating through folders and categories• managing and viewing documents• handling security commands• using the various dictionaries• deploying your application

For more information on migration issues see the Migrating Business Objects 6 Customized Applications to BusinessObjects XI guide.

A typical Web Intelligence SDK applicationNot all applications that use Web Intelligence SDK have the same features, but all typically provide features for listing documents in the BusinessObjects Enterprise Central Management System (CMS) and viewing documents. A more sophisticated application could also include features such as document creation and report formatting.

Application essentialsEvery application that uses Web Intelligence SDK needs to perform a few common tasks such as importing the appropriate Java packages, and creating and managing the user’s BusinessObjects Enterprise session (login).While it is not absolutely necessary, every application should also take user profiles into account and ensure that errors are handled properly. See “User rights for categories and folders” on page 39 and “User preferences” on page 25.

Document managementDocument management features include the ability to list the documents that the current user can view, and, depending on the user’s rights, allowing the user to browse and manage categories and folders used to organize the documents.


1
Document management can also include features such as saving, and scheduling documents.
Viewing reportsAn application that provides a feature for viewing reports can display reports using the default HTML format. It is easy to extend this to handle reports that contain prompts, and to provide drilling functions. These extended functions have to be handled when a document is refreshed.How you provide these viewing features depends on the type of document. The report-viewing part of the application should include routines for viewing reports in the following document types:• Web Intelligence (*.wid)• Crystal Reports documents

• other document types, for example Adobe® Acrobat®, Microsoft® Excel or XML format.

Creating documents: building and editing data providersTo give users the ability to create documents and generate their own reports, you need to provide them with tools to build and edit data providers.A data provider encapsulates information about the information source and the query that defines what information is retrieved. Creating a document essentially means creating a data provider. You can use the same classes to provide different features for editing a query, such as adding conditions and changing the scope of analysis.

Formatting documentsFormatting documents involves creating and positioning the elements of a report (blocks, sections, and cells) in the appropriate document structure. Using Web Intelligence Report Engine SDK you can build reports from scratch.Web Intelligence Report Engine SDK also includes classes for controlling the page decoration (fonts, colors, headers, and footers) and page layout of a report.

Example workflowsInfoView is implemented using BusinessObjects Enterprise SDK and Web Intelligence SDK. The Web Intelligence InfoView viewer interface has three zones:• the document tool bar, which shows the user’s position in the document


1
• the report map, which shows the structure of a report• the rendering area, which is where reports are displayed
The pages manage these zones in sequence. First the document is opened, the prompts are filled and the position is set, then the report map is populated and finally the report is rendered and displayed.

Open document workflowThe following diagram shows the workflow for opening a document.

open a documentcheck for prompts

fill prompts until there are none left unfilled

get the report map

get the report in the requested format

fill document toolbar

Client pages

fill report map

fill rendering area



1
Refresh document workflow
The following diagram shows the workflow for refreshing a document.

<open document workflow>

check for promptsfill prompts until there are none left unfilled

get the report map

get the report in the requested format

set the position

refresh the report

refresh

fill document toolbar

fill report map

fill rendering area

update document

toolbar

Client pages




Application Essentials

chapter

2
Overview
Before providing viewing, reporting, and editing functions Web Intelligence SDK applications need to perform basic tasks, such as referencing the appropriate package and creating a BusinessObjects Enterprise session for the user.This chapter covers the essential concepts and tasks that all applications that customize Web Intelligence must use.

“Hello World”The simplest application you can write with Web Intelligence SDK is one that creates a BusinessObjects Enterprise session, that is, provides log in and log out functions.You can use this as a basis for building much more sophisticated applications that provide, for example, functions to list, view and create documents, and publish them in hierarchical categories.

Table 2-1 Application for logging in and out of BusinessObjects EnterpriseThis application gathers login details from the user, and sends the details to another page which uses BusinessObjects Enterprise SDK to try to open a BusinessObjects Enterprise session. If the session is successfully created, the application displays a “Hello World” message and the option to log out. When

open a session

get name and password from user

display “Hello World” and a logout link

close session

Name = “janderson”

Pass = “*******”


2
the user clicks the logout link, the application closes the user’s BusinessObjects Enterprise session with BusinessObjects Enterprise SDK and displays the first page again.Each page that uses BusinessObjects Enterprise SDK must:• reference BusinessObjects Enterprise SDK• create or reference an IEnterpriseSession object• create or reference an IInfoStore object
See “Implementing “Hello World”” on page 22 for code that implements this application.

Referencing BusinessObjects Enterprise SDKReferencing BusinessObjects Enterprise SDK gives your web application access to the Web Intelligence platform functions exposed by the SDK. Note: You must use BusinessObjects Enterprise SDK prior to using Web Intelligence Report Engine SDK.

Referencing BusinessObjects Enterprise SDKTo reference BusinessObjects Enterprise SDK, import the BusinessObjects Enterprise packages.Example: Referencing BusinessObjects Enterprise SDKTo import BusinessObjects Enterprise SDK packages, add the following line to JSP pages that use the packages.<% page import="com.crystaldecisions.sdk.framework.*,

com.crystaldecisions.sdk.occa.infostore.*,com.crystaldecisions.sdk.occa.pluginmgr.*,com.crystaldecisions.sdk.plugin.*,com.crystaldecisions.sdk.plugin.desktop.server.*,com.crystaldecisions.sdk.occa.infostore.*,com.crystaldecisions.sdk.plugin.destination.smtp.*,com.crystaldecisions.sdk.plugin.destination.managed.*,com.crystaldecisions.sdk.exception.SDKException,com.crystaldecisions.sdk.occa.security.*,com.crystaldecisions.sdk.plugin.desktop.user.*,com.crystaldecisions.sdk.properties.*,

com.businessobjects.sdk.plugin.desktop.webintelligence.CeWebIntelligenceRightID,com.businessobjects.rebean.wi.*"%>

You need to include this line in every page that uses BusinessObjects Enterprise SDK.


2
Creating an new user session
In BusinessObjects Enterprise SDK the ISessionMgr lets a user to log in to the BusinessObjects Enterprise server and create a session. Session information is stored in the IEnterpriseSession object returned by this method. Every session has a corresponding IEnterpriseSession object which is used to access Web Intelligence SDK.

Creating a ISessionMgr objectTo create a ISessionMgr object for an application that uses BusinessObjects Enterprise SDK, instantiate a new ISessionMgr object.Example: Instantiating the ISessionMgr classISessionMgr mySessionMgr =

CrystalEnterprise.getSessionMgr();

BusinessObjects Enterprise sessionsEvery user of Web Intelligence requires a BusinessObjects Enterprise session before entering and using the system. The BusinessObjects Enterprise session represents the user’s current interaction with BusinessObjects Enterprise. A user’s BusinessObjects Enterprise session provides access to the user’s details, and objects that are subject to the rights of the user, for example, the list of universes that the current user can use to create documents.You must create a BusinessObjects Enterprise session for the user: it is the key part of the log in and authentication process.To create a session for a user:1. Get the user’s login information:

• name• password• the Central Management System (CMS) the user wishes to log into• authentication type (Enterprise or LDAP)

2. Establish a valid BusinessObjects Enterprise session for the user.

Getting login informationThe simplest way to get a user’s login information is to use an HTML form into which the user enters a name and a password. When the user submits the form, the values for the fields are passed via the query string to a page that processes the values.


2
Example: HTML form for gathering a user’s login information<FORM name="LoginForm" action="Login.jsp" method="POST">
<TABLE><TR><TD>Name:</TD><TD><input name="Name"></TD>

</TR><TR>

<TD>Password:</TD><TD><input type="password" name="pass"></TD>

</TR><TR>

<TD>Central Management System:</TD><TD><input name="CMS"></TD>

</TR><TR>

<TD>Authentication:</TD><TD>

<select name='auth'><option value='secEnterprise'>Enterprise</

option><option value='secLDAP'>LDAP</option>

</select></TD>

</TR><TR>

<TD><input id=submit1 name=submit1type=submit value="Login"></TD>

</TR></TABLE></FORM>

Note: When the user enters login information and clicks the Login button, the values for the fields are passed to Login.jsp in the query string parameters Name and Pass. Since the method attribute of the form is set to POST, these values will not be visible in the URL.

AuthenticationThe way you monitor passwords depends on how BusinessObjects Enterprise passwords have been set up by the BusinessObjects Enterprise system administrator.There are two settings available to the system administrator which you can use as the basis for the login procedure in your own application:• Enterprise Mode

This mode requires from the user to submit a user name and password which are unique to BusinessObjects Enterprise (and may be different from their network name/password combination).


2
• LDAP Mode
This mode requires the user to submit a user name and password which are stored on a corporate LDAP server.

For more information on authentication in Windows, see the BusinessObjects Enterprise XI Administrator’s Guide.

Establishing a valid BusinessObjects Enterprise user’s sessionTo establish a valid BusinessObjects Enterprise user’s session:1. Try to create an IEnterpriseSession object for the user.2. If the IEnterpriseSession object is valid, store this object in the user’s

session attributes.3. Create an IInfoStore object and store in the user’s session attributes.These steps are usually done together and are normally followed by redirecting the user to an appropriate page: a welcome page or back to the login page, depending on the validity of the session.

Example: Establishing a sessionThe following code fragment illustrates how to establish a BusinessObjects Enterprise session using J2EE.ISessionMgr mySessionMgr =

CrystalEnterprise.getSessionMgr();IEnterpriseSession eSession;try {

eSession = mySessionMgr.logon(name, password, CMS, auth);if (eSession != null){

session.setAttribute("EnterpriseSession",enterpriseSession);

IInfoStore iStore = (IInfoStore)enterpriseSession.getService("InfoStore");

session.setAttribute("InfoStore", iStore);} catch (SDKException sdkEx){

;}

Retrieving a BusinessObjects Enterprise sessionOnce you have established a valid BusinessObjects Enterprise session for the user, you can retrieve it from the user’s session attributes.

Closing a BusinessObjects Enterprise sessionTo close a session, that is, log a user out of BusinessObjects Enterprise, use IEnterpriseSession.logoff.


2
Closing a session is important: • It frees the resources held by the user’s BusinessObjects Enterprise
session.• It forces other users to start their own sessions rather than just taking

over an existing session.Note: See “logout.jsp” on page 24 for an example of how to close a BusinessObjects Enterprise session.

BusinessObjects Enterprise session time-outBusinessObjects Enterprise sessions have a time-out value which determines the number of seconds users can be inactive before their sessions are automatically closed. The BusinessObjects system administrator sets the time-out.Note: If the session time-out of the application server hosting the web application is less than the BusinessObjects Enterprise session time-out:• The user’s JSP page will not have access to objects such as

IInfoStore stored in the user’s application server session variables.• Session objects created on the BusinessObjects Enterprise server will

not be liberated correctly. This will degrade server performance.


2
Implementing “Hello World”
Following is an implementation of the Hello World application discussed on page 16. To run this application you need to have installed BusinessObjects Enterprise and established a Business Objects Central Management System. For more information, see the Installation and Configuration Guide for Windows or UNIX.

In this implementation index.jsp displays a form which collects the user’s login information which is passed to login.jsp. Login.jsp attempts to create a session and IInfoObject for the user. If the operation is successful, login.jsp redirects to home.html which displays the “Hello World” message and a link to logout.jsp. When the user clicks the logout link, logout.jsp closes the session and displays index.jsp again.

index.jsp<html><body><h1>Create a BusinessObjects Enterprise Session</h1><form name="LoginForm" action="login.jsp" method="POST">

<table><tr><td>Name: </td><td><input name="Name"></td>

</tr><tr>

<td>Password: </td><td><input type="password" name="Pass"></td>

</tr><TR>

<TD>Crystal Management System:</TD>

Name = “janderson”

Pass = “********”

index.jsp login.jsp

logout.jsp home.html


2
<TD><input name="CMS"></TD>
</TR><TR>

<TD>Authentication:</TD><TD>

<select name='auth'><option value='secEnterprise'>Enterprise</

option><option value='secLDAP'>LDAP</option>

</select></TD>

</TR><tr>

<td><input id=s1 name=s1 type=submit value="Login"></td></tr></table>

</form></body></html>

login.jspThis page is opened when the user clicks Login in the form LoginForm described on page 19. The user name and password used for the login are passed from the HTML form in the query string parameters Name and Pass.<%@ page

import="com.crystaldecisions.sdk.framework.CrystalEnterprise" %>

<%@ page import="com.crystaldecisions.sdk.framework.IEnterpriseSession" %>

<%@ page import="com.crystaldecisions.sdk.framework.ISessionMgr" %>

<%@ page import="com.crystaldecisions.sdk.exception.SDKException" %>

<%@ page import="com.businessobjects.rebean.wi.*" %><%

String CMS = request.getParameter("CMS");String userID = request.getParameter("Name");String password = request.getParameter("pass");String auth = request.getParameter("auth");

if ( CMS == null) CMS = "";if ( userID == null) userID = "";if ( password == null) password = "";if ( auth == null) auth = "";

IEnterpriseSession enterpriseSession;try{

ISessionMgr mySessionMgr =CrystalEnterprise.getSessionMgr();


2
enterpriseSession =
mySessionMgr.logon(userID, password, CMS,auth);if (enterpriseSession != null){//Create and store useful objects for the session.

session.setAttribute("EnterpriseSession",enterpriseSession);

IInfoStore iStore = (IInfoStore)enterpriseSession.getService("InfoStore");

session.setAttribute("InfoStore", iStore); response.sendRedirect("home.html");

}else response.sendRedirect("index.jsp");

}catch( SDKException mySDKExept){

response.sendRedirect("index.jsp");}

%>

home.html<html><body><h1>Create a Web Intelligence Session: Home Page</h1><p>Hello World!</p><a href="logout.jsp">Log out</a></body></html>

logout.jsp<%@ page

import="com.crystaldecisions.sdk.framework.IEnterpriseSession" %>

<%IEnterpriseSession enterpriseSession;enterpriseSession =(IEnterpriseSession)

session.getAttribute("EnterpriseSession");session.removeAttribute("EnterpriseSession");if(enterpriseSession != null){

enterpriseSession.logoff();enterpriseSession = null;

}%>


2
User preferences
Users can set their InfoView and Web Intelligence Report Engine viewing options using the Preferences page.When designing a Web Intelligence SDK application you should take this into account. For example, if the user wants to use the Java version of the Report Panel for creating and editing documents then you need to design your application so that it can display the Java Report Panel rather than the HTML Report Panel.

Accessing Web Intelligence user preferencesWith BusinessObjects Enterprise SDK you can get, set and add new preferences in a user’s profile. Standard preferences and possible settings are:Web Intelligence standard user preference variables, values and meaning.

Variable Name Possible Values

Meaning

webi_view P View documents in PDF format.

I View Documents in Interactive format.

H View Documents in HTML format.(default)

webi_panel java Create documents using the Java Report Panel.(default)

html Create documents using the HTML Report Panel.

DOCUMENT_WIStartNewDrill duplicate Start the drill action in a duplicate report.

existing Start the Drill action in the current report. (default)


2

Note: other applications may have their own user settings which are stored in the user profile. For more information see “Adding custom options to a user’s profile” on page 29.

Getting a user’s Web Intelligence preferencesTo read the value of a user’s option:1. Get the current user’s IUser object using an IInfoStore query.2. Get the "desktopsettings" profile string.3. Convert the profile string to a Map for easy manipulation and printing.Example: Printing a user’s preferencesThe following JSP code functions show how to retrieve a user’s Web Intelligence preferences and print them to an HTML response stream.<%!//Return a string containing a user’s Web Intelligence

PreferencesString getWebiPrefs(IInfoStore iStore, int uId){

String prefs = "";String sQuery = "SELECT SI_ID, SI_NAME, SI_DATA FROM”

+ “ CI_SYSTEMOBJECTS WHERE SI_ID = '" + uId + "'";

IInfoObjects users = null; try{

users = iStore.query(sQuery);if (users.size() > 0){

IUser user = (IUser)users.iterator().next();

DOCUMENT_WIPromptDrillOutScope N Prompt if drill requires additional data.(default)

Y Do not prompt if Drill requires additional data.

DOCUMENT_WISyncDrillBlocks N Synchronize Drill on report blocks.(default)

Y Do not Synchronize Drill on report blocks.

DOCUMENT_WIDrillBar N Show the Drill bar.Y Hide the Drill bar.

(default)

Variable Name Possible Values

Meaning


2
prefs = user.getProfileString("desktopsettings");
}}catch(SDKException sEx){

return ““;}return prefs;

}//Convert a String of preferences to a MapMap webiPrefsToMap(String prefs){ StringTokenizer st = new StringTokenizer (prefs, "&"); Map webiPrefs = null; while (st.hasMoreTokens()) { String s2 = st.nextToken(); StringTokenizer st2 = new StringTokenizer (s2, "="); if (st2.countTokens() == 2) webiPrefs.put(st2.nextToken(), st2.nextToken()); } return webiPrefs;}%>

The following code fragment shows how to use the functions declared above to print a user’s Web Intelligence preferences to an HTML stream.<%int userID = myIEnterpriseSession.getUserInfo().getUserID();PrintWriter myWriter = response.getWriter();String prefs = getWebiPrefs(myIInfoStore, userID);Map prefsMap = webiPrefsToMap(prefs);if (prefsMap != null){

Iterator itr = prefsMap.entrySet().iterator();while(itr.hasNext()) {

Map.Entry current = (Map.Entry)itr.next();myWriter.print (

current.getKey() + "=" + current.getValue() + "<br>");

}}%>


2
Setting an option in a user profile
To set an option:1. Get a user’s preferences.2. Update a standard option in the Map continuing the user preferences.3. Convert the Map to a String. 4. Update the user profile with IInfoStore.commit.Example: Setting a user’s report panel preference to JavaThe following JSP code functions enables a user’s profile to be updated to use the Java Report Panel.<%!//Update the user’s Web Intelligence preferences.void setWebiPrefs(IInfoStore iStore, String prefs, int uId){

String sQuery = "SELECT SI_ID, SI_NAME, SI_DATA FROM CI_SYSTEMOBJECTS WHERE SI_ID = '"

+ uId + "'";IInfoObjects users = null; try{

users = iStore.query(sQuery);if (users.size() > 0){

IUser user = (IUser)users.iterator().next();user.setProfileString("desktopsettings", prefs);iStore.commit(users);

}}catch(SDKException sEx){

;}

}

//Convert a preferences Map to a stringString webiPrefsToSting(Map wPrefs){ StringBuffer sbWebiPrefs = new StringBuffer(); Iterator itr = wPrefs.entrySet().iterator(); while(itr.hasNext()) { Map.Entry current = (Map.Entry)itr.next(); if(sbWebiPrefs.length() != 0) sbWebiPrefs.append("&");

sbWebiPrefs.append(current.getKey()); sbWebiPrefs.append("="); sbWebiPrefs.append(current.getValue()); } return sbWebiPrefs.toString();}%>The following code fragment shows how to use the functions declared above

to update a user’s Web Intelligence preferences.<%//Update a user’s Web Intelligence preferences


2
int userID = myIEnterpriseSession.getUserInfo().getUserID();String prefs = getWebiPrefs(myIInfoStore, userID);Map prefsMap = webiPrefsToMap(prefs);prefsMap.put( "webi_panel", "java");setWebiPrefs(iStore, webiPrefsToSting(prefsMap), userID);%>
Note: The functions getWebiPrefs and webiPrefsToMap are declared in the example “Printing a user’s preferences” on page 26

Adding custom options to a user’s profileTo add custom options to a user’s profile:1. Get a user’s preferences.2. Set the custom option with Map.put.

When you set an option that does not exist in the user profile, Map.put creates a new option and sets it to the value you specify.

3. Convert the Map to a String. 4. Update the user profile with IInfoStore.commit.Example: Adding a new preference to a user’s profileThe following JSP code fragment sets a custom preference.<%//Add a custom Web Intelligence preference using functions

defined in the previous examplesint userID = myIEnterpriseSession.getUserInfo().getUserID();String prefs = getWebiPrefs(myIInfoStore, userID);Map prefsMap = webiPrefsToMap(prefs);prefsMap.put( "MyPreference", "tea");setWebiPrefs(iStore, webiPrefsToSting(prefsMap), userID);%>

Note: The functions getWebiPrefs and webiPrefsToMap are declared in the example “Printing a user’s preferences” on page 26.


2
Exception handling
BusinessObjects Enterprise SDK generates exceptions of the type SDKException.Depending on the cause of the exception, Web Intelligence Report Engine SDK generates exceptions of the following type:• REException• CommunicationException • ConfigurationException • FilterConditionException • InvalidParameterException • QueryException• ReportException • ServerException • UserInputRequiredException

Exceptions and their descriptions are listed in the online reference documentation.Note: All exception classes (above) are subclasses of the REException class.


2
Reporting essentials
All applications that view, edit or format Web Intelligence documents need to:• reference Web Intelligence Report Engine SDK• initialize the ReportEngine object

This links the report engine and platform packages.• close the ReportEngine object

Note: You use Web Intelligence Report Engine to view, edit and format Web Intelligence documents.

Referencing Web Intelligence Report Engine SDKReferencing the Web Intelligence Report Engine packages gives your web application access to the Web Intelligence functions exposed by REBean.If the web application uses J2EE it must reference REBean.Example: Importing the REBean packageTo import the REBean package, add the following line to JSP pages that use REBean.<%@ page import= "com.businessobjects.rebean.wi.*" %>

Note: You need to include this line in every JSP page that uses REBean classes.

Creating a ReportEngine object with REBeanTo create a ReportEngine object for an application that uses Web Intelligence Report Engine SDK, retrieve the ReportEngine object from the user’s IEnterpriseSession.Example: Instantiating a ReportEngine objectTo instantiate the ReportEngine object, add the following lines to one page of the web application that uses the reporting features of the Web Intelligence SDK. ReportEngine webiRepEngine = (ReportEngine)

enterpriseSession.getService("","WebiReportEngine");webiRepEngine.setLocale(request.getLocale().getLanguage());session.setAttribute("ReportEngine", webiRepEngine);

Note: Business Objects recommends that this object is created when the user logs in to the BusinessObjects Enterprise server.


2
Note: The locale used by the ReportEngine must match the locale used by the client browser.
The ReportEngine object is recuperated in further JSP scripts using the following code.ReportEngine webiRepEngine = (ReportEngine)

session.getAttribute("ReportEngine");

You need to include this on every JSP page that uses the ReportEngine object. Since the scope is set to session, there can be several ReportEngine objects existing at the same time.

Closing a report engine objectJust as you need to close a BusinessObjects Enterprise session, you should also close a report engine object when you have finished with it. To close a report engine object use ReportEngine.close(). This method deallocates the memory assigned to the object and should be called before you call IEnterpriseSession.logoff().



Document Management

chapter

3
Overview
Two key parts of a typical Web Intelligence SDK application are listing the documents that the user can view, and depending on the user’s rights, allowing the user to browse and manage categories and folders used to organize the documents.This chapter explains how to open, list, and work with documents.

Document typesWith BusinessObjects Enterprise SDK you can work with:• Web Intelligence documents• Crystal Reports documents• third-party documents, for example Microsoft Excel (.xls), and Adobe

Acrobat (.pdf) filesUsing Web Intelligence SDK you can do everything Web Intelligence users can do with Web Intelligence documents:• view as HTML• view as PDF• view as Excel• view as XML• refresh• create• categorize• delete• drill• save• schedule• send


3
Document state: storage tokens
Storage tokens are a way to save and, later, reconstruct the state of a document.

Storage token life cycleWeb Intelligence generates a storage token:• when you open a document • when the microcube contents are modified or formatted

When you open a document, Web Intelligence creates a DocumentInstance object that has a storage token. Web Intelligence also creates some temporary files that contain information about the document’s current state.

As the document changes state through the execution of JSP files, the storage token changes too, and more temporary files, representing the document’s states, are created.Web Intelligence generates a new storage token and corresponding set of temporary files at the following triggers:

User interface Triggers SDK Triggers

refreshing the document calling DocumentInstance.getViewdrilling modifying the DrillPath objectcreating and editing a document calling DataProvider.getResultapplying new formats calling DataProvider.runQueryrunning a query opening a document

StorageToken = r0

Temporary files

r0

open doc

Executing file doc object

view1


3
Note: Setting a password and filling in a prompt does not cause a new token to be generated directly. However, a new storage token is generated when you commit the change using DocumentInstance.getView.Example: Storage token life cycleThe following diagram shows how storage tokens change according to triggers in the user interface and the object model. It also shows how the storage tokens are passed between web pages and refer to temporary files that can be used to reconstruct the DocumentInstance object using the call ReportEngine.getDocumentFromStoratagetoken. In the diagram below, this call name is shortened to “get doc”.Using the storage token as an identifier for a document state, you can restore the document to any of its saved states.

3
e.
GIF

GIF

GIFGIF

GIF

StorageToken = r0

r0-s0

StorageToken = r0-s0




view1

view2

view3

Temporary files

r0-s0

r0

r0-s1

r0-s2

r0-s3

open docInstance

run query

get doc(r0-s0)

drill

get doc(r0-s1)

drill

commit change

Executing files docInstance object

r0-s1

1

2

3


3
Table 3-1 Storage token life cycle
Advantages of storage tokensLifetime A storage token in the file system lasts as long as its BusinessObjects Enterprise session. This means that storage tokens are purged from the disk only when the user logs out and the corresponding BusinessObjects Enterprise session ends.Note: Storage tokens are linked to ReportEngine instances. It is not possible to open a document using a storage token created by a different ReportEngine instance.

Browser navigation back and forwardAfter progressing through several document states, users can go back and forwards in their browser to a previous document state and continue working from that state.


3
Organizing documents in categories and folders
In Web Intelligence, categories and folders are used to classify documents in the central management system. Documents that are organized in the hierarchical category and folder structures are easier to find for users who need to search for them.In Web Intelligence, a user can save a document to selected categories and folders. A document can be assigned to one or more public or personal categories.

Table 3-2 Categorized documents.Using the BusinessObjects Enterprise query mechanism you can navigate a category or folder hierarchy and retrieve IInfoObjects containing the individual categories and folders. These in turn enable you to: • create, rename and delete categories and folders• get the details of a categories and folders

User rights for categories and foldersA System administrator, using BusinessObjects Enterprise Central Management Console, can set how much control a user or group has over categories and folders. User rights settings are updated in the Advanced Rights page of the InfoView section for BusinessObjects Enterprise Applications of the Central Management Console.The following table lists an InfoView user’s possible rights.


3
Folder and category-related settings in a Web Intelligence user’s rights
A list of a user’s rights over an object in the InfoStore can be recovered by retrieving the user’s ISecurityInfo object for a certain BusinessObjects Enterprise application. Example: how to check that a user has the right to create categoriesThis code fragment shows how to validate a user has the right to create categories.<%

IInfoStore iStore =(IInfoStore)session.getAttribute("InfoStore");

IInfoObject infoView = null;String query = "SELECT STATIC FROM CI_APPOBJECTS,”

+ “ CI_SYSTEMOBJECTS WHERE”+ “ (SI_PARENTID = 99 AND SI_KIND=\'" + CeKind.INFOVIEW + "\')";

try{IInfoObjects appObjects = iStore.query( query);if (appObjects.size() > 0)

infoView = (IInfoObject )appObjects.get(0);if (infoView != null){

InfoView Advanced Right Variable Name

User can change preferences CeInfoViewRightID.PREFERENCEUser can move and copy objects, create shortcuts and add object to the favorites folder.

CeInfoViewRightID.ORGANIZE

Can use InfoView simple search

CeInfoViewRightID.SIMPLESEARCH

Can use InfoView advanced search

CeInfoViewRightID.ADVANCEDSEARCH

Can use InfoView filter feature CeInfoViewRightID.FILTERUser has a favorites folder CeInfoViewRightID.FAVORITESUser can view inbox contents CeInfoViewRightID.VIEWINBOXUser can create categories CeInfoViewRightID.CREATECATEGORIESUser can assign categories to users or groups

CeInfoViewRightID.ASSIGNCATEGORIES

User can send documents to users and groups

CeInfoViewRightID.SENDDOCUMENTS

User can create dashboards CeInfoViewRightID.CREATEDASHBOARDSUser can create folders CeInfoViewRightID.CREATEFOLDERS


3
ISecurityInfo secInfo =
infoView.getSecurityInfo();if (secInfo.checkCustomRight(

CeInfoViewRightID.CREATECATEGORIES,infoView.getKind()))

{...}

}}catch (Exception exc){

...}

%>

Note: Before trying to manage categories, check that the user who started the session has the appropriate rights.Note: A list of a rights for other BusinessObjects Enterprise applications can be found by changing the CeKind being searched for. For example, to search for a user’s Web Intelligence rights the query string would include CeKind.WEBINTELLIGENCE in the place of CeKind.INFOVIEW.

Navigating categories and foldersCategories and folders in a Web Intelligence Central Management System are represented as a tree. Personal and Public are root nodes for categories. Home is the root node for folders.To access the category or folder trees, query the repository to retrieve the ID of the parent node for categories or folders. Use this ID to navigate the child nodes.

Example: Recursively traversing the category treeThe following example shows JSP functions that use BusinessObjects Enterprise SDK to recover the ID of the parent folder for a user’s personal categories. Using this ID a bulleted list containing the hierarchical structure of the user’s personal categories is generated.<%! //Return the ID of a specific folderpublic int getFolderParentId(IInfoStore iStore, int userID,

String kind){int FolderID = 0;IInfoObjects folders = null;String query = "SELECT SI_PARENTID FROM CI_INFOOBJECTS”

+ “ WHERE SI_KIND='" + kind + "'"+ “ AND SI_OWNERID=" + userID;

try{folders = iStore.query(query);if(folders.size() > 0)

FolderID=((IInfoObject)folders.get(0)).getParentID();


3
}catch (SDKException sdke){
return FolderID;}return FolderID;

}//Return a selectable list of categories or foldersString getCategoryList(IInfoStore iStore,

int id, String kind ){String results = "";IInfoObject category;if (id == -1) id = 0;String sQuery = "SELECT SI_ID, SI_NAME, SI_PARENTID FROM”

+ “ CI_INFOOBJECTS WHERE SI_PARENTID=" + id+ " AND SI_KIND= \'"+ kind + "\'" ;

try{ IInfoObjects categories = iStore.query(sQuery); if (!categories.isEmpty()){

results += "<ul>";for(int i = 0; i < categories.size(); i++){

category = (IInfoObject)categories.get(i);String name = category.getTitle();int catID = category.getID() ;results += "<li><input type=\"radio\" name=\""

+ kind + "\" value=\""+ catID + "\" >" + name + "</li>\n";

results += getCategoryList(iStore,category.getID(), kind);

}results += "</ul>";

}}catch (SDKException sdke){

results = null;}return results;

}%>

The following code fragment shows how to use the functions declared above to print personal categories for a user.<%IEnterpriseSession enterpriseSession =(IEnterpriseSession)

session.getAttribute("EnterpriseSession");IInfoStore iStore=

(IInfoStore)session.getAttribute("InfoStore");int userID = enterpriseSession.getUserInfo().getUserID();int persoCatsfolderID = getFolderParentId(

iStore,userID,(String)CeKind.PERSONALCAT);String catButtons =

getCategoryList(iStore, (String)CeKind.PERSONALCAT));

%>

Note: For an example of how to list documents in a folder, see “Displaying a document list” on page 49.


3
Retrieving Inbox and favorites folder IDs
Each BusinessObjects Enterprise user has unique personal directories. The Inbox and Favorites directories contain documents sent to a specific user or saved for personal rather than corporate use. To list the contents of these folders you need to retrieve the ID for each user’s personal directories. Once the root directory ID is retrieved, you can list and navigate the contents in the same way corporate folders are navigated. Example: Retrieve a user’s Inbox and Favorites folder IDsThe following example shows JSP functions that use BusinessObjects Enterprise SDK to recover the ID of the parent folder for a user’s Inbox and Favorites folders. <%!//Retrieve the ID for any type of personal folderpublic int getFolderId(IInfoStore iStore, int userID,

String kind){int FolderID = 0;IInfoObjects folders = null;String query = "SELECT SI_ID" +

" FROM CI_INFOOBJECTS" +" WHERE SI_KIND='" + kind + "'" +" AND SI_OWNERID=" + userID;

try{folders = iStore.query(query);if(folders.size() > 0)

FolderID = ((IInfoObject)folders.get(0)).getID();}catch(SDKException sdke){

FolderID = -1;}return FolderID;

}//Retrieve the ID of a user’s Inboxint getInboxFolderId(IInfoStore iStore, int userID){

return getFolderId(iStore,userID,(String)CeKind.INBOX);}//Retrieve the ID of a user’s favorites folderint getFavoritesPFolderID(IInfoStore iStore, int userID){

return getFolderId(iStore,userID,(String)CeKind.FAVORITESF);

}%>

//The following example shows how to retrieve a list of documents in the current user’s Inbox. See “Displaying a document list” on page 49 for the definition of getList.

<%IEnterpriseSession enterpriseSession;IInfoObjects docList = null;enterpriseSession = (IEnterpriseSession)

session.getAttribute("EnterpriseSession");IInfoStore iStore = (IInfoStore)


3
session.getAttribute("InfoStore");
int userID = enterpriseSession.getUserInfo().getUserID();int inboxID = getInboxFolderId(iStore, userID);

docList = getList(iStore, inboxID, (String)CeKind.WEBI );

%>

Note: See “Displaying a document list” on page 49 for the definition of getList.


3
Creating categories and folders
You can add categories and folders by:• getting the ID of the folder or category in which you wish to create a node• getting the correct plug-in to create a node• committing the new object to the Central Management System

Example: Creating a new folder or categoryThe following example shows JSP functions that use BusinessObjects Enterprise SDK to create a new folder or category.<%!int addFolderOrCategory(IInfoStore iStore,

int parentFolderID,String name, String description, String type){

int objectID = 0;IPluginInfo plugin; try{

IPluginMgr pluginMgr = iStore.getPluginMgr();plugin = pluginMgr.getPluginInfo(type);IInfoObjects newInfoObjects =

iStore.newInfoObjectCollection();newInfoObjects.add(plugin);IInfoObject infoObject = (IInfoObject)

newInfoObjects.get(0);infoObject.setTitle (name);infoObject.setDescription (description);objectID = infoObject.getID();infoObject.properties().setProperty(

CePropertyID.SI_PARENTID, parentFolderID);iStore.commit (newInfoObjects);

}catch (SDKException e) {throw new Error("Failed to add the object.");

}return objectID;

}%>

The following code fragment shows how to use the functions declared above to create a new personal category and a new folder.<%//How to use this function //Create a new personal categoryaddFolderOrCategory(iStore, categoryParentID,

"Category Name", "Keywords",CeKind.PERSONALCAT);

//Create a new personal folderaddFolderOrCategory(iStore, categoryParentID,

"Folder Name", "Keywords", CeKind.FOLDERS);

%>


3
Moving and renaming categories and folders
You can move categories and folders from one parent to another with:• IInfoObject.setParentID

You can rename categories and folders using:• myIInfoObject.setTitle

After the category or folder has been renamed or moved, IInfoStore.commit must be called with the changed IInfoObject passed as a parameter.Example: Moving and renaming categories or foldersThe following function changes the name of a folder or category and moves it in the folder or category hierarchy respectively.<%!String changeNameMove(IInfoStore iStore, int ID, String

newName, int newParentID){String query;IInfoObjects result;String res = "";query = "Select SI_NAME, SI_ID From CI_INFOOBJECTS “

+ “ Where SI_ID=" + ID;try{

result = iStore.query(query);if ( result.size() > 0 ){

IInfoObject currResult;currResult = (IInfoObject)result.get(0);currResult.setTitle(newName);currResult.setParentID(newParentID);iStore.commit(result);

}}catch(SDKException e){

;}return res;

}%>

Getting the properties of a categoryEach IInfoObject in the BusinessObjects Enterprise InfoStore contains a collection of all properties assigned to that object, known as a "properties bag." To retrieve an IInfoObject's details, request SI_NAME, SI_DESCRIPTION, SI_KEYWORD in the query string used to recuperate the IInfoObject representing a category or folder. Example: Retrieve the properties for a categoryThe following method returns the properties of a category, folder, or document as an IInfoObject:


3
<%!IInfoObject getProps(IInfoStore iStore, int ID){
String query;IInfoObjects result = null;IInfoObject properties = null;String res = "";query = "SELECT SI_FILES, SI_DESCRIPTION,”

+ ” SI_KEYWORD, SI_KIND";query += " FROM CI_INFOOBJECTS WHERE SI_ID=" + ID;try{

result = iStore.query(query);if (result.size() > 0){

properties = (IInfoObject)result.get(0);}

}catch(SDKException e){

return null;}return properties;

}%>

The following code fragment shows how to use the functions declared above to print the description and keywords of an InfoStore object to an HTTP stream.<%int ID = Integer.parseInt(request.getParameter("ID"));PrintWriter myWriter = response.getWriter();IInfoStore iStore = (IInfoStore)

session.getAttribute("InfoStore");IInfoObject fProperties = getProps(iStore, ID);myWriter.print( fProperties.getDescription() + "<br>\n");myWriter.print( fProperties.getKeyword() + "<br>\n");

//Another way to retrieve the keyword IInfoObject PropertymyWriter.print(

fProperties.properties().getProperty(CePropertyID.SI_KEYWORD).getValue().toString());

%>


3
Working with documents
Working with documents involves opening and listing the documents, then providing facilities for saving, sending, scheduling, and organizing documents.

Opening documentsAfter establishing a session for a user (see “Establishing a valid BusinessObjects Enterprise user’s session” on page 20) you can open a document on behalf of the user.In general, to open a document you:1. Establish a BusinessObjects Enterprise session for the user.2. Get an identifier for the document.

The identifier can be a storage token (see “Document state: storage tokens” on page 35), or more simply the document’s ID.

3. Open the document using the ReportEngine.openDocument method for Web Intelligence documents.

Taking into account user rights and profilesBecause your Web Intelligence application acts on behalf of a user, what your application can do with the document is subject to the user’s rights, which are set in the BusinessObjects Enterprise Central Management Console. You should take these rights into account in your application.You should also take into account the settings in the user’s profile. See “User preferences” on page 25.Note: By default, the maximum number of DocumentInstances open concurrently on one application server is ten. When the number of DocumentInstances exceeds the default, the primary application server will failover to a backup application server. If you want to change the default value, set the variable FAILOVER_SIZE to the value desired in the webi.properties file of your BusinessObjects Enterprise installation.

Displaying document listsTo display a list of documents you:1. Use the IInfoStore.query method to return the list of IInfoObjects

representing the root directory of the user’s folders and documents.2. Loop through the IInfoObject list and print the values of the fields of

each row.3. Allow navigation through the folders.


3
Note: IInfoObject is the base BusinessObjects Enterprise type. An IInfoObject can be used to store any type of object in the central management system.
Refreshing a document listA document list is refreshed every time IInfoStore.query is called. The results come directly from the BusinessObjects Enterprise Central Management System (CMS) with no intermediary cache.Example: Displaying a document listThe following JSP code fragment is a helper function called getList. This function is passed an IInfoStore object as a parameter, which is then used to return a list of IInfoObjects of a required type, in this case Folders or Web Intelligence documents. This function is placed either at the head of the listfolders.jsp script or in a file containing helper functions included in listfolders.jsp.<%!IInfoObjects getList(IInfoStore iStore,

int searchID, String kind){IInfoObjects list = null;String query = "SELECT SI_ID, SI_NAME, SI_PARENTID,”

+ “ SI_KIND, SI_INSTANCE, SI_DESCRIPTION FROM”+ “ CI_INFOOBJECTS WHERE SI_PARENTID=" + searchID + " AND SI_KIND = '" + kind + "'";

try{list = iStore.query(query);

} catch (SDKException sdke){

list = null;}return list;

}%>

The function getInfoList is called from listfolders.jsp. The following code fragment shows returns a list of Web Intelligence documents in the document root folder.<%

int iID= 0; //ID of the root folderIInfoObjects webiDocs = null;String searchID=request.getParameter("sID");if (searchID!=null) iID=Integer.parseInt(searchID);IInfoStore iStore =

(IInfoStore)session.getAttribute("InfoStore");webiDocs=getList(iStore,iID,(String)CeKind.WEBI);...

%>


3
Saving documents
To save a document use DocumentInstance.save and DocumentInstance.saveAs.Example: Save a Web Intelligence documentThe following example shows how to open a document to be worked on, then open and save the original version of the document.<%DocumentInstance doc =

myReportEngine.openDocument(docID);String docToken doc.getStorageToken();//User perform actions on document doc...//Open the first version of the document and save.DocumentInstance docToSave =

myReportEngine.openDocument(docToken);docToSave.save();%>

Note: Go to “Sending documents to users, groups and categories” on page 52 to see how to use the saveAs method.

Scheduling documentsScheduling refreshes a document automatically at a specified time or times. When a scheduled document refreshes successfully, an instance is created. An instance is version of the document containing data available at the time it is refreshed. Instances created later contain more recent data. By scheduling and viewing instances, a user can have the latest information available for viewing, printing, and distributing. For example, you can schedule a document to run every night so data viewed first thing in the morning is sure to be up to date.To schedule a document you need to:1. Query the IInfoStore to get the IInfoObject representing the specific

document.2. Get the document IInfoObject’s ISchedulingInfo object.3. Set the type and frequency of the scheduling.4. Use the IInfoStore to schedule the document.

Note: The schedule action refreshes data in a document. This means that Prompt, Context, and Drill actions have to be handled automatically at run time using information gathered from the user when the schedule action is created.


3
Example: Scheduling a documentThe following JSP function shows how to schedule a document to run once immediately or recurrently on a specific interval of days. The document instance created is stored in the list of document instances attached to a document. <%!boolean scheduleDocument(IInfoStore iStore, int documentID,
int days){IInfoObjects documentList;ISchedulingInfo schedulingInfo;IInfoObject document;String res = "";boolean success = true;try {

String schedQuery = "Select SI_schedulingInfo From”+ “ CI_INFOOBJECTS Where SI_ID="+ documentID;

documentList = iStore.query( schedQuery);if ( documentList.size() > 0 ){

document= (IInfoObject) documentList.get(0);schedulingInfo = document.getSchedulingInfo();if (days == -1){

schedulingInfo.setType(CeScheduleType.ONCE);schedulingInfo.setRightNow(true);

} else {schedulingInfo.setIntervalDays(days);schedulingInfo.setType( CeScheduleType.DAILY );

}iStore.schedule(documentList);

}} catch( SDKException e ) {

success = false ;}return success;

}%>

The following code fragment shows how to call the scheduleDocument function to schedule a document to be run once immediately.<%String docId = request.getParameter("docID"); IInfoStore iStore =

(IInfoStore)session.getAttribute("InfoStore");

scheduleDocument(iStore, Integer.parseInt(docId), -1);%>


3
Sending documents to users, groups and categories
The list of BusinessObjects Enterprise users to whom a document can be sent depends on the groups to which the current user belongs, and the current user’s permissions.

Example: Retrieve the list of groups to which a user belongsThe following JSP function shows how to retrieve the list of groups the current user belongs to.<%!IInfoObjects getUserGroups(IInfoStore iStore){

IInfoObjects groups = null;String query = "SELECT SI_ID, SI_NAME" +

" FROM CI_SYSTEMOBJECTS" +" WHERE SI_KIND='" + CeKind.USERGROUP + "'" ;

try{groups = iStore.query(query);

} catch (SDKException sdke){groups = null;

}return groups;

}%>

BusinessObjects Enterprise uses object security, which means that security is set for each object in the system and not for each user. Thus, for a particular object, certain users and certain groups have the rights to different actions, depending on the object’s settings. This means that access to folders and categories can be restricted to specific groups and individual users. Saving a document to a specific folder and category is a way of publishing a document to a group of users.These permissions are controlled by the system administrator using BusinessObjects Enterprise Central Management Console.

Action To these groups and/or users …

Depending on the current user’s settings for these permissions…

Save to Groups and Categories

groups and categories to which the current user has access

DocumentInstance.saveAs

Send to Inbox, FTP, email, groups.

groups to which the current user belongs, and/or the other users in those groups

IInfoStore.schedule


3
Procedure for sending a document to folders and categoriesBusinessObjects Enterprise documents are organized by folder and categories. To send a document to folders use DocumentInstance.saveAs. Typically, however, to send a document, you need to gather the appropriate information from the current user before sending. To do this you need two web pages:In the first page:1. Display the name of the document to be sent. 2. Retrieve the IDs of:
• corporate folders and categories• the root directory of the current user's personal categories

3. Get and display the list of folders and categories to which the current user can send documents.

4. Pass this information to the second JSP page.Then, in the second JSP page:1. Get the details entered by the user.2. Call DocumentInstance.saveAs.Example: Sending a document to folders and categoriesThe following JSP code fragments are used to save a document in specific folders and categories. saveDocAs.jsp is called by a JSP that passes the name and ID of the document in the query string. In saveDocAs.jsp the user selects the folders and categories the document is to be saved in. When the user clicks “Save Document” in the form, saveDoc.jsp is executed and the document is sent according to the user’s selections.Note: The function getCatOrFoldersRadioButtons and webiPrefsToMap is declared in the example “Recursively traversing the category tree” on page 41.In saveDocAs.jsp<%!//Return the ID of a specific folderpublic int getFolderParentId(IInfoStore iStore, int userID,

String kind){int FolderID = 0;IInfoObjects folders = null;String query = "SELECT SI_PARENTID FROM “

+ “ CI_INFOOBJECTS WHERE SI_Kind='" + kind + "'" + AND SI_OWNERID=" + userID;

try{ folders = iStore.query(query); if(folders.size() > 0)


3
FolderID=((IInfoObject)folders.get(0)).getParentID();}catch (SDKException sdke){
return FolderID;}return FolderID;

}%>

The following code fragment shows how to use the functions declared above to create a form used to select the folders and categories in which a document will be saved.In saveDoc.jsp<%//get the parameters from the request objectString docId = request.getParameter("docID");String docName = request.getParameter("docName");String docParentFolderID =

request.getParameter("corpFolder");String corpCategID = request.getParameter("corpCategory");String persoCatedID = request.getParameter("persoCategory");List ccIDlist = new ArrayList();List pcIDlist = new ArrayList();//Validate the parametersif (corpCategID != null)

ccIDlist.add(Integer.decode(corpCategID));if (persoCatedID != null)

pcIDlist.add(Integer.decode(persoCatedID));if (docId != null && docParentFolderID != null){//Open and save the document

DocumentInstance docToSave = webiRepEngine.openDocument(Integer.parseInt(docId));

if( docToSave != null)docToSave.saveAs( docName,

Integer.parseInt(docParentFolderID),ccIDlist,pcIDlist);

}%>

Note: corpCategories and persoCategories are strings containing the ID’s of the corportate and personal category chosen by the active user in which to store the document.

Sending a document to the Inbox of users or groupsIf the current user has the appropriate permissions, you can schedule a document to be send to the inboxes of users or groups of users to which the current user belongs.

Procedure for sending a document to inboxesTo schedule a document, you need to gather the appropriate information from the current user before sending. To do this you need to:


3
1. Query the IInfoStore to get the IInfoObject representing the document to
be sent.2. Get the document’s ISchedulingInfo object.3. Retrieve the Inbox plugin used to send a document to users.4. Set the destination and send options for the Inbox plugin.5. Create a Set containing the IDs of users or groups to which the current

user can send the document.6. Allow the user to choose the users/groups to send the document to.7. Add the set of IDs created in the previous step to the Inbox plugin

options.8. Set the type and frequency of the scheduling.9. Schedule the document.Note: In the InfoView user interface, this action is called “Send to BusinessObjects Inbox.”You get the list of groups to which the current user can publish documents by querying the InfoStore. The returned IInfoObjects object contains the ID’s of all groups the current user has the right to send to. Example: Send a document to the inbox of groups of users<%!//This function retrieves the Inbox destination pluginIDestinationPlugin getInboxDestPlugin(IInfoStore iStore){

int PLUGIN_ROOT = 29;IDestinationPlugin inboxPlugin = null;String[] pluginsToLoad = new String[] {CeKind.DISKUNMANAGED, CeKind.SMTP, CeKind.FTP,

Kind.MANAGED_DEST};String pluginString = "";for (int i = pluginsToLoad.length - 1; i >= 0; i--){

pluginString += "'" + pluginsToLoad[i] + "'";if (i != 0) pluginString += ", ";

}String pluginQuery = "SELECT * FROM CI_SYSTEMOBJECTS”

+ “ WHERE SI_PARENTID=” + PLUGIN_ROOT+ “ AND SI_NAME in "+ "(" + pluginString + ")";

try{IInfoObjects destPlugins = iStore.query(pluginQuery);for (int i = 0; i < destPlugins.size(); i++){ IInfoObject plugin =

(IInfoObject)destPlugins.get(i); if (

CeKind.MANAGED_DEST.equals(plugin.getTitle()) )inboxPlugin = (IDestinationPlugin)(plugin);

}} catch (SDKException e){


3
inboxPlugin = null;
}return inboxPlugin;

}

//This function retrieves the IDs of the groups the current //user can schedule toSet getUserGroupIDs(IInfoStore iStore){

IInfoObjects groups = null;Set IDs = new HashSet();String query = "SELECT SI_ID, SI_KIND, SI_NAME"

+ " FROM CI_SYSTEMOBJECTS" + " WHERE SI_Kind='" + CeKind.USERGROUP + "'";

try{groups = iStore.query(query);int size = groups.size();for (int i = 0; i < size; i++) {

IInfoObject obj = (IInfoObject)groups.get(i);if (CeKind.USERGROUP.equals(obj.getKind())) {

IDs.add(new Integer(obj.getID()));}

}} catch (SDKException sdke){

IDs = null;}return IDs;

}%>

The following code fragment shows how to send the copy of a document to the inbox of all users in the groups the current user is allowed to post to once a week.<%

String docId = request.getParameter("docID"); IInfoStore iStore =

(IInfoStore)session.getAttribute("InfoStore");

IDestinationPlugin inboxPlugin = null;IManagedOptions destOptions = null;ISchedulingInfo schedulingInfo = null;IInfoObjects documentList = null;IInfoObject document = null;try {

String docQuery = "Select SI_schedulingInfo FROM”+ “ CI_INFOOBJECTS Where SI_ID=" + docId;

documentList = iStore.query(docQuery);if ( documentList.size() > 0 ) {

document= (IInfoObject)documentList.get(0);schedulingInfo = document.getSchedulingInfo();inboxPlugin = getInboxDestPlugin(iStore);IDestination destination =

schedulingInfo.getDestination();if (inboxPlugin != null){ destOptions =(IManagedOptions)

inboxPlugin.getScheduleOptions();


3
destOptions.setDestinationOption(
IManagedOptions.CeDestinationOption.ceInbox); destOptions.setSendOption(

IManagedOptions.CeManagedSendOption.ceCopy); Set IDs = getUserGroupIDs(iStore); Set destinationIDs =

destOptions.getDestinations(); destinationIDs.clear(); destinationIDs.addAll(IDs); destination.setFromPlugin(inboxPlugin); schedulingInfo.setIntervalDays(7); schedulingInfo.setType(CeScheduleType.DAILY); iStore.schedule(documentList);}

}} catch( SDKException e ) {

throw e;}%>


3
Document properties
Some of the important characteristics of Web Intelligence documents are stored as part of the document. You can access these properties using the DocumentInstance object.For REBean the process for accessing a property of a Web Intelligence document is:1. Get the collection of properties.2. Set/Read the property.3. Commit the change, if any, to the collection of properties.

Working with propertiesUsing Web Intelligence Report Engine SDK, you can access a document’s properties with DocumentInstance.getProperties and DocumentInstance.setProperties. These methods make use of the Java class java.util.Properties.There are predefined properties defined in PropertiesType. You can also add you own properties to the document.Note: To avoid confusion in the central management system, PropertiesType.NAME is read only.Example: Getting the name of a Web Intelligence document using REBeanThe following Java code fragment illustrates how to get the NAME property of a Web Intelligence document.DocumentInstance doc =

myReportEngine.openDocument(docID);java.util.Properties props = doc.getProperties ();String dName = props.getProperty (PropertiesType.NAME);

Adding your own properties to the documentUse Properties.setProperty to add your own properties to the document.Example: Adding a property to a Web Intelligence document The following Java code fragment illustrates how to add the RefreshCount property to a Web Intelligence document.DocumentInstance doc =

myReportEngine.openDocument(docID);java.util.Properties props = doc.getProperties ();props.setProperty ("RefreshCount", "12");


3
doc.setProperties (props);
If you create a new Properties collection and add properties to that collection, when you call DocumentInstance.setProperties the values in the new object are added to the standard property collection. Permanent properties such as NAME and AUTHOR are not erased in the merge. Values for these properties that you have set in the new collection take precedence over those in the one attached to the DocumentInstance.

Property persistenceYou do not need to save the document for the properties you set to persist after the document is closed.


3



Viewing Web Intelligence Reports

chapter

4
Overview
Web Intelligence SDK contains classes and methods for viewing documents. Applications for viewing Web Intelligence documents (*.wid) handle prompts and provide report and section navigation with a report map.This chapter discusses how to use REBean to view Web Intelligence reports.See also and “Formatting Reports” on page 103.

Viewing reportsYou can view complete documents (all reports) in either Adobe Acrobat (PDF) or Microsoft Excel (XLS) format. You can view individual reports or report pages (?) in XML and HTML format as well as PDF and XLS. The following table shows viewing possibilities.

To view an entire document, call DocumentInstance.getView,to view an individual report, call Report.getView. If you want to view all the reports in a document in HTML format, you need to get views of each report in HTML and display those separately. See “Viewing an individual report in HTML” on page 63.Note: Calling DocumentInstance.getView and Report.getView generates a new storage token. For more information on storage tokens see “Document state: storage tokens” on page 35.

Viewing all the reports in a documentTo view all the reports in a document:1. Open the document.2. Get a binary view of the document.

You can get a binary view of a document in PDF or Microsoft Excel format. When Web Intelligence converts the document into PDF it places reports on separate pages and creates a bookmark for each report. In Microsoft Excel format the reports of a Web Intelligence document appear on separate sheets.

Type XLS PDF XML HTML

Document X XReport X X X XReport Page X X X X


4
3. Output the binary view of the document via the implicit response object.
You need to prepare the response object to receive the appropriate content type. For Adobe Acrobat format set the content type to “application/pdf”. For Microsoft Excel format, set the content type to “application/vnd.ms-excel”.

Example: Viewing all the reports in a Web Intelligence documentThe following code fragment displays all the reports in a document in Adobe Acrobat format. In this example, the name of the document is stored in docName and the ID is stored in docID. Typically these would be passed to the script in the query string.<%// get the documentDocumentInstance doc = repEng.openDocument(docID);//get the report contents as a binary stream in PDF formatBinaryView docBinaryView = (BinaryView)

doc.getView(OutputFormatType.PDF);byte[] abyBinaryContent = docBinaryView.getContent();

//output the binary stream via the response objectresponse.setContentType("application/pdf");ServletOutputStream outputStream =

response.getOutputStream();outputStream.write(abyBinaryContent);%>

Note: This example starts Adobe Acrobat Reader® and displays the document using this application. Depending on the user’s browser configuration, the document will appear in either in the browser or in a separate application window.

Viewing an individual report in HTMLThe standard viewing format is HTML.To view an individual report in HTML format:1. Get a document instance.2. Set the report.3. Get a view of the report in HTML format.4. Display the report.Example: Viewing a report in a Web Intelligence document The following JSP code fragment displays a selected report in a Web Intelligence document in HTML format.<%// Get query string parameters and initialize variables


4
String sToken = request.getParameter("token");String sRepID = request.getParameter("reportID");DocumentInstance doc = null;Report rep = null; //the report to be viewedint iRepID = 0; //index of the selected report
// Get the documentdoc = reportEngine.openDocument(sToken);// Set the reportif ((sRepID != null)&&(!(sRepID.equals(""))))

iRepID = Integer.parseInt(sRepID);else iRepID = 0;//set to the first report in the document

rep = doc.getReports().getItem(iRepID);

//get a view of the report in HTML formatHTMLView docHtmlView = null;docHtmlView = (HTMLView)rep.getView(OutputFormatType.HTML);String sHTMLView = docHtmlView.getContent();%><%=sHTMLView%>

Note: In this example, reportEngine is an initialized ReportEngine object.

Viewing an individual report in another formatYou can view reports in Adobe Acrobat or Microsoft Excel format. The procedure is the same as for HTML format (described above) except that, as for viewing all the reports in a document, you must get the content of the report as a binary stream which you can output via the response object.To view a report in a non-HTML format:1. Get a binary view of the report.2. Output the binary view of the document via the implicit response object.

You need to prepare the response object to receive the appropriate content type. For Adobe Acrobat format set the content type to “application/pdf”. For Microsoft Excel format, set the content type to “application/vnd.ms-excel”.

Example: Viewing a report in Microsoft Excel formatThe following JSP code fragment displays all the reports in a Web Intelligence document in Microsoft Excel format.//get the report to view (Report rep)...//get the report contents as a binary stream in Excel formatBinaryView docBinaryView =

(BinaryView)rep.getView(OutputFormatType.XLS);byte[] abyBinaryContent = docBinaryView.getContent();

//output the binary stream via the response object


4
response.setContentType("application/vnd.ms-excel");ServletOutputStream outputStream =
response.getOutputStream();outputStream.write(abyBinaryContent);


4
Handling prompts
Prompts are a way to get supplementary information before executing a query. Prompts can resolve filters in the query, ask for passwords on protected documents, and resolve context clashes in universes (do you want the customer’s details to come from the Sales table, or the Customer Service table?).In Web Intelligence Report Engine SDK, how you handle prompts depends on the type of document you are working with. This section discusses how to handle prompts in Web Intelligence documents. For Web Intelligence documents you use the REBean packages to handle prompts.Prompts are usually raised when a document is refreshed using DocumentInstance.refresh if scheduled. The refresh operation executes the query and, therefore, needs to collect the supplementary information that resolves filters and contexts.Note: Prompts that resolve universe contexts must be filled before standard prompts. See “Handling context prompts” on page 76.

Documents with a single simple promptOne of the simplest and most common prompts is one that resolves a query filter. For example, “Enter the year: “ to which a user responds “2003” and the data retrieved by the query is restricted to the year 2003.Example: Handling a single, simple promptThe following JSP code fragment illustrates how to handle a single, simple prompt. (“Simple prompt” means standard, text-entry prompts only.)The code in this example is from a JSP called refresh.jsp. When the user chooses to refresh a document, refresh.jsp is executed, then, when the prompt have been filled, view.jsp is executed.DocumentInstance doc = reportEngine.openDocument(Token);if (doRefresh) doc.refresh(); //refresh first time onlyPrompts prompts = doc.getPrompts();

//try to enter values and set promptsString[] values = request.getParameterValues("PromptInput");if ((values != null)&&(!(values[0].equals("")))){

prompts.getItem(0).enterValues(values);doc.setPrompts(); //also sets getMustFillPrompts to false

}

//get user inputif (doc.getMustFillPrompts()) {

//build a form to get user input for the prompt


4
%><formname="PromptsForm"
action="refresh.jsp?Token=<%=doc.getStorageToken()%>"method="post"><input name="PromptInput" type="text"/><input name="Submit" type="submit" value="OK" />

</form><%

}response.sendRedirect("view.jsp?

Token="+doc.getStorageToken());

Note: This example does not show how to set doRefresh. One way to set this variable is to include an extra parameter in the query string for refresh.jsp; when DoRefresh is ”F”, doRefresh is false.

The workflow for refresh.jsp for a document with one, simple prompt is therefore:1. Get the DocumentInstance object for the document.2. Get the collection of prompts for the document.3. Try to enter values for the prompt and set the prompts for the document.

The first time refresh.jsp is executed, this step will not work as the user has not yet entered a value for the prompt.

4. Either:

• if the prompt is not filled, display a form to get a value from the user

This is the case the first time the JSP is executed.The form’s action parameter is set to refresh.jsp so that this JSP is executed when the user clicks the submit (OK) button.

• otherwise, execute view.jsp to display the document’s reports

Using the storage token to retrieve a DocumentInstanceWhen handling any kind of prompt, if you use the storage token to retrieve the document, you must be careful to use the correct token. The storage token changes after calls to DocumentInstance.refresh, and DocumentInstance.setPrompts.For more information on storage tokens see “Document state: storage tokens” on page 35.


4
Documents with many simple prompts
To handle many simple prompts you can extend the workflow for the single simple prompts (page 66) with a form into which the user can enter values for all the prompts, and a script that handles these values.One problem this extension raises is that you need to dynamically set the names of the inputs in the form that carry the values of each prompt. To do this you can construct a name using a string constant, for example “PV”, and the position of the prompt in the Prompts collection.Example: Dynamically creating input namesThe following JSP code fragment illustrates how to dynamically create names for the inputs of a form.<form name="PromptsForm" action="refresh.jsp" method="post">

<table><%for (int i = 0; i < prompts.getCount(); i++) {%><tr>

<td>Enter a value for prompt number <%=i%>:</td><td><input name=<%="PV"+i%> type="text"/></td>

</tr><%}%><tr><td>

<input name="Submit" type="submit" value="OK" /></tr></td>

</table></form>

Note: See the following example for an illustration of how to retrieve the values in these inputs from the query string.Example: Handling many, simple promptsThe following code fragment illustrates how to handle many, simple prompts in a Web Intelligence document. (“Simple prompt” means standard, text-entry prompts only.)The code in this example is from a JSP called refresh.jsp. When the user chooses to refresh a document, refresh.jsp is executed, then, when the prompt have been filled, view.jsp is executed.<%//get the document and its promptsDocumentInstance doc = reportEngine.openDocument(token);if (doRefresh) doc.refresh(); //refresh first time onlyPrompts prompts = doc.getPrompts();

//try to get and enter values from the query string // valuesSelected is true when the user completes the formif (valuesSelected) {

for (int j = 0; j < prompts.getCount(); j++) {//use (recreate) the parameter names created in the form

String[] values = request.getParameterValues(("PV" + j));


4
if ((values != null)&&(values.length != 0))
prompts.getItem(j).enterValues(values);}doc.setPrompts(); //also sets getMustFillPrompts to false

}

//get user inputif (doc.getMustFillPrompts()) {

//build a form to get user input for the prompt%><form

name="PromptsForm"action="refresh.jsp"method="post">

<table><%//add a row to the table for each prompt// the names of inputs are created dynamicallyfor (int i = 0; i < prompts.getCount(); i++) {%>

<tr><td><%=prompts.getItem(i).getName()%></td><td><input name=<%="PV"+i%> type="text"/></td></tr>

<%}//and add a row to the table for the submit button// DoRefresh and ValuesSelected help keep track of // where we are in the workflow%><tr><td>

<input name="Token" type="hidden"value="<%=doc.getStorageToken()%>" /><input name="DoRefresh" type="hidden"value="false" /><input name="ValuesSelected" type="hidden"value="true" /><input name="Submit" type="submit" value="OK">

</tr></td></table>

</form><%

}else //all prompts are filled and can now display the report

response.sendRedirect("view.jsp?Token="+doc.getStorageToken());

%>

Note: A flag is needed now to determine if there are prompt values in the query string. This example uses a hidden input in the form, ValuesSelected, which is converted to a boolean when it is retrieved, however, you could also use the first prompt parameter PV0 for this purpose.


4
Prompts with simple lists of values
A list of values (LOV) is a set of values associated with a universe object. These values are the corresponding values found for the object in the database, however the universe designer can edit this set as part of creating the object in the universe. For example, the Quarter object could have the following list of values {Q1, Q2, Q3, Q4}, and the Customer object could have a list of values like this: {Adams, Arkwright, Baker, Bean, ..., Zane}. These values are defined when the designer creates the object, but can be refreshed, to accommodate changes in the database, automatically or manually. For information on refreshing lists of values, see “Chunking long lists of values” on page 74.

Table 4-1 Viewing the list of values for the Quarter object in Universe Designer.Handling prompts for objects that have lists of values involves extending the workflow for many, simple prompts (page 68). To do this you detect if the prompt (object) has an associated list of values with Prompt.hasLOV, if there is a list of values for the prompt, get the values in the list with Lov.getAllValues, then display them in the user input form, with Values.getValue, as options of an HTML select tag.Note: Prompt.getLOV automatically refreshes the report, this can cause problems with nested prompts which need to be handled. See “Handling nested prompts” on page 74.The select tag for the list uses the same dynamic input naming described in “Dynamically creating input names” on page 68.Example: Displaying a simple list of valuesThe following JSP code fragment illustrates how to get the values of a LOV and display them in a form.//get user inputif (doc.getMustFillPrompts()) {

//build a form to get user input for the prompt%><form

name="PromptsForm"action="refresh.jsp"

list of values for the Quarter objectin the eFashion universe


4
method="post">
<table><%for (int i = 0; i < prompts.getCount(); i++) {

Prompt prompt = prompts.getItem(i);if (prompt.hasLOV()) { Values lovValues =

prompt.getLOV().getAllValues();%>

<tr><td><%=prompt.getName()%></td><td><select name=<%="PV"+i%> size=1><%for (int k=0; k < lovValues.getCount(); k++){%><optionvalue="<%=lovValues.getValue(k)%>"><%=lovValues.getValue(k)%></option><%}%></select></td></tr><%

}}

%><tr><td><input name="Submit" type="submit" value="OK">

</tr></td></table>

</form><%}%>

Note: The example “Handling multivalued prompts” on page 72 shows how to modify the select tag to handle multivalued prompts.

Constrained promptsA prompt is constrained if the answer must come from the prompt’s list of values. In Web Intelligence, users create constrained prompts by selecting Select Only From List when creating a prompt filter for a query.You can detect if a prompt is constrained with Prompt.isConstrained.

Multivalued promptsUntil now we have only considered prompts that can have one value, however, some prompts can require several values before being filled. For example, the prompt, Store name in list, can have one or many responses before it is filled, whereas the prompt, Year equals, can have only one response.


4
Note: For prompts that use the Between operator, such as, Sales revenue is between X and Y, the user must specify both X and Y before the prompt can be considered complete. However, Web Intelligence forms these kinds of prompts as two separate prompts, you do not need to treat them as a multivalued prompt.To detect how many values the prompt requires use PromptType.getType. A prompt can either be PromptType.Mono or PromptType.Multi.Example: Handling multivalued promptsThe following JSP code fragment illustrates how to modify the <select> tag of the previous example (page 70) to handle multivalued prompts.<td><%
if (prompt.getType() == PromptType.Mono) {%><select name=<%="PV"+i%> size=1><%

}//multivalued LOV needs a different select statementelse {%>

<select name=<%="PV"+i%> multiple size=5><%}//add values in LOV to the select listfor (int k = 0; k < lovValues.getCount(); k++) { %>

<option value="<%=lovValues.getValue(k)%>"><%=lovValues.getValue(k)%>

</option><%}%></select>

</td>

Prompts with multicolumn lists of valuesA universe designer can create a list of values that has many columns.You detect a list of values with more than one column using Values.isMultiColumns. A multicolumn list of values is represented in REBean as rows in a table with the RowValues interface. To display the values in the list you use Values.getRowValue to get a row in the table, and then RowValue.getHeader and RowValue.getItem to display the values in the list.Note: Prompt.enterValues uses only the first value in each row to identify the row. When the user selects a row, make sure you pass just the value in the first column (index = 0) of the row to Prompt.enterValues. The example below illustrates this.Example: Handling multicolumn lists of valuesThe following JSP code fragment illustrates how to display multicolumn lists of values in the select block of the example on page 70.


4
if (prompt.hasLOV()) { //display the list of values
Values lovValues = prompt.getLOV().getAllValues();%><tr>

<td><%=prompt.getName()%></td><td><%

if (lovValues.isMultiColumns()) {//MULTICOLUMN VALUES (1/2) display the column names

String colNames = "";for (int m = 0; m < lovValues.getRowValue(0).getCount(); m ++) colNames = colNames + " | " +lovValues.getRowValue(0).getHeader(m);%><%=colNames%><br><%

}//assume multivalue LOV%><select name=<%="PromptValue"+i%>

multiple size=5><%//get value and text for the option tagfor (int k = 0; k < lovValues.getCount(); k++) {

String value = lovValues.getValue(k);String valueText = value;if (lovValues.isMultiColumns()) { //MULTICOLUMN VALUES (2/2) option is a row RowValue row = lovValues.getRowValue(k); value = row.getItem(0); valueText = ""; for (int n = 0;n < row.getCount(); n++) { //build a string to display the <option> tag if (n == 0) valueText = row.getItem(n); else valueText = valueText + " | " + row.getItem(n);}

}%><option value="<%=value%>">

<%=valueText%></option><%

}%></select>

</td></tr><%

}

Note: The value and valueText are different in multicolumn lists of values. The variable value contains just the first value in the row, which is passed to Prompt.enterValues to fill the prompt, whereas valueText displays all the values in the row.


4
Chunking long lists of values
Some objects, for example Customer name, can have a very long list of values. The Lov class has methods that you can use to divide long lists of values into “chunks” that are easier to display, and easier for the user to browse:• Lov.getCurrentBatchIndex• Lov.getValues• Lov.getCurrentBatchName• Lov.setBatchSize

Handling nested promptsSometimes a list of values contains its own prompts. A prompt in a list of values is called a nested prompt. Nested prompts can be raised when a document containing prompts is refreshed and the prompts have lists of values that contain their own prompts.If a list of values contains prompts, those prompts must be filled before you can fill the prompts in the next level up.Example: Order of filling a hierarchy of nested promptsConsider the following set of prompts:Select a town from the list: (prompt in query)

Select a state from the list: (prompt on list of towns)Select a country from the list: (prompt on list of states)

Each prompt qualifies the one above it in the hierarchy; the country must be defined before a state can be defined and, similarly, a state must be defined before a town can be defined.

You use Lov.mustFillNestedPrompts to detect if a list of values contains its own prompts, then Lov.getNestedPrompts, Prompt.enterValues and Lov.setNestedPrompts to enter values for and set the nested prompts.Example: Handling nested promptsThe following JSP code fragment illustrates the recommended method for handling nested prompts. In this example, prompts and nested prompts are handled by the recursive function fillPrompts.//get the document and its promptsDocumentInstance doc =

re.getDocumentFromStorageToken(token);if (doRefresh) doc.refresh(); //refresh first time onlyPrompts prompts = doc.getPrompts();//if there are prompts, fill themif (docInstance.getMustFillPrompts()) {


4
this.fillPrompts (prompts, null);docInstance.setPrompts();
}else //all prompts are filled and can now display the report

response.sendRedirect("view.jsp?Token="+doc.getStorageToken());

//FUNCTION - fill prompts and handle nested prompts

public void fillPrompts (Prompts pmts, Lov parentLOV) {//pmts is the set of prompts or nested prompts to be filled//parentLOV is a LOV for which there are unfilled nested

promptsfor (int i = 0; i < pmts.getCount(); i++) {

Lov lov = pmts.getItem(i).getLOV();if (lov.mustFillNestedPrompts()) {

Prompts nestedPrompts = lov.getNestedPrompts();fillPrompts (nestedPrompts , lov);

}//get user input for pmts//enter values for pmts

}if (parentLOV != null) parentLOV.setNestedPrompts();

}

Note: You can use the methods described in “Prompts with simple lists of values” on page 70 to get the user input and enter the values for nested prompts.

Refreshing a list of valuesIf the document contains lists of values with prompts, the prompts on the lists of values must be filled every time the document is refreshed, however, to make sure that the lists are up to date, you can use Lov.refresh to provide a "Refresh List" button so that the user can update the list manually. Note: This process is independent of the document refresh mechanism. After calling Lov.refresh, the next time you call Lov.getValues or Lov.getAllValues, the list of values will be refreshed.

Refreshing a list of values containing nested promptsIf you provide a manual refresh option, you can handle any nested prompts contained in the list of values with the fillPrompts function described in the example “Handling nested prompts” on page 74. Example: Refreshing a list of values containing nested promptsThe following JSP code fragment shows how to use the fillPrompts function described in the example “Handling nested prompts” on page 74 to handle nested prompts raised when the list of values is refreshed manually.


4
//get and display the LOV//if the user clicks "Refresh List" ...lov.refresh();Prompts nestedPmts = lov.getNestedPrompts();this.fillPrompts (nestedPmts, lov);
Handling context promptsUniverse designers define context prompts in universes to ensure users retrieve the appropriate data when there is more than one way to get the results of a query. For more information about defining contexts see Designer’s Guide.The classes and methods, and hence the process, for filling a context prompt is similar to that for filling many, simple prompts (page 68). The contexts in a document are represented by the Contexts collection, and you can detect if a document has contexts to fill with DocumentInstance.getMustFillContexts.To fill a context prompt:If contexts must be filled,1. Get contexts.2. Display the possible values for each context and get the user’s response.3. Enter the values for the context provided by the user.4. Set the contexts.5. View the report.

“Viewing reports” on page 62 explains how to view reports.


4
Displaying a report map
A report map is a representation of the reports and report sections in a Web Intelligence document.There are two modes for calculating the contents of a report map: incremental and non-incremental. In incremental mode only the requested information is calculated, and in non-incremental mode the whole report map is calculated in one step.To get the report map for a document use DocumentInstance.getReportMap.Example: Traversing the report map for a Web Intelligence documentThe following JSP code fragment traverses the following report structure and gets a section as HTML.

// Get the ReportMap from the document instanceReportMap map = doc.getReportMap();//point to the root node of the structureReportMapNodes root = map.getStructure(); // Get the number of reports in the document// There are three in this case: Report1, Report2, and

Report3int count = root.getChildCount();// Get the first reportReportMapNode report1 = root.getChildAt(0);// Get the name of the report (Report1)String reportName = report1.getName();// Get the report path (0)String reportPath = report1.getPath();// Check if the report contains sections (true in this case)boolean leaf = report1.isLeaf();// Get the number of sections in the report

= ReportMapNode

ReportMapNodes

Report1

Report2

Report3

Section1

Section2

Section1

Section2

Section1

Section2

map.getStructure()


4
// There are two in this case: Section1, Section2int section_count = report1.getChildCount();// Get the first sectionReportMapNode section1 =
(ReportMapNode)report1.getChildAt(0);// Get the section name (Section1)String sectionName = section1.getName();// Get the section path (0/0)String sectionPath = section1.getPath();// Get the HTML page associated with this sectionReport report = doc.setPath(sectionPath);HTMLView view = report.getView(OutputFormatType.HTML);



Drilling in Web Intelligence Reports

chapter

5
Overview
Drilling is one of the key features of Web Intelligence documents, helping users analyze document data.This chapter discusses how to provide drilling facilities for Web Intelligence documents.

Introduction to drillingDrilling is a way for a user to control the amount of detail in a report.Universe designers create hierarchies of dimensions when they create universes, for example Country, State, City, Zip Code, Street. When users view reports, they can adjust the amount of detail in the reports by entering drill mode and drilling up or down according to the dimension hierarchies (often called “drill hierarchies).Note: Depending on their user rights, some users might not have access to the drilling functions.Users set the scope of analysis to control how much data Web Intelligence includes in the data provider (cube) it creates when a query is executed.When a user executes a query, Web Intelligence retrieves data for the dimensions in the query, but also for the dimensions that the user has included in the scope of analysis. This means that when a user drills through a dimension hierarchy the information for the new report is in the data provider, and it is not necessary to execute a new query to display the drilled report. See also “Drilling out of scope: the scope of analysis” on page 82.Note: The user executing the query might not be the user that set the scope of analysis.You use REBean to drill in Web Intelligence reports.

The drilling processTo provide users with a drill function, implement the following process:1. User requests a drill operation by clicking on a drill link in a report.

The request contains information about the drill operation. For example, the name of the script that will handle the request, from which dimension the drill starts, and to which dimension it goes.

2. The script defines the drill operation by initializing the document’s drilling objects with the information passed in the drill request.


5
3. The script instructs Web Intelligence to generate the HTML for the drilled
report.Web Intelligence uses the information in the document’s drilling classes to generate the drilled view.

4. The script displays the drilled view generated by Web Intelligence.5. Repeat steps 2 to 4 for each request for a drill operation.

Table 5-1 The process you need to implement to provide a drilling function

Defining the drill operationYou can only define drill operations for drillable documents. A document is considered drillable if the dimensions used to form the query are part of a dimension hierarchy.Defining the drill operation involves:• getting the parameters of the drill request• defining the query string parameters• entering and leaving drill mode• setting the drill path

Drill Option

Define drill

Generate HTML

View report

view.jsp

2

3

4

drill request

drill request

Drill Path 5

1


5
The details of how you define the drill operation depend on the type of report. For information on defining the drill operation for Web Intelligence reports see page 83.
Generating the HTML and viewing a drilled reportThis step in the drilling process involves generating the HTML for the report using the drill operation you have defined. Once you have done this you can view the report as HTML using the normal workflows.

Drilling out of scope: the scope of analysisAn out of scope drill is one that goes up or down to a dimension that is not in the data provider. To fulfill this request the query must be reformed and rerun to retrieve the requested data.You can handle out of scope drills manually or transparently. How you manually handle out of scope drills depends on the type of report, however the mechanism for transparently handling out of scope drills does not depend on the report type.For information on manually handling out of scope drills for Web Intelligence reports see page 88.

Transparent Drill Outside of CubeThe Web Intelligence facility for automatically handling out of scope drill requests is called Transparent Drill Outside of Cube. When this is functioning, the scope of analysis of the query is automatically reset to incorporate the data for the requested dimension.Supervisors can control a user’s access to this facility using Supervisor.

Drill hierarchiesHierarchies contain dimensions and are defined by universe designers. You can see drill hierarchies in the Report Panel.A dimension contains a list of values. When a value is selected from the list, it acts as a dimension filter.


5
Drilling in Web Intelligence reports
To provide drilling functions in Web Intelligence reports you can implement the process described in “The drilling process” on page 80, or use the drill bar to filter the query.

Drilling informationYou 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 universeUse 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 barDrillBar 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 operationA 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 modeYou 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.


5
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 parametersIn 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” on page 82).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.gifExample: Defining the query string parametersThe 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 drillingDrillOption 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 requestTo 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");


5
String[] from = request.getParameterValues("From");String[] hierarchy =
request.getParameterValues("Hierarchy");String[] filter = request.getParameterValues("Filter");

Setting the drill pathThe drill path defines the drill operation. To set the drill path:1. Get the drill path.2. Set the drill action.

See “Setting the action: up, down, by, or slice” on page 85 below.3. Set the block id.4. Set the object id of the drill to element.5. Set the object id and filter of the drill from element.

Setting the action: up, down, by, or sliceA user’s drill actions are classified by how they move through the drill hierarchies.

Table 5-2 Different drill actionsYou set the drill action with DrillPath.setAction.The actions are enumerated by DrillActionType.

Drill action Resulting 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.

hierarchy 1 hierarchy 2dimension 1

dimension 2

dimension 3

dimension 4

dimension 5

dimension 6

dimension 7

upby

down or by

down

slice


5
Setting the from and to parametersTo 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 pathThe 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” on page 84.DrillPath drill = info.getDrillPath();//set the ACTIONif (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 BLOCKdrill.setBlockID(block);//set the TO drill elementsif (to.length > 0) {

DrillElements toElements = drill.getTo();for (int j = 0;j < to.length; j++) {

DrillToElement toElement = (DrillToElement) toElements.add();

toElement.setObjectID(to[j]);}

}


5
//set the FROM drill elementsif (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 reportTo 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” on page 88. See also “Viewing an individual report in HTML” on page 63).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 drillingThe 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.• bomenuIE.js• browserDetection.js• drillcontext.js• drillcontextDom.js• /language/language/message.js

Where language is the language of the messages.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:


5
• /businessobjects/enterprise11/desktoplaunch/viewers/cdz/style/
skin_name/bomenu.cssskin_name is one of: skin_default, skin_corporate, or skin_coloredline.The fonts used in bomenu.css do not include some special characters. To display characters such as the yen symbol (¥) use bomenu_fe.css.

• /businessobjects/enterprise11/desktoplaunch/viewers/cdz/images/

Referencing the Java script files for drillingThe 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” on page 88.

Displaying the drilled reportTo 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 reportThe 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>

<head>

<link rel="stylesheet"type="text/css" href="style/bomenu.css">

<%=htmlHeader%></head>

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

</html>

Manually handling out of scope drill requestsOnce 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.


5
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” on page 89.
Adding objects that have promptsIf 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” on page 66 to find out how to do this.

Filtering with a drill barThe 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 barYou 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


5
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” on page 88.
Taking a snapshot of a drillYou 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.



Building and Editing Data Providers

chapter

6
Overview
A data provider holds information about a query. Using a data provider you can get the SQL for a query, retrieve the data returned when the query is executed, and explore the data source (universe) through which the data was retrieved.This chapter explains how to use REBean to build data providers and edit queries for Web Intelligence reports.

Data providersA data provider has two parts: a query and a data source.

The queryThe query part of a data provider defines the data to be retrieved. The query is expressed in terms of the data source objects (universe objects, also known as result objects) of interest and conditions which restrict the data retrieved.The query can also have an associated scope of analysis which includes more data in the retrieved microcube than the query requires. This helps when you are providing drilling features (see “Scope of analysis” on page 99 and “The drilling process” on page 80).The query of a data provider is exposed in REBean through the Query and Scope objects. Conditions on queries are expressed as a syntax tree in which conditions and operators (for example AND, and EQUAL TO) are nodes in the tree. This syntax tree is created with the ConditionContainer set of classes. See “Conditions” on page 100.

The data sourceThe data source of a data provider gives you access to the universe used to define the query. REBean exposes the following universe elements:• class• hierarchy• dimension• measure• detail• predefined condition


6
Using the classes that expose these universe elements, you can present the contents of a universe to users as classes and objects for query editing, or as drill hierarchies in a drill bar. Use the following classes to explore a universe:• DataSource (universe)• DataSourceObjects (classes and hierarchies in the universe)• DataSourceObject (elements of the universe)
Universe elements can be classes, conditions, dimensions, details, measures, or hierarchies.DataSourceObject is a specialization of the TreeNode class.

Note: You use DataSourceObject to create and edit the query, but after you execute the query the objects are stored in the document's dictionary as ReportExpression objects.


6
Building a data provider
You can build a data provider by:• integrating the Web Intelligence Java Report Panel into your application• building a data provider manually with REBean classes

Integrating the Web Intelligence Java Report Panel into your applicationThe Web Intelligence Java Report Panel is the standard method for users to create data providers and edit queries.

Table 6-1 The Web Intelligence Java Report PanelNote: This applet is different from previous releases of Web Intelligence.

Launching the Web Intelligence Java Report PanelYou launch the Web Intelligence Java Report Panel using JSP. You use the <applet> or <object> tag to declare the applet, and the <param> tag to specify the applet’s parameters. All parameters are of the type java.lang.String.


6

Parameters Value(s) Description

Applet parameterscode “com.businessobjects.w

p.tc.TCMain”The path to the applet.

useslibrary “Web Intelligence Report Panel”

The name of the applet.

useslibrarycodebase “/webiApplet/ThinCadenza.jar”

The path to the archive containing the applet

HelpRoot - The path to the online help.

Lang “en”; “jp” The language of the user interface.

Server parametersServer - The name of the

server from which the applet is downloaded.

Isapi “/servlet/com.businessobjects.cdzlet.CadenzaServlet”

The path to the servlet through which the server and the browser communicate.

Port default is “8080” The port used for the application server

CdzSession use the string returned by ReportEngine.getServerInstance

The session identifier for the open document.

Document parametersToken use the string returned

by DocumentInstance.getStorageToken when editing an open document

The storage token for the document.

RepoType “corporate”; “inbox”; “personal”.

The type of the repository in which the document is stored.

DocumentID - The id of the document.


6

You can use the implicit JSP request object (javax.servlet.http.HttpServletRequest) to get the values for some of these parameters. For example, you can use request.getServerName and request.getServerPort to populate the Server and Port parameters.Note: Some parameters are optional depending on what you are doing with the applet. For example, if you are creating a new document, you do not need to provide a storage token.Example: Launching the Web Intelligence Java Report PanelThe following example shows JSP functions that use BusinessObjects Enterprise SDK to recover a universe object from a valid ID. This Universe can be used to supply information necessary to start the Java Report Panel<%!IInfoObject getUniverse(IInfoStore iStore, String ID){

IInfoObjects universes = null;IInfoObject universe = null;try{

String sQuery = "SELECT SI_CUID, SI_NAME FROM”+ “ CI_APPOBJECTS WHERE SI_ID = " + ID + " AND SI_KIND = '"+ CeKind.UNIVERSE +"'";

universes = (IInfoObjects) iStore.query(sQuery);if(universes.size() > 0)

universe = (IInfoObject)universes.get(0);}catch(Exception e){

universe = null;}return universe;

}%>// The following JSP script retrieves all necessary// parameters and then launches the Web Intelligence Java// Report Panel.<%IInfoStore iStore = (IInfoStore)

session.getAttribute("InfoStore");

DocumentName - The name of the document.

OpenFirstClassOfUniverse - If present, the applet automatically opens the first class of the universe.

Data source parametersUniverseID - The id of the universe

on which the query will be run.

Parameters Value(s) Description


6
ReportEngine wiRepEngine = (ReportEngine)
session.getAttribute("ReportEngine");String ID = request.getParameter("uID");universe = getUniverse(iStore, ID);if (universe != null){

String currPath = request.getServletPath();String contextPath = request.getContextPath();String serverName = request.getServerName();int serverPort = request.getServerPort();

currPath = currPath.substring(0, currPath.lastIndexOf( '/' ) + 1 );

currPath = contextPath + currPath;String instanceID = wiRepEngine.createServerInstance();String strWISession =

instanceID.substring(0,instanceID.indexOf(","));%><APPLET CODE="com.businessobjects.wp.tc.TCMain"

CODEBASE="<%= contextPath %>/webiApplet/" ARCHIVE="ThinCadenza.jar" style="

width: 100%; height: 100%;"><PARAM NAME=CODE VALUE="com.businessobjects.wp.tc.TCMain" ><PARAM NAME=CODEBASE VALUE="<%= contextPath %>/webiApplet/"><PARAM NAME=ARCHIVE VALUE="ThinCadenza.jar" ><PARAM NAME="type"

VALUE="application/x-java-applet;version=1.4"><PARAM NAME="Isapi"

VALUE="<%= contextPath %>/CadenzaServlet"></PARAM><PARAM NAME="Server" VALUE="<%= serverName %>"></PARAM><PARAM NAME="Protocol" VALUE="http"></PARAM><PARAM NAME="Port" VALUE="<%= serverPort %>"></PARAM><PARAM NAME="Type" VALUE="signed"></PARAM><PARAM NAME="WebiSession"

VALUE="<%= strWISession %>"></PARAM><PARAM NAME="CdzSession" VALUE="<%= instanceID %>"></PARAM><PARAM NAME="DocumentID" VALUE=""></PARAM><PARAM NAME="UniverseID"

VALUE="UnivCUID=<%=universe.getCUID()%>"></PARAM><PARAM NAME="bRobot" VALUE="false"></PARAM><PARAM NAME="bTraceInLogFile" VALUE="false"></PARAM><PARAM NAME="HelpRoot"

VALUE="<%= contextPath.substring(1) %>"></PARAM><PARAM NAME="SaveAs"

VALUE="<%= contextPath %>save.jsp"></PARAM><PARAM NAME="Lang"

VALUE="<%= request.getLocale().getLanguage() %>"></param>

</APPLET>


6
Building a data provider manually
When you create a new document instance, Web Intelligence automatically creates an empty data provider for the document. The data provider has a data source and an empty query object. Building a data provider consists in populating the query object with the data source objects in which you are interested.To build a data provider:1. Get the collection of data providers for the document.2. Get the universe elements in which you are interested.3. Get the query for the data provider.4. Add result objects.5. Add condition objects (optional).6. Execute the query.Example: Building a data providerThe following JSP code fragment illustrates how to populate the query object of a data provider.//select a universe ==> sID...//create a new document instanceDocumentInstance doc = reportEngine.newDocument(sID);DataProviders dps = doc.getDataProviders();// Retrieve the 1st data providerDataProvider dp = dps.getItem(0);// Retrieve the universe objectsDataSource ds = dp.getDataSource ();DataSourceObject city =

ds.getClasses().getChildByName("city");DataSourceObject year =

ds.getClasses().getChildByName ("year");DataSourceObject sales =

ds.getClasses().getChildByName ("sales");Query q = dp.getQuery();// Add result objects to the queryq.addResultObject (city);q.addResultObject (year);q.addResultObject (sales);// Run the query: execute the query and fetch the datadp.runQuery();

Editing queriesA query is represented by the Query object and has the following parts:• a list of result objects


6
• a scope of analysis that defines the amount of data available in the cube• conditions that restrict the amount of data retrieved from the data source
To get the query for a data provider, use DataProvider.getQuery.

Result objectsA result object is a class or an object in a universe. Including a result object in the query is the same as dragging and dropping an object into the Results area of the Query Panel of the Web Intelligence Java Report Panel. When you execute the query, the result object is added to the report dictionary (as a report expression, see “Block structure: axes and report expressions” on page 110) and is available for editing reports.To add a result object to the query, use Query.addResultObject.To remove a result object from the query, use Query.removeResultObject.

Scope of analysisThe scope of analysis is a feature that enables you to include more information in a cube than the query requires. This is very helpful in drilling as it is avoids modifying the query for every drill operation. See “Drilling in Web Intelligence Reports” on page 79.The scope of analysis is defined in terms of the scope level and is represented by the Scope interface. The scope level specifies how many objects of a class hierarchy are retrieved when you run the query. The scope level can be LEVEL_1, LEVEL_2, LEVEL_3, or CUSTOM.A scope level of LEVEL_1 indicates that just the result object specified in the query is retrieved. A scope level of LEVEL_3 indicates that the first three objects in the class hierarchy, starting with the result objects specified in the query, will be included in the retrieved results.If you modify the elements in the scope of analysis, Web Intelligence changes the scope level accordingly. If you create a scope of analysis that does not match an existing hierarchy, for example, if you remove the Quarter object from the scope of analysis so that a drill on the Year goes to the Month object, the scope level is set to CUSTOM, however, if you remove the third level from a LEVEL_3 scope of analysis, Web Intelligence sets the scope level to LEVEL_2.To get the scope of analysis for a query, use Query.getScope.To modify a scope of analysis add and remove the objects you want in the scope of analysis with Scope.addScopeObject and Scope.removeScopeObject.


6
Conditions
A condition is a constraint on the data retrieved when you run a query, and is sometimes called a query filter.For example, if you add the result objects Year, Revenue, Store, and Company Average, then define the condition ((Year between 1995 and 1999) AND (Revenue < Company Average)), the query would return only data about the stores that, between 1995 and 1999, achieved revenues below the company average. For more information on conditions see Web Intelligence User’s Guide.

Simple conditionsThe simplest condition consists of a container, a data source object, and unary operator. For example, in the condition (Revenue is not NULL), “Revenue” is the object, and “is not NULL” is the operator.In REBean, this condition is represented as follows.

The FilterCondition class holds information about operators and operands. For some operators, such as BETWEEN, the FilterCondition contains more than one operand.Example: Creating a simple conditionThe following JSP code fragment creates the condition (Revenue < 10000).Query q; //query to which the condition is applied//create a container for the conditionConditionContainer c1 = q.createCondtion();//create an object for the conditionConditionObject co = c1.createConditionObject(revenue);//create a FilterCondition object to contain information//about the operator and the operandFilterCondition fc =

co.createFilterCondition(Operator.LESS);fc.createFilterConditionConstant("10000");

Complex conditionsBy combining containers with operators and adding extra condition objects you can build very complex conditions.

FilterConditionContainerConditionObjectgetDataSourceObject = Revenue

FilterConditiongetOperator = NOT_IS_NULL


6
Example: Structure of a complex conditionThe following is a representation in REBean of the condition:
(Revenue < 1000000) OR ((Year = 2002) AND (Holiday)).

In this example the data source object used for the last part of the condition (Holiday) is a predefined condition that is part of the universe, and it does not need a corresponding FilterCondition object.

Including a prompt in a conditionTo include a prompt in a condition use FilterCondition.createConditionPrompt.This method returns a ConditionPrompt object that you can use to define a prompt that is activated when the query is executed.As with normal prompts when you create a condition prompt you need to define the name of the prompt (that is, the question that is asked). You can also define properties such as its default value, and whether or not it is constrained to a list of values.You handle these prompts with the same workflows that are described in “Handling prompts” on page 66.Example: Including a prompt in a conditionThe following JSP code fragment creates the condition prompt “Year?”//get the query (q) to which the condition is applied//...//create a container for the conditionConditionContainer cc = q.createCondition();//create an object for the conditionConditionObject co = cc.createConditionObject(country);//create a FilterCondition object to contain the promptFilterCondition fc =

co.createFilterCondition(Operator.EQUAL);//define the prompt

FilterConditionContainer(OR)ConditionObjectgetDataSourceObject = Revenue

FilterConditiongetOperator = LESSgetOperand = 1000000

FilterConditionContainer(AND)ConditionObjectgetDataSourceObject = Holiday

ConditionObjectgetDataSourceObject = Year

FilterConditiongetOperator = EQUALgetOperand = 2002


6
ConditionPrompt cp = fc.createConditionPrompt("Country?");cp.setConstrained(false);cp.setMonoValue(true);cp.addDefault("Australia");
Executing queries and retrieving the dataWhen a query is executed and data retrieve, contexts and prompts are raised that need to be handled. It is possible to execute a query without retrieving data, in which case no prompts or contexts need to be handled.

DataProvider.runQuery puts the data it retrieves into the results recordset of the data provider.Use DataProvider.getResults to retrieve the recordset. For an example of how to access the values in the recordset see “Working with Recordsets” on page 119.

Getting the SQL for the queryWeb Intelligence uses the properties of the Query object to create the SQL statement it executes when you execute the query.To get the SQL for a query, use Query.getSQL.

To execute the query and… Use…

not retrieve the dataThe user does not need to set any prompts or contexts.

DataProvider.executeQuery

retrieve the dataIf there are prompts or contexts, the user must set these using the same procedure as for viewing a document.

DataProvider.runQuery



Formatting Reports

chapter

7
Overview
Web Intelligence SDK contains classes and methods for controlling the format of reports. Applications for formatting Web Intelligence reports (*.wid) create and edit document structures, sections, cells, and page decoration.This chapter discusses how to use REBean to format Web Intelligence reports.

Creating and editing the document structureYou can access and change the structure of a Web Intelligence document. A Web Intelligence document is made up of at least the following elements:• report• page header/footer• report body

A document can also contain:• sections• blocks• report cells• free cells

It is often useful to create a blank Web Intelligence document within which you can manually build queries and report structures.To create a blank document use DocumentInstance.newDocument.Example: Creating a blank documentThis example shows a JSP functions that use BusinessObjects Enterprise SDK to recover the ID of the Universe parent folder. Using this ID an IInfoObjects containing information about Universes stored in the Central Management System is returned.

IInfoObjects getUniverses(IInfoStore iStore, int searchID) {int ROOT_FOLDER_ID = 95;IInfoObjects rootDirs = null;IInfoObjects universes = null;

String rootQuery = "SELECT SI_ID, SI_NAME FROM”+ “ CI_APPOBJECTS WHERE SI_PARENTID="+ ROOT_FOLDER_ID ;

String unvQuery = "SELECT SI_ID, SI_NAME, SI_CUID,”+ “ SI_OWNER, SI_PARENTID, SI_KIND"+ " FROM CI_APPOBJECTS WHERE SI_ANCESTOR=";


7
try{
//get the Universe Root directoryrootDirs = iStore.query(rootQuery);if (rootDirs.size() > 0){

//Get the UniversesIInfoObject rootDir =

(IInfoObject)rootDirs.get(0);unvQuery += rootDir.getID();universes = iStore.query(unvQuery);

}}catch (SDKException sdke){

universes = null;} catch (Exception e){

universes = null;}return universes;

}

The following code fragment creates a blank document using the first universe in the collection of universes as a data source.//Recover the universe listIInfoStore iStore =

(IInfoStore)session.getAttribute("InfoStore");ReportEngine webiRepEngine =

(ReportEngine)session.getAttribute("ReportEngine");IInfoObjects universes = getUniverses(iStore, iID);//Get the first universeIInfoObject universe = (IInfoObject)universes.get(0);//then create the blank documentDocumentInstance doc =

webiRepEngine.newDocument(universe.getID());


7
Representing document structure through containment
Document elements are structured according to their containment relationship.

The containment relationship between the elements of a document is represented in the object model as a tree using TreeNode, ReportElementContainer, and ReportElement.

Table 7-1 Structures of a document with one report, one section, and two blocks, and another with one report, two sections, and one block.Notice that, to have two sections in a report, the relationship between the sections is containment.

This element… Can contain these elements…

report page header/footer, report bodyreport body sections, blocks, and cellspage header/footer cellssection sections, blocks, and cells

report

page headerfree cell

report body

page footerfree cell

free cell

section

free cell

report cell

block

block

report

page headerfree cell

report body

page footerfree cell

section

section

block


7
Example: Creating a document structureThe following code fragment creates the document structure shown in the diagram. This code creates a new document and a report and adds information to the header and footer parts. It then creates a section and a block and adds universe objects (report expressions) to the block.//create an empty document and a new reportDocumentInstance doc = engine.newDocument("1");ReportContainer report = doc.createReport("My Report");
PageHeaderFooter header = report.getPageHeader();Cell headerCell = header.createFreeCell("header cell");PageHeaderFooter footer = report.getPageFooter();Cell footerCell = footer.createFreeCell("footer cell");

BodyReport body = report.getBodyReport();// create a sectionSectionContainer sectionYear = body.createSection();sectionYear.getAxis().addExpr(yearExpr); //[Year]// create a blockReportBlock block1 = sectionYear.createBlock ();BlockAxis hAxis = block1.getAxis(TableAxis.HORIZONTAL);hAxis.addExpr(quarterExpr); //[Quarter]// create another blockReportBlock block2 = body.createBlock ();BlockAxis hAxis2 = block2.getAxis(TableAxis.HORIZONTAL);hAxis2.addExpr(revenueExpr); //[Sales Revenue]

doc.applyFormat();

Table 7-2 Report structure defined by the code example aboveNote: The header, footer, and report body elements are created by default. Also, when you create a block, the default type is TableType.HTABLE.


7
Positioning document elements
By default, elements are positioned using x-y co-ordinates referenced from the top left corner of the containing element.

You can express x and y in millimeters or inches.

Using attachments to avoid overlapping elementsSince the size of some elements, for example table blocks, is not known at the time the report is formatted, sometimes elements overlap. To avoid this you can use the attachment feature.An attachment is a way to position a Cell or ReportBlock element relative to other elements. An attachment consists of a vertical anchor, horizontal anchor and a pair of x-y co-ordinates.Vertical anchors can be either TOP, BOTTOM or NONE. Horizontal anchors can be either RIGHT or LEFT or NONE. For example, in the diagram below the attachment between block 1 and block 2 has a vertical anchor set to BOTTOM and a horizontal anchor set to NONE, and the anchor between block 1 and cell 1 has a vertical anchor set to NONE and a horizontal anchor set to RIGHT.

Table 7-3 Positioning elements relative to the parent container and siblings.

body report

free cell

x

y

cell 1

block 2

yb1

xb1 xc1

block 1

attachmentb1-c1

attachmentb1-b2yb2


7
Example: Creating an attachmentThe following Java code fragment creates and positions the elements shown in the diagram above. In this example, the x and y co-ordinates’ parameters are in millimeters and are cast to the required type (double) using the “d” operator.//units = UnitType.MILLIMETER// Create block 1 (b1) as child of the ReportBody containerReportBlock b1 = report.getReportBody().createBlock();// Set the block’s position relative to its containerb1.setX(150d); // Xb1b1.setY(10d); // Yb1
// Create block 2 (b2) and cell 1 (c1)ReportBlock b2 = report.getReportBody().createBlock();ReportBlock c1 = report.getReportBody().createFreeCell(" ");

// Attach cell 1 to block 1 (RIGHT attachment): b1-c1c1.setAttachTo(b1, VAnchorType.NONE, HAnchorType.RIGHT);// Position cell 1 relative to block 1c1.setX(200d); // Xc1

// Attach block 2 to block 1 (BOTTOM attachment): b1-b2b2.setAttachTo(b1, VAnchorType.BOTTOM, HAnchorType.NONE);// Position block 2 relative to block 1b2.setY(200d); // Yb2

Creating and editing sectionsA report can have zero or more sections, each one containing blocks, cells and/or other sections. A section has one axis with one report expression, and, by default, each report expression has a corresponding report cell.To check if a report cell is a section container use: ReportCell.isSection.When you add report expressions to the section’s axis, they are added to the right of the last one added.Example: Editing the sections of a reportThe following code fragment creates two sections, one for Year and another for Country.SectionContainer sc, sc2;ReportExpression reYear;ReportExpression reCountry;

sc.getAxis().addExpression(reYear);sc2 = sc.createSection();sc2.getAxis().addExpression(reCountry);


7
When you add an expression to the axis of a section, a cell for the expression is automatically created. In the example above, report cells for =[Year] and =[Country] are created.
Creating and editing blocksBlock is a generic name for tables, cross tables, forms, and graphs.

Block structure: axes and report expressionsA block axis is an oriented collection of one or more report expressions.A report expression is a report object or a variable. For example, [Customer].Report expressions are stored in the document dictionary when a query is executed, and are represented in REBean by the ReportExpression interface.Sections and report blocks have axes. A section has one axis. A report block has one, two, or three axes. The following table shows the axes for each type of block.

For a vertical table the report expressions are displayed in columns.

Table 7-4 Structure of a vertical tableNote: The block type determines the operators applied to the expression in the report. For example, in the above example the report expression [year] is shown in the table as NameOf([year]) and =[year].For a horizontal table the report expressions are displayed in rows.

Block type Axes

vertical table one horizontal axishorizontal table one vertical axiscross table horizontal, vertical, and content axesgraph x, y, and z axes


7

Table 7-5 Structure of a horizontal tableFor a cross table the report expressions are displayed in columns and rows with a shared body.

Table 7-6 Structure of a cross tableIn a graph the report expressions are displayed as a picture with two or three dimensions.


7

Table 7-7 Structure of a graphExample: Building a report: adding expressions to axesThe following code fragment builds a report structure by retrieving the report expressions from the document dictionary.// Retrieve the dictionary associated with the document// populated by the last call to Document.runQueryReportDictionary dico = doc.getDictionary();

// Create a new reportReportContainer report = doc.createReport("My Report");BodyReport body = report.getBodyReport();

// Create a section as the body report childSectionContainer section = body.createSection ();ReportExpression ctryExpr =

dico.getChildByname("ParentCountryID");

// Add the country object on the section axissection.getAxis().addExpr(ctryExpr);

// Create a block in the section containerReportBlock block = section.createBlock ();

ReportExpression yearExpr = dico.getChildByName("ParentYearID");

ReportExpression revExpr = dico.getChildByName("ParentRevenueID");

// Add the Year and Revenue objects on the vertical axis of // the horizontal table.block.getAxis (TableAxis.HORIZONTAL).addExpr (yearExpr);block.getAxis (TableAxis.HORIZONTAL).addExpr (revExpr);


7
doc.applyFormat ();
Sorting report expressionsYou can sort report expressions into ascending or descending natural order. The natural order of an object is the one used in the database.Sorts are stored in a collection (Sorts) that defines the type and priority of the sort. By default the first sort in the collection has the highest priority.

BreaksYou can add breaks to report expressions. You can add breaks to report expressions belonging to an axis, and you can show or hide the break’s header and footer using the BreakElement interface. By default the header and footer are hidden.Breaks are stored in a collection. The first element in the collection has the highest priority.

CalculationsYou can add a calculation to a report expression. For example, the predefined calculation Sum adds the values of the report expression.By default, the results of a calculation are placed in the footer of a table, and use the name of the calculation as a label for the result. For a percentage calculation, a Percentage column is also added.

Representing a blockA block can be represented as a vertical or horizontal table, a cross table, a form, or a graph. The interface Representation defines how a block is represented.

Vertical and horizontal tablesThe header, footer and body of the table are exposed through the Table class as a CellMatrix collection, which contains TableCell objects. Vertical and horizontal tables use the SimpleTable specialization of Table.You can change the following properties of the header, footer and body of a table with the Table interface:• visibility• repetition• decoration


7
The settings on low level objects are inherited from their parents but, if changed, override those of their parents.
Cross tablesCross tables use the CrossTable specialization of Table, and the cells in a cross table are grouped into zones.

The zones correspond to parts of a cross table in structure view.Zones that can contain more than one cell, for example Body - Body, contain a matrix of TableCell objects that are contained in the collection CellMatrix.Note: If you add a break to the report expressions in a cross table, each break has its own header and footer and each zone (except Body - Body) contains a division for each break.

FormsForms are represented by the Form interface. The cells in the form are represented by a CellMatrix object, and you can set the decoration of labels and values separately.

GraphsGraphs are represented by the Graph interface, and a set of interfaces that represent parts of the graph: Legend, GraphTitle, GraphData, GraphAxisValues, GraphAxisProperties, Graph3D, and Wall.Developer Suite supports the following graphs.

Top - Left Top - Body Top - RightBody - Left Body - Body Body - RightBottom - Left Bottom - Body Bottom - Right


7

Graph category Graph type

Bar Vertical GroupedHorizontal GroupedVertical Line and BarHorizontal Line and BarVertical StackedHorizontal Stacked Vertical PercentHorizontal Percent3D

Line Vertical MixedHorizontal MixedVertical StackedHorizontal Stacked Vertical PercentHorizontal Percent3D3D Surface

Area Vertical AbsoluteHorizontal AbsoluteVertical StackedHorizontal Stacked Vertical PercentHorizontal Percent3D Area3D Surface

Pie Pie Doughnut3D Pie3D Doughnut

Radar & Scatter Stacked Area RadarPolarScatterRadar Line


7
Creating and editing cells
A cell is a report element that contains information such as the title of the report, or the heading of a section. There are two types of cell: free cell, and report cell.Free cells contain a string and are exposed with the class FreeCell. Report cells contain a formula of a section axis and are exposed with the class ReportCell.You can add a cell to all the elements contained in a report element. For more information on containment rules see “Representing document structure through containment” on page 106.

Creating and editing the page decorationPage decoration refers to the display aspects of the contents of a cell. For example, the font, color, and size of the text in the cell. You can control the decoration of most cells in a report using the Decoration interface. The Decoration interface provides a gateway for other interfaces such as Alignment, Attributes and Font.

AlignmentUsing the Alignment interface you can set the horizontal and vertical alignment of the cell contents. You can also set the wrapping properties of text in the cell.

AttributesThe Attributes interface represents the “non-font” aspects of the cell’s presentation. Using this interface you can set properties such as the background and foreground image, the color of the foreground and background, and the properties of the cell border (which is represented by the interface Border).

FontThe Font interface allows you to determine the color, style, size and font name of the text in the cell.


7
Page layout
You can control the page layout of a report using the PageLayout, Visibility and Repetition classes. The classes give you control over how blocks behave around page breaks, repeating blocks on every page, displaying calculations and breaks, and hiding and showing the elements of a report.

Paper sizeYou can set the page size for the document to the following paper sizes: Custom, A4 to A0, and Letter, and orient the page in landscape, or portrait views.All the margins are adjustable and you can set the units to millimeters, or inches.


7



Working with Recordsets

chapter

8
Overview
Web Intelligence SDK often uses the recordset data structure for storing information such as the results in a data provider.This chapter explains how to use the recordset classes of the Web Intelligence SDK.

Anatomy of a recordsetIn Web Intelligence SDK recordsets provide a generic way of representing the data about, or contained in, a group of objects.

Each recordset is divided into rows and columns. Each row can be considered a record (or a set of fields) and you can access only one record at a time.

Recordsets in REBeanIn REBean the Recordset class represents recordsets.

Field namesRecordset.getColumnName(n) gives the name of the nth field in the current record.The names of the fields in most recordsets are fixed. You can find the names listed under the method descriptions in the Web Intelligence SDK Online Reference. The exceptions to this are DataProvider.getResult which returns a recordset in which the names of the fields are the names of the results (columns) of the query.

a b c 10.0

current recordrecordset

field fieldsd e f 20.0

g h i 30.0

j k l 40.0

m n o 50.0p q r 60.0

s t u 70.0


8
Moving around the recordset
Recordset can contain only one record (row) at a time. To load it use the move methods of Recordset:• first, last, next, previous, and setRow

The Recordset class has a feature for setting the direction. You can set the direction to FORWARD (default) or REVERSE. When the direction is set to FORWARD calling Recordset.next moves to (Recordset.getRow + 1) and when it is set to REVERSE calling Recordset.previous moves to (Recordset.getRow -1). Recordset.first and Recordset.last do not depend on the direction and always move to row 0 and row (Recordset.getColumnCount - 1) respectively.It is good practice to set the direction and call Recordset.first or Recordset.last before you start processing a recordset so that you know which row the Recordset object contains.You can use Recordset.isLast and Recordset.isFirst to control loops that move through recordsets.

Accessing the value of a fieldIn REBean you can access the values of a field directly.To access the fields of a record, use Recordset.getCellObject and provide the index of the column in which you are interested.Example: Accessing the values in a recordsetThe following Java code fragment prints the types of the columns and the contents of the results of a query contained in a data provider.Recordset rs = dp.getResult(0);

// 0: assume query has one flowrs.first();

// Print the column types. They can be Integer, String,// or Date.for (int i = 0; i < rs.getColumnCount(); i++) {

Class c = rs.getColumnType(i);StringBuffer sbt = new StringBuffer();if ( c.equals(Integer.class) )

sbt.append("Integer");if ( c.equals(String.class) )

sbt.append("String");if ( c.equals(Date.class) )

sbt.append("Date");sbt.append(";");System.out.println(sbt.toString());

}

// Print the recordset contents: column names and data


8
while (!rs.isLast()) {
// column namesStringBuffer sbn = new StringBuffer(); for (int j = 0; j < rs.getColumnCount(); j++) {

sbn.append( rs.getColumnName(j).toString() );sbn.append(";");

}System.out.println(sbn.toString());

// datafor (int k= 0; k< rs.getColumnCount(); k++) {

sbd.append( rs.getCellObject(k).toString() );sbd.append(";");

}System.out.println(sbd.toString());

rs.next();}

This code fragment assumes that rs.getDirection equals FORWARD, and that the data provider (dp) has been populated. For more information on populating data providers see “Executing queries and retrieving the data” on page 102.


Migrating Business Objects 6 Customized Applications to BusinessObjects XI

Business Objects Information Resources

appendix

Documentation and information services9
Documentation and information services
Business Objects offers a full documentation set covering its products and their deployment. Additional support and services are also available to help maximize the return on your business intelligence investment. The following sections detail where to get Business Objects documentation and how to use the resources at Business Objects to meet your needs for technical support, education, and consulting.

DocumentationYou can find answers to your questions on how to install, configure, deploy, and use Business Objects products from the documentation.

What’s in the documentation set?View or download the Business Objects Documentation Roadmap, available with the product documentation at http://www.businessobjects.com/support/.The Documentation Roadmap references all Business Objects guides and lets you see at a glance what information is available, from where, and in what format.

Where is the documentation?You can access electronic documentation at any time from the product interface, the web, or from your product CD.

Documentation from the productsOnline help and guides in Adobe PDF format are available from the product Help menus. Where only online help is provided, the online help file contains the entire contents of the PDF version of the guide.

Documentation on the webThe full electronic documentation set is available to customers on the web from support website at: http://www.businessobjects.com/support/.

Documentation on the product CDLook in the docs directory of your product CD for versions of guides in Adobe PDF format.

124Migrating Business Objects 6 Customized Applications to BusinessObjects XI

http://www.businessobjects.com/support/


http://www.businessbojects.com/support/

http://www.businessbojects.com/support/

Customer support, consulting and training 9
Send us your feedback
Do you have a suggestion on how we can improve our documentation? Is there something you particularly like or have found useful? Drop us a line, and we will do our best to ensure that your suggestion is included in the next release of our documentation: [email protected]: If your issue concerns a Business Objects product and not the documentation, please contact our Customer Support experts. For information about Customer Support visit: http://www.businessobjects.com/support.

Customer support, consulting and trainingA global network of Business Objects technology experts provides customer support, education, and consulting to ensure maximum business intelligence benefit to your business.

How can we support you?Business Objects offers customer support plans to best suit the size and requirements of your deployment. We operate customer support centers in the following countries:• USA• Australia• Canada• United Kingdom• Japan

Online Customer SupportThe Business Objects Customer Support website contains information about Customer Support programs and services. It also has links to a wide range of technical information including knowledgebase articles, downloads, and support forums.http://www.businessobjects.com/support/

Migrating Business Objects 6 Customized Applications to BusinessObjects XI125


http://businessobjects.com/support/

http://businessobjects.com/support/

[email protected]

Customer support, consulting and training9
Looking for the best deployment solution for your company?
Business Objects consultants can accompany you from the initial analysis stage to the delivery of your deployment project. Expertise is available in relational and multidimensional databases, in connectivities, database design tools, customized embedding technology, and more.For more information, contact your local sales office, or contact us at:http://www.businessobjects.com/services/consulting/

Looking for training options?From traditional classroom learning to targeted e-learning seminars, we can offer a training package to suit your learning needs and preferred learning style. Find more information on the Business Objects Education website:http://www.businessobjects.com/services/training


www.businessobjects.com/services/consulting.htm

www.businessobjects.com/services/education.htm

www.businessobjects.com/services/consulting.htm

www.businessobjects.com/services/education.htm

Useful addresses at a glance 9
Useful addresses at a glance
Address Content

Business Objects product informationhttp://www.businessobjects.com

Information about the full range of Business Objects products.

Product documentationhttp://www.businessobjects.com/support

Business Objects product documentation, including the Business Objects Documentation Roadmap.

Business Objects Documentation [email protected]

Send us feedback or questions about documentation.

Online Customer Supporthttp://www.businessobjects.com/support/

Information on Customer Support programs, as well as links to technical articles, downloads, and online forums.

Business Objects Consulting Serviceshttp://www.businessobjects.com/services/consulting/

Information on how Business Objects can help maximize your business intelligence investment.

Business Objects Education Serviceshttp://www.businessobjects.com/services/training

Information on Business Objects training options and modules.

Migrating Business Objects 6 Customized Applications to BusinessObjects XI127

http://www.businessobjects.com

http://www.businessobjects.com/support

http://www.businessobjects.com/support



mailto:[email protected]

http://www.businessobjects.com/forms/tipsandtricks_login.asp

http://www.techsupport.businessobjects.com/

http://www.techsupport.businessobjects.com/

http://businessobjects.com/services/consulting/

http://businessobjects.com/services/consulting/

http://www.businessobjects.com/services/training

http://www.businessobjects.com/services/training

Useful addresses at a glance9


Index
Aaccessing
user profiles 25actions

drilling 85Adobe Acrobat 34

see also PDFalignment 116anchors

vertical and horizontal 108applets

Web Intelligence Java Report Panel 94area graph 114attachments 108authentication

passwords 19axis (block) 110

Bbackground 116bar graph 114batched lists of values 74blocks

cells 116creating 110cross tables 114forms 114graphs 114repeating 117representing 113

borders 116breaks 113browsers

storage tokens 38building data providers 91Business Objects

consulting services 126, 127support services 125

training services 126, 127

Ccalculations 113categories 39–47

category details 46category moving 46creating 45deleting 45getting details 46renaming 45user rights, and 39

categorizing documents 39cells

creating 116CESDK

creating a ISessionMgr object 18referencing 17

CESDK objectcreating 20

chunkinglists of values 74

classesreferencing 17

closingReportEngine object 32Web Intelligence sessions 20

colors 116conditions 100

prompts 101structure 101

consultants, Business Objects 126contexts

opening documents 48cookies

sending with JSP 20creating

blocks 110


categories 45cells 116

document structure 104ISessionMgr object 18ReportEngine object 31sections 109

cross tables 114custom 58customer support 125

Ddata providers 91–102

building 94data sources 92executing queries 102

data sources 92decoration

pages 116deleting

categories 45Developer Suite

migration 11dimensions

drilling 82, 85scope of analysis, and 88

displayingdocument lists 48report maps 77

document structure 104attachments 108blocks 110positioning elements 108report expressions 109sections 109

documentationfeedback on 125on product CD 124on the web 124roadmap 124

documents 50

see also reportscategories 39changing names 50creating 104dictionaries 93displaying

document lists 48drillable 81drilling 79opening 13, 48prompts 66properties 58refreshing 14, 66, 75

document lists 49report maps 77saving 50sending 52structure 104types 34Web Intelligence format 31, 83

drill bars 83, 89drill hierarchies 82drill mode 81, 82

entering and leaving 83drill options 84drill path 81, 81, 83

setting 81, 83, 85drilling 79–90

actions 85dimensions 82drill bars 83drill hierarchies 83drill mode 81, 87drill path 81, 83, 85filtering 89generating HTML 82, 87hierarchies 82, 85hyperlinks 81, 83, 84images 87


Java script files 87overview 80

query string parameters 81, 81, 81, 83, 84scope of analysis 82, 88, 99setting parameters 86slice 85snapshots 90transparent drill out of cube 82Web Intelligence reports 83–90

Eediting

blocks 110cells 116data providers 91document structure 104queries 98sections 109

education. See trainingEnterprise Mode authentication 19errors 30exceptions 30executing queries 102

Ffeedback, on documentation 125fields

recordsets 120filtering

drill bars 83, 89drill-by and drill-up actions 86queries 100query conditions 89

fonts 116foreground 116formats

saving 50formatting

layout 117

pagedecoration 116

paper size 117reports 103

forms 114free cells 116

GgetHTMLView 36

drilling 82, 87getting started 11, 16graphs 114

Hhandling

context prompts 76exceptions 30out of scope drill requests 88prompts 66

hello world example 16hierarchies

drilling 83, 85hyperlinks

generating for drilling 81, 82, 83, 84, 87

Iimages

drilling 87importing code in JSP 24include directive

in JSP 24information resources 124InfoView

example workflows 13user profiles 25

Introduction 9


JJava Report Panel see Web Intelligence Java Report Panel

Java script filesdrilling 87

java.util.Properties 26, 58JSP

importing code 24reading a user profile 26sending cookies 20

Llandscape layout 117layout 117line graph 114listing

documents 48lists of values 70–76

batched 74chunking 74constrained prompts, and 71displaying 70multicolumn 72prompts in (nested) 74refreshing 75

log in and log out 16logins 18LOV see lists of values

Mmanaging

documents 34Microsoft Excel

displaying Web Intelligence reports 62output format 64

migration 11, 50multivalued prompts 71

Nnavigating

reports 77nested prompts 74NT Challenge Mode authentication 20

Oobjects

query results 99Online Customer Support 125opening

documents 13, 48out of scope drills 82, 88, 99

Ppackages

java.util.Properties 58page

layout 117page decoration 116paper size 117passwords 18

storage token 36PDF

displaying Web Intelligence reports 62output format 64

.pdf see PDFpie chart 115portrait layout 117prompts 66–76

conditions 101constrained 71context 66, 76drilling 89entering values 72lists of values 70multicolumn lists of values 72multivalued 71nested 74storage tokens 36


properties 58documents 58

Qqueries 92

editing 98executing 102

query conditions 89, 100query strings

drilling 81, 81, 81, 83, 83, 84

Rradar & scatter graph 115REBean

building data providers 91creating a ReportEngine object 31document properties 58exceptions 30features 10formatting reports 103prompts 66

RECOMcreating a ReportEngine object 31prompts 66

RECOM.dll 31recordsets 119–122

changing records 121fields 120

referencingCESDK 17Web Intelligence SDK classes 17

refreshingdocument lists 49documents 14, 66, 75lists of values 75

renaming categories 45RENET

exceptions 30features 10

report expressions 109, 110adding to axes 112

breaks 113calculations 113sorting 113

report maps 77snapshots, and 90

Report Panel see Web Intelligence Java Report Panel

ReportEngine object 31closing 32

reportsdrilling 79, 82, 87filters 89formatting 103–117report maps 77viewing all the reports in a document 62

repositoryopening documents 48sending documents 52

resolving universe contexts 76resources 124result objects 99running queries 102

Ssave to corporate see publishingsaving documents 50scope of analysis 80, 82, 99

handling manually 88scripts

drilling 87sections

creating 109sending documents 52–54session ID

cookies, and 20sessions

closing 20creating 20, 48


settingdrill actions 85

drill parameters 86user profiles 28

settings in user profiles 25slice drill action 85snapshots 90SQL

executing 102storage tokens

advantages 38browser navigation 38generation triggers 35life cycle 35opening documents 48viewing reports 62

supportcustomer 125locations 125technical 125web site 125

Ttables

cross tables 114vertical and horizontal 113

technical support 125temporary files

storage tokens 35training, on Business Objects products 126transparent drill out of cube 82traversing

categories 41report maps 77

triggersgenerating storage tokens 35

Uuniverses 92

resolving contexts 76

user names 18user profiles 25, 48

accessing 25adding to 29setting 28

user rights 48categories, for 39transparent drill out of cube 82

user sessions see Web Intelligence sessions

Vvalues

prompts 70viewing

binary view 62Web Intelligence reports 61–78

Wweb

customer support 125getting documentation via 124useful addresses 127

Web Intelligence documentsbuilding data providers 91formatting reports 103saving 50sending 52

Web Intelligence Java Report Panel 94launching 94

Web Intelligence SDKcreating a ISessionMgr object 18exceptions 30features 34hello world 16login 18migration 11packages 10referencing classes 17


Index

Web Intelligence sessionsclosing 20creating 48storage tokens 38

web sitessupport 125training 126


Index