Customizing Web Intelligence 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 documentation@businessobjects.com. Copyright 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. 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.
Patents
Contents
Chapter 1 Chapter 2 Introduction Introduction to WebIntelligence SDK 7 9 Packages for customizing WebIntelligence . . . . . . . . . . . . . . . . . . . . . . . . 10 Migrating to BusinessObjects XI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 A typical Web Intelligence SDK application . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 3 Application Essentials 15
Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 BusinessObjects Enterprise sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Implementing Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 User preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Reporting essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Chapter 4 Document Management 33
Document types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Document state: storage tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Organizing documents in categories and folders . . . . . . . . . . . . . . . . . . . . 39 Working with documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Document properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Chapter 5 Viewing Web Intelligence Reports 61
Viewing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Handling prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Displaying a report map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Chapter 6 Drilling in Web Intelligence Reports 79
Introduction to drilling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Drilling in Web Intelligence reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Customizing Web Intelligence 3
Chapter 7
Building and Editing Data Providers
91
Data providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Building a data provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Executing queries and retrieving the data . . . . . . . . . . . . . . . . . . . . . . . . 102 Chapter 8 Formatting Reports 103
Creating and editing the document structure . . . . . . . . . . . . . . . . . . . . . . 104 Creating and editing cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Page layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Appendix A Working with Recordsets 119
Anatomy of a recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Appendix B Business Objects Information Resources 123
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Customer support, consulting and training . . . . . . . . . . . . . . . . . . . . . . . . 125 Useful addresses at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Examples
Referencing BusinessObjects Enterprise SDK 17 Instantiating the ISessionMgr class 18 HTML form for gathering a users login information 19 Establishing a session 20 Printing a users preferences 26 Setting a users report panel preference to Java 28 Adding a new preference to a users profile 29 Importing the REBean package 31 Instantiating a ReportEngine object 31 Storage token life cycle 36 how to check that a user has the right to create categories 40 Recursively traversing the category tree 41 Retrieve a users Inbox and Favorites folder IDs 43 Creating a new folder or category 45 Moving and renaming categories or folders 46 Retrieve the properties for a category 46 Displaying a document list 49 Save a Web Intelligence document 50 Scheduling a document 51 Retrieve the list of groups to which a user belongs 52 Sending a document to folders and categories 53 Send a document to the inbox of groups of users 55 Getting the name of a Web Intelligence document using REBean 58 Adding a property to a Web Intelligence document 58 Viewing all the reports in a Web Intelligence document 63 Viewing a report in a Web Intelligence document 63 Viewing a report in Microsoft Excel format 64 Handling a single, simple prompt 66 Dynamically creating input names 68
Examples
Handling many, simple prompts 68 Displaying a simple list of values 70 Handling multivalued prompts 72 Handling multicolumn lists of values 72 Order of filling a hierarchy of nested prompts 74 Handling nested prompts 74 Refreshing a list of values containing nested prompts 75 Traversing the report map for a Web Intelligence document 77 Defining the query string parameters 84 Setting the drill path 86 Displaying the drilled report 88 Launching the Web Intelligence Java Report Panel 96 Building a data provider 98 Creating a simple condition 100 Structure of a complex condition 101 Including a prompt in a condition 101 Creating a blank document 104 Creating a document structure 107 Creating an attachment 109 Editing the sections of a report 109 Building a report: adding expressions to axes 112 Accessing the values in a recordset 121
6 Customizing Web Intelligence
Customizing Web Intelligence
Introduction
chapter
Introduction About this guide
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 guide

To 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 resources

For 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 WebIntelligence

There 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 SDK This package plugs into Business Objects Enterprise SDK. It provides the functions of the Web Intelligence Report Engine.
BusinessObjects Enterprise SDK Crystal Enterprise Documents View Refresh Analyze Platform functions Manage sessions and users Manage documents and categories List universes, documents Schedule
Web Intelligence SDK Web Intelligence documents View Refresh Analyze Create Format Metadata (universe) Explore
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.
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 application

Not 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 essentials
Every 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 users 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 management
Document management features include the ability to list the documents that the current user can view, and, depending on the users 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 reports
An 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 providers

To 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 documents
Formatting 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 workflows
InfoView 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 users 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 workflow

The following diagram shows the workflow for opening a document.
Client pages open a document check for prompts fill prompts until there are none left unfilled fill document toolbar fill report map fill rendering area Web Intelligence SDK
get the report map get the report in the requested format
1
Refresh document workflow
The following diagram shows the workflow for refreshing a document.
Client pages Web Intelligence SDK
<open document workflow> update document toolbar
refresh the report refresh check for prompts fill prompts until there are none left unfilled set the position
fill document toolbar fill report map fill rendering area
get the report map get the report in the requested format
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.
get name and password from user
Name = janderson Pass = *******
open a session
close session
display Hello World and a logout link
Table 2-1 Application for logging in and out of BusinessObjects Enterprise
This 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
2
the user clicks the logout link, the application closes the users 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 SDK

Referencing 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 SDK

To reference BusinessObjects Enterprise SDK, import the BusinessObjects Enterprise packages. Example: Referencing BusinessObjects Enterprise SDK To 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.CeWeb IntelligenceRightID,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 object

To create a ISessionMgr object for an application that uses BusinessObjects Enterprise SDK, instantiate a new ISessionMgr object. Example: Instantiating the ISessionMgr class
ISessionMgr mySessionMgr = CrystalEnterprise.getSessionMgr();
BusinessObjects Enterprise sessions

Every user of Web Intelligence requires a BusinessObjects Enterprise session before entering and using the system. The BusinessObjects Enterprise session represents the users current interaction with BusinessObjects Enterprise. A users BusinessObjects Enterprise session provides access to the users 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 users login information:

2.
name password the Central Management System (CMS) the user wishes to log into authentication type (Enterprise or LDAP)
Establish a valid BusinessObjects Enterprise session for the user.
Getting login information

The simplest way to get a users 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 users 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=submit1 type=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.
Authentication
The 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).
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 Administrators Guide.
Establishing a valid BusinessObjects Enterprise users session

To establish a valid BusinessObjects Enterprise users session: 1. 2. 3. Try to create an IEnterpriseSession object for the user. If the IEnterpriseSession object is valid, store this object in the users session attributes. Create an IInfoStore object and store in the users 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 session The 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 session

Once you have established a valid BusinessObjects Enterprise session for the user, you can retrieve it from the users session attributes.
Closing a BusinessObjects Enterprise session

To 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 users 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-out

BusinessObjects 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 users JSP page will not have access to objects such as IInfoStore stored in the users 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.
index.jsp Name = janderson Pass = ******** login.jsp
logout.jsp
home.html
In this implementation index.jsp displays a form which collects the users 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>
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.jsp
This 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.CrystalEnterp rise" %> <%@ page import="com.crystaldecisions.sdk.framework.IEnterpriseSe ssion" %> <%@ 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 if if if ( ( ( ( CMS == null) CMS = ""; userID == null) userID = ""; password == null) password = ""; 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.IEnterpriseSe ssion" %> <% 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 preferences

With BusinessObjects Enterprise SDK you can get, set and add new preferences in a users profile. Standard preferences and possible settings are: Web Intelligence standard user preference variables, values and meaning. Variable Name webi_view Possible Values P I H Meaning View documents in PDF format. View Documents in Interactive format. View Documents in HTML format. (default) Create documents using the Java Report Panel. (default) Create documents using the HTML Report Panel. Start the drill action in a duplicate report. Start the Drill action in the current report. (default)
webi_panel
java
html
DOCUMENT_WIStartNewDrill
duplicate existing
2
Variable Name Possible Values Meaning Prompt if drill requires additional data. (default) Do not prompt if Drill requires additional data. Synchronize Drill on report blocks. (default) Do not Synchronize Drill on report blocks. Show the Drill bar. Hide the Drill bar. (default) DOCUMENT_WIPromptDrillOutScope N
Y DOCUMENT_WISyncDrillBlocks N
Y DOCUMENT_WIDrillBar N Y
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 users profile on page 29.
Getting a users Web Intelligence preferences

To read the value of a users option: 1. 2. 3. Get the current users IUser object using an IInfoStore query. Get the "desktopsettings" profile string. Convert the profile string to a Map for easy manipulation and printing.
Example: Printing a users preferences The following JSP code functions show how to retrieve a users Web Intelligence preferences and print them to an HTML response stream.
<%! //Return a string containing a users Web Intelligence Preferences String 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();
2
prefs = user.getProfileString("desktopsettings"); } }catch(SDKException sEx){ return ; } return prefs;
} //Convert a String of preferences to a Map Map 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 users 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. 2. 3. 4. Get a users preferences. Update a standard option in the Map continuing the user preferences. Convert the Map to a String. Update the user profile with IInfoStore.commit.
Example: Setting a users report panel preference to Java The following JSP code functions enables a users profile to be updated to use the Java Report Panel.
<%! //Update the users 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 string String 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 users Web Intelligence preferences.
<% //Update a users 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 users preferences on page 26
Adding custom options to a users profile

To add custom options to a users profile: 1. 2. Get a users preferences. 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. 4. Convert the Map to a String. Update the user profile with IInfoStore.commit.
Example: Adding a new preference to a users profile The following JSP code fragment sets a custom preference.
<% //Add a custom Web Intelligence preference using functions defined in the previous examples int 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 users 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 SDK

Referencing 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 package To 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 REBean

To create a ReportEngine object for an application that uses Web Intelligence Report Engine SDK, retrieve the ReportEngine object from the users IEnterpriseSession. Example: Instantiating a ReportEngine object To 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 object

Just 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 users 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 types
With 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) files
Using 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 cycle

Web 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 documents current state.
Temporary files Executing file doc object
open doc
StorageToken = r0
r0
view1
As the document changes state through the execution of JSP files, the storage token changes too, and more temporary files, representing the documents states, are created. Web Intelligence generates a new storage token and corresponding set of temporary files at the following triggers: User interface Triggers refreshing the document drilling creating and editing a document applying new formats running a query SDK Triggers calling DocumentInstance.getView modifying the DrillPath object calling DataProvider.getResult calling DataProvider.runQuery opening a document
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 cycle The 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.
Temporary files 1
Executing files
docInstance object
open docInstance
StorageToken = r0
r0
GIF
run query
StorageToken = r0-s0
r0-s0
view1
r0-s0
2
GIF GIF
get doc(r0-s0) drill
r0-s1
view2
r0-s1
3
get doc(r0-s1)
GIF
drill
r0-s2
GIF
commit change
view3 r0-s3
3
Table 3-1 Storage token life cycle
Advantages of storage tokens

Lifetime
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 forward

After 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 folders

A 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 users possible rights.
3
Folder and category-related settings in a Web Intelligence users rights InfoView Advanced Right User can move and copy objects, create shortcuts and add object to the favorites folder. Can use InfoView simple search Can use InfoView advanced search User has a favorites folder User can create categories Variable Name CeInfoViewRightID.ORGANIZE User can change preferences CeInfoViewRightID.PREFERENCE
CeInfoViewRightID.SIMPLESEARCH CeInfoViewRightID.ADVANCEDSEARCH
Can use InfoView filter feature CeInfoViewRightID.FILTER CeInfoViewRightID.FAVORITES CeInfoViewRightID.CREATECATEGORIES User can view inbox contents CeInfoViewRightID.VIEWINBOX User can assign categories to CeInfoViewRightID.ASSIGNCATEGORIES users or groups User can send documents to users and groups User can create dashboards User can create folders CeInfoViewRightID.SENDDOCUMENTS CeInfoViewRightID.CREATEDASHBOARDS CeInfoViewRightID.CREATEFOLDERS
A list of a users rights over an object in the InfoStore can be recovered by retrieving the users ISecurityInfo object for a certain BusinessObjects Enterprise application. Example: how to check that a user has the right to create categories This 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){
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 users Web Intelligence rights the query string would include CeKind.WEBINTELLIGENCE in the place of CeKind.INFOVIEW.
Navigating categories and folders

Categories 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 tree The following example shows JSP functions that use BusinessObjects Enterprise SDK to recover the ID of the parent folder for a users personal categories. Using this ID a bulleted list containing the hierarchical structure of the users personal categories is generated.
<%! //Return the ID of a specific folder public 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
} //Return a selectable list of categories or folders String 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; } %> }catch (SDKException sdke){ return FolderID;} return FolderID;
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 users 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 users Inbox and Favorites folder IDs The following example shows JSP functions that use BusinessObjects Enterprise SDK to recover the ID of the parent folder for a users Inbox and Favorites folders.
<%! //Retrieve the ID for any type of personal folder public 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 users Inbox int getInboxFolderId(IInfoStore iStore, int userID){ return getFolderId(iStore,userID,(String)CeKind.INBOX); } //Retrieve the ID of a users favorites folder int 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 users 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 category The 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 category addFolderOrCategory(iStore, categoryParentID, "Category Name", "Keywords",CeKind.PERSONALCAT); //Create a new personal folder addFolderOrCategory(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 myIInfoObject.setTitle
You can rename categories and folders using: 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 folders The 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 category

Each 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 category The 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 Property myWriter.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 documents
After establishing a session for a user (see Establishing a valid BusinessObjects Enterprise users session on page 20) you can open a document on behalf of the user. In general, to open a document you: 1. 2. Establish a BusinessObjects Enterprise session for the user. 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 documents ID. 3. Open the document using the ReportEngine.openDocument method for Web Intelligence documents.
Taking into account user rights and profiles

Because your Web Intelligence application acts on behalf of a user, what your application can do with the document is subject to the users 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 users 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 lists

To display a list of documents you: 1. 2. 3. Use the IInfoStore.query method to return the list of IInfoObjects representing the root directory of the users folders and documents. Loop through the IInfoObject list and print the values of the fields of each row. 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 list

A 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 list The 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 folder IInfoObjects 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 document The 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 documents
Scheduling 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. 2. 3. 4. Query the IInfoStore to get the IInfoObject representing the specific document. Get the document IInfoObjects ISchedulingInfo object. Set the type and frequency of the scheduling. 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 document The 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 users permissions. Action To these groups and/or Depending on the current users users settings for these permissions groups and categories to DocumentInstance.saveAs which the current user has access groups to which the IInfoStore.schedule current user belongs, and/or the other users in those groups
Save to Groups and Categories Send to Inbox, FTP, email, groups.
Example: Retrieve the list of groups to which a user belongs The 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 objects 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.
3
Procedure for sending a document to folders and categories
BusinessObjects 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. 2. Display the name of the document to be sent. Retrieve the IDs of:

3. 4. 1. 2.
corporate folders and categories the root directory of the current user's personal categories
Get and display the list of folders and categories to which the current user can send documents. Pass this information to the second JSP page. Get the details entered by the user. Call DocumentInstance.saveAs.
Then, in the second JSP page:
Example: Sending a document to folders and categories The 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 users 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 folder public 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 object String 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 parameters if (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 IDs 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 groups

If 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 inboxes

To schedule a document, you need to gather the appropriate information from the current user before sending. To do this you need to:
3
1. 2. 3. 4. 5. 6. 7. 8. 9. Query the IInfoStore to get the IInfoObject representing the document to be sent. Get the documents ISchedulingInfo object. Retrieve the Inbox plugin used to send a document to users. Set the destination and send options for the Inbox plugin. Create a Set containing the IDs of users or groups to which the current user can send the document. Allow the user to choose the users/groups to send the document to. Add the set of IDs created in the previous step to the Inbox plugin options. Set the type and frequency of the scheduling. 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 IDs 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 plugin IDestinationPlugin 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 to Set 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. 2. 3. Get the collection of properties. Set/Read the property. Commit the change, if any, to the collection of properties.
Working with properties

Using Web Intelligence Report Engine SDK, you can access a documents 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 REBean The 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 document

Use 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 persistence
You do not need to save the document for the properties you set to persist after the document is closed.
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 reports
You 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. Type Document Report Report Page XLS X X X PDF X X X X X X X XML HTML
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 document

To view all the reports in a document: 1. 2. Open the document. 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.
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.msexcel. Example: Viewing all the reports in a Web Intelligence document The 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 document DocumentInstance doc = repEng.openDocument(docID); //get the report contents as a binary stream in PDF format BinaryView docBinaryView = (BinaryView) doc.getView(OutputFormatType.PDF); byte[] abyBinaryContent = docBinaryView.getContent(); //output the binary stream via the response object response.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 users browser configuration, the document will appear in either in the browser or in a separate application window.
Viewing an individual report in HTML

The standard viewing format is HTML. To view an individual report in HTML format: 1. 2. 3. 4. Get a document instance. Set the report. Get a view of the report in HTML format. 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 viewed int iRepID = 0; //index of the selected report // Get the document doc = reportEngine.openDocument(sToken); // Set the report if ((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 format HTMLView 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 format

You 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. 2. Get a binary view of the report. 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 format The 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 format BinaryView 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 customers 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 prompt

One 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 prompt The 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 only Prompts prompts = doc.getPrompts(); //try to enter values and set prompts String[] values = request.getParameterValues("PromptInput"); if ((values != null)&&(!(values[0].equals("")))){ prompts.getItem(0).enterValues(values); doc.setPrompts(); //also sets getMustFillPrompts to false } //get user input if (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. 2. 3. Get the DocumentInstance object for the document. Get the collection of prompts for the document. 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 forms 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 documents reports
Using the storage token to retrieve a DocumentInstance

When 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 names The 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 prompts The 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 prompts DocumentInstance doc = reportEngine.openDocument(token); if (doRefresh) doc.refresh(); //refresh first time only Prompts prompts = doc.getPrompts(); //try to get and enter values from the query string // valuesSelected is true when the user completes the form if (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
} } doc.setPrompts(); //also sets getMustFillPrompts to false if ((values != null)&&(values.length != 0)) prompts.getItem(j).enterValues(values);
//get user input if (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 dynamically for (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.
list of values for the Quarter object in the eFashion universe
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 values The following JSP code fragment illustrates how to get the values of a LOV and display them in a form.
//get user input if (doc.getMustFillPrompts()) { //build a form to get user input for the prompt %><form name="PromptsForm" action="refresh.jsp"
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++){ %> <option value="<%=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 prompts
A prompt is constrained if the answer must come from the prompts 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 prompts
Until 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 prompts The 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 statement else {%> <select name=<%="PV"+i%> multiple size=5><% } //add values in LOV to the select list for (int k = 0; k < lovValues.getCount(); k++) { %> <option value="<%=lovValues.getValue(k)%>"> <%=lovValues.getValue(k)%> </option><% }%> </select> </td>
Prompts with multicolumn lists of values

A 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 values The 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 tag for (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 prompts

Sometimes 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 prompts Consider 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 prompts The 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 prompts DocumentInstance doc = re.getDocumentFromStorageToken(token); if (doRefresh) doc.refresh(); //refresh first time only Prompts prompts = doc.getPrompts(); //if there are prompts, fill them if (docInstance.getMustFillPrompts()) {
4
} 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 prompts for (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(); } this.fillPrompts (prompts, null); docInstance.setPrompts();
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 values

If 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 prompts

If 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 prompts The 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 prompts

Universe 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 Designers 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. 2. 3. 4. 5. Get contexts. Display the possible values for each context and get the users response. Enter the values for the context provided by the user. Set the contexts. 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 document The following JSP code fragment traverses the following report structure and gets a section as HTML.
Section1 Report1 map.getStructure() Report2 Report3 Section2 Section1 Section2 Section2
Section1
ReportMapNodes = ReportMapNode
// Get the ReportMap from the document instance ReportMap map = doc.getReportMap(); //point to the root node of the structure ReportMapNodes root = map.getStructure(); // Get the number of reports in the document // There are three in this case: Report1, Report2, and Report3 int count = root.getChildCount(); // Get the first report ReportMapNode 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
4
// There are two in this case: Section1, Section2 int section_count = report1.getChildCount(); // Get the first section ReportMapNode 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 section Report 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 drilling
Drilling 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 process

To 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 documents 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 documents drilling classes to generate the drilled view. 4. 5. The script displays the drilled view generated by Web Intelligence. Repeat steps 2 to 4 for each request for a drill operation.
1
s ue req ll t
Drill Option
dri
2 Define drill 3 Generate HTML Drill Path View report view.jsp 4
dri ll
req
ue st
Table 5-1 The process you need to implement to provide a drilling function
Defining the drill operation

You 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
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 report

This 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 analysis

An 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 Cube

The 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 users access to this facility using Supervisor.
Drill hierarchies
Hierarchies 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 information
You can access drilling information by examining the contents of the universe (the drill hierarchies and dimensions), or by examining the drill bar.
Drill hierarchies defined in a universe

Use Report.getNamedInterface(DrillInfo) to get the DrillInfo class. To get the hierarchies used in the report, use DrillInfo.getDrillHierarchies. A hierarchy is used if one of its dimensions is included in the query for the report. To get the dimensions and details that are not included in a hierarchy but are used in the report, use DrillInfo.getFreeDimensions. The DrillBlock object gets the drill hierarchies and dimensions for just one block (table or graph) in the report.
Drill bar
DrillBar exposes drill and report filters, and specific drill objects added by the user. A drill object can be a dimension, or a detail.
Defining the drill operation

A drill operation is defined in terms of the drill path. The drill path is represented in REBean by the DrillPath interface, and consists of a set of parameters such as the IDs of the objects (dimensions) from and to which the user is drilling. Defining the drill operation, therefore, involves setting the parameters of the drill path object. To define the drill operation: 1. 2. 3. 4. Enter drill mode. Define the query string parameters, if required. Get the parameters of the drill request. Set the drill path.
Entering and leaving drill mode

You need to put Web Intelligence into a special mode so that it can perform the drilling functions. There are two modes: ReportMode.Viewing and ReportMode.Analysis.
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 parameters

In Web Intelligence users drill with hyperlinks and a popup menu, which are generated by Web Intelligence using Javascript functions and style sheets (see Generating the HTML and viewing a drilled report 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 users drill request and, hence, to set the drill path. Note: You cannot change the name and path of the image used to indicate the drill up hyperlinks. This is always ApplicationName/images/cdz/drillup.gif Example: Defining the query string parameters The following JSP code fragment shows how to define the query string parameters used to pass drill information to the Javascript functions that generate the hyperlinks and popup menu, which provide the user with drilling functions.
//set up the query string parameters used for drilling DrillOption option = info.getDrillOption(); option.setBlockHolder("Block"); option.setBlockSynchronized(true); option.setCallBackScript("drillHandler.jsp?ReportIdx=0); option.setCallBackFrame("_self"); option.setDrillActionHolder("Action"); option.setToHolder("To"); option.setFromHolder("From"); option.setFilterHolder("Filter"); option.setHierarchyHolder("Hierarchy"); option.setStorageTokenHolder("Token");
Note: Notice that you can add your own query string parameters to the call back script definition. Depending on the architecture of your application, and how you manage storage tokens (document state) you might need to include the storage token in the call back script definition. If you do this, remember that drilling methods such as beginDrill and executeDrill generate new tokens for the document.
Getting the parameters of the drill request

To get the parameters of the drill request use request.getParameter and request.getParameterValues. For example:
String token = request.getParameter("Token"); String block = request.getParameter("Block"); String action = request.getParameter("Action"); String[] to = request.getParameterValues("To");
5
String[] from = request.getParameterValues("From"); String[] hierarchy = request.getParameterValues("Hierarchy"); String[] filter = request.getParameterValues("Filter");
Setting the drill path

The drill path defines the drill operation. To set the drill path: 1. 2. 3. 4. 5. Get the drill path. Set the drill action. See Setting the action: up, down, by, or slice on page 85 below. Set the block id. Set the object id of the drill to element. Set the object id and filter of the drill from element.
Setting the action: up, down, by, or slice A users drill actions are classified by how they move through the drill hierarchies. Drill action Resulting report engine action Up Down By Slice The report engine replaces the current object with its parent in the drill hierarchy. The report engine replaces the current object with its child in the drill hierarchy. The report engine replaces the current object with an object that is not adjacent to it in the drill hierarchy. The report engine adds or removes the filtered values.
hierarchy 1 dimension 1 down down or by dimension 2 dimension 3 hierarchy 2 dimension 5 up dimension 6 by dimension 7 slice
dimension 4
Table 5-2 Different drill actions
You set the drill action with DrillPath.setAction. The actions are enumerated by DrillActionType.
5
Setting the from and to parameters To set the from and to parameters of the drill, you define the elements of the drill. The elements of the drill are the dimensions involved in the drill action and are represented by the DrillElements interface. There is a DrillElements object for the to and for the from dimensions. Individual from and to elements are represented by DrillFromElement and DrillToElement. For each drill operation: 1. 2. 3. 4. Get the drill from and to elements with DrillPath.getTo and DrillPath.getFrom. Add drill elements to each collection. Set the object IDs of each drill element using the values you retrieve from the query string. For each from element, set the filter, if any.
Note: The filter remains for drill-by actions between dimensions in the same hierarchy. However for drill-up actions the filter is removed. Note: For example, in the Time Period hierarchy, if you drill down to Quarters from Year = 2003, all the quarters for 2003 are displayed, then if you drill by Year, only Year= 2003 is displayed. However if you drill up from Quarters to Year, all the values for Years are displayed. Example: Setting the drill path The following code fragment shows how to set the values of the drill path. The parameters of the drill (action, from, to, block) are retrieved as described in Getting the parameters of the drill request on page 84.
DrillPath drill = info.getDrillPath(); //set the ACTION if (action.equals("down")) drill.setAction(DrillActionType.DOWN); else if (action.equals("up")) drill.setAction(DrillActionType.UP); else if (action.equals("slice")) drill.setAction(DrillActionType.SLICE); else if (action.equals("by")) drill.setAction(DrillActionType.BY); //set the BLOCK drill.setBlockID(block); //set the TO drill elements if (to.length > 0) { DrillElements toElements = drill.getTo(); for (int j = 0;j < to.length; j++) { DrillToElement toElement = (DrillToElement) toElements.add(); toElement.setObjectID(to[j]); } }
5
//set the FROM drill elements if (from.length > 0) { DrillElements fromElements = drill.getFrom(); for (int k = 0; k < from.length; k++) { DrillFromElement fromElement = (DrillFromElement) fromElements.add(); fromElement.setObjectID(from[k]); if ((filter != null) && (filter.length > 0)) fromElement.setFilter(filter[0]); } }
This example assumes that there is only one value in the array filter fromElement.setFilter(filter[0]). This is true for simple drilling, however, to handle more sophisticated drilling you need to use all the values in the array of filters. Also, in the part that sets the filter, you can add the condition if !action.equals(up) since there is no filtering in a drill-up operation, however, if you set a filter for a drill-up operation, it is ignored.
Generating the HTML and viewing a drilled report

To generate the HTML for the report execute the drill with DrillInfo.executeDrill, then view the generated HTML using HTMLView.getString (see Displaying the drilled report 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 drilling

The Java script files used to create the drilling user interface are stored in /businessobjects/enterprise11/desktoplaunch/viewers/cdz/. Copy the following files from this directory to the same directory as your script that displays the HTML view of the report.
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:
/businessobjects/enterprise11/desktoplaunch/viewers/cdz/style/ skin_name/bomenu.css skin_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 drilling

The HTML generated by Report.getView references these files and you need to include this in your header with HTMLView.getString("head", false). For an example of how to do this, see Displaying the drilled report on page 88.
Displaying the drilled report

To display the drilled report, call HTMLView.getStringPart("body", false). Alternatively you can call HTMLView.getString() which retrieves both the appropriate HTML header and the drilled report, however, it means you can't add supplementary HTML to the page. Example: Displaying the drilled report The following JSP code fragment illustrates how to display a report after executing the drill.
<% HTMLView objHTMLView = null; htmlView = (HTMLView) rep.getView(OutputFormatType.HTML); String htmlHeader = htmlView.getStringPart("head", false); %> <html>  <head> <link rel="stylesheet" type="text/css" href="style/bomenu.css"> <%=htmlHeader%> </head>  <%=htmlView.getStringPart("body", true)%> </html>
Manually handling out of scope drill requests

Once you have set the DrillTo and DrillFrom elements you can detect if a drill dimension is not in scope with DrillDimension.isInScope, and if the defined drill operation contains out of scope dimensions with DrillInfo.willGoOutOfScope.
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 prompts

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

The DrillBar object exposes the drill filters and specific objects added by the user. By default, the drill bar is initialized with the report filter, but it can be customized by the user to add or remove drill objects. Drill objects can be dimensions, or details. In the example below, the DrillBar object contains three objects, the Country dimension filtered on the US value, the Resort dimension filtered on the Bahamas Beach value, and the unfiltered Service Line object.
You access the drill bar with DrillInfo.getDrillBar, and you add and remove objects to and from the drill bar with DrillBar.add and Drillbar.remove. Note: When you remove an object from the drill bar, it is automatically removed from the report filter.
Adding query conditions using the drill bar

You can use the filters in the drill bar to add query conditions when extending the scope of analysis. For example, if the drill bar has the filter Country = US, when the scope is extended you can use this object to form a query condition
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 drill

You can use DrillInfo.snapshot to put aside a drilled view and continue drilling. This method adds a report containing the current view to the documents 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 providers
A data provider has two parts: a query and a data source.
The query
The 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 source

The 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 application
The 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 Panel
Note: This applet is different from previous releases of Web Intelligence.
Launching the Web Intelligence Java Report Panel

You 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 applets parameters. All parameters are of the type java.lang.String.
6
Parameters Applet parameters code useslibrary useslibrarycodebase com.businessobjects.w The path to the p.tc.TCMain applet. Web Intelligence Report Panel /webiApplet/ ThinCadenza.jar en; jp The name of the applet. The path to the archive containing the applet The path to the online help. The language of the user interface. The name of the server from which the applet is downloaded. The path to the servlet through which the server and the browser communicate. The port used for the application server The session identifier for the open document. The storage token for the document. Value(s) Description
HelpRoot Lang Server parameters Server
Isapi
/servlet/ com.businessobjects.cd zlet. CadenzaServlet default is 8080 use the string returned by ReportEngine. getServerInstance use the string returned by DocumentInstance. getStorageToken when editing an open document corporate; inbox; personal.
Port CdzSession
Document parameters Token
RepoType
The type of the repository in which the document is stored. The id of the document.
DocumentID
6
Parameters DocumentName Value(s) Description The name of the document. If present, the applet automatically opens the first class of the universe. The id of the universe on which the query will be run.
OpenFirstClassOfUniverse -
Data source parameters UniverseID -
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 Panel The 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");
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. 2. 3. 4. 5. 6. Get the collection of data providers for the document. Get the universe elements in which you are interested. Get the query for the data provider. Add result objects. Add condition objects (optional). Execute the query.
Example: Building a data provider The following JSP code fragment illustrates how to populate the query object of a data provider.
//select a universe ==> sID ... //create a new document instance DocumentInstance doc = reportEngine.newDocument(sID); DataProviders dps = doc.getDataProviders(); // Retrieve the 1st data provider DataProvider dp = dps.getItem(0); // Retrieve the universe objects DataSource 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 query q.addResultObject (city); q.addResultObject (year); q.addResultObject (sales); // Run the query: execute the query and fetch the data dp.runQuery();
Editing queries
A query is represented by the Query object and has the following parts:
a list of result objects
6

Result objects
A 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. 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.
Scope of analysis
The 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 Users Guide.
Simple conditions
The 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.
FilterConditionContainer ConditionObject FilterCondition
getDataSourceObject = Revenue getOperator = NOT_IS_NULL
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 condition The following JSP code fragment creates the condition (Revenue < 10000).
Query q; //query to which the condition is applied //create a container for the condition ConditionContainer c1 = q.createCondtion(); //create an object for the condition ConditionObject co = c1.createConditionObject(revenue); //create a FilterCondition object to contain information //about the operator and the operand FilterCondition fc = co.createFilterCondition(Operator.LESS); fc.createFilterConditionConstant("10000");
Complex conditions
By combining containers with operators and adding extra condition objects you can build very complex conditions.
6
Example: Structure of a complex condition The following is a representation in REBean of the condition: (Revenue < 1000000) OR ((Year = 2002) AND (Holiday)).
FilterConditionContainer(OR) ConditionObject FilterCondition
getDataSourceObject = Revenue getOperator = LESS getOperand = 1000000

FilterConditionContainer(AND) ConditionObject FilterCondition
getDataSourceObject = Year getOperator = EQUAL getOperand = 2002
ConditionObject
getDataSourceObject = 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 condition

To 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 condition The following JSP code fragment creates the condition prompt Year?
//get the query (q) to which the condition is applied //... //create a container for the condition ConditionContainer cc = q.createCondition(); //create an object for the condition ConditionObject co = cc.createConditionObject(country); //create a FilterCondition object to contain the prompt FilterCondition fc = co.createFilterCondition(Operator.EQUAL); //define the prompt
6
ConditionPrompt cp = fc.createConditionPrompt("Country?"); cp.setConstrained(false); cp.setMonoValue(true); cp.addDefault("Australia");
Executing queries and retrieving the data

When 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. To execute the query and not retrieve the data The user does not need to set any prompts or contexts. retrieve the data If there are prompts or contexts, the user must set these using the same procedure as for viewing a document. 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. DataProvider.runQuery Use DataProvider.executeQuery
Getting the SQL for the query

Web 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.
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 structure

You 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 sections blocks report cells free cells
A document can also contain:
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 document This 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 directory rootDirs = iStore.query(rootQuery); if (rootDirs.size() > 0){ //Get the Universes IInfoObject 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 list IInfoStore iStore = (IInfoStore)session.getAttribute("InfoStore"); ReportEngine webiRepEngine = (ReportEngine)session.getAttribute("ReportEngine"); IInfoObjects universes = getUniverses(iStore, iID); //Get the first universe IInfoObject universe = (IInfoObject)universes.get(0); //then create the blank document DocumentInstance doc = webiRepEngine.newDocument(universe.getID());
7
Representing document structure through containment
Document elements are structured according to their containment relationship. This element report report body page header/footer section Can contain these elements page header/footer, report body sections, blocks, and cells cells sections, blocks, and cells
The containment relationship between the elements of a document is represented in the object model as a tree using TreeNode, ReportElementContainer, and ReportElement.
report page header free cell report page header free cell
report body free cell section block block free cell report cell
report body
section section block
page footer
free cell
page footer
free cell
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.
7
Example: Creating a document structure The 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 report DocumentInstance 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 section SectionContainer sectionYear = body.createSection(); sectionYear.getAxis().addExpr(yearExpr); //[Year] // create a block ReportBlock block1 = sectionYear.createBlock (); BlockAxis hAxis = block1.getAxis(TableAxis.HORIZONTAL); hAxis.addExpr(quarterExpr); //[Quarter] // create another block ReportBlock 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 above
Note: 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.
x
body report free cell
You can express x and y in millimeters or inches.
Using attachments to avoid overlapping elements

Since 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.
xb1 yb1 block 1 cell 1 attachmentb1-b2 block 2 xc1
attachmentb1-c1
yb2
Table 7-3 Positioning elements relative to the parent container and siblings.
7
Example: Creating an attachment The 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 container ReportBlock b1 = report.getReportBody().createBlock(); // Set the blocks position relative to its container b1.setX(150d); // Xb1 b1.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-c1 c1.setAttachTo(b1, VAnchorType.NONE, HAnchorType.RIGHT); // Position cell 1 relative to block 1 c1.setX(200d); // Xc1 // Attach block 2 to block 1 (BOTTOM attachment): b1-b2 b2.setAttachTo(b1, VAnchorType.BOTTOM, HAnchorType.NONE); // Position block 2 relative to block 1 b2.setY(200d); // Yb2
Creating and editing sections

A 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 sections axis, they are added to the right of the last one added. Example: Editing the sections of a report The 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 blocks

Block is a generic name for tables, cross tables, forms, and graphs.
Block structure: axes and report expressions

A 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. Block type vertical table horizontal table cross table graph Axes one horizontal axis one vertical axis horizontal, vertical, and content axes x, y, and z axes
For a vertical table the report expressions are displayed in columns.
Table 7-4 Structure of a vertical table
Note: 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.
Table 7-5 Structure of a horizontal table
For a cross table the report expressions are displayed in columns and rows with a shared body.
Table 7-6 Structure of a cross table
In a graph the report expressions are displayed as a picture with two or three dimensions.
Table 7-7 Structure of a graph
Example: Building a report: adding expressions to axes The 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.runQuery ReportDictionary dico = doc.getDictionary(); // Create a new report ReportContainer report = doc.createReport("My Report"); BodyReport body = report.getBodyReport(); // Create a section as the body report child SectionContainer section = body.createSection (); ReportExpression ctryExpr = dico.getChildByname("ParentCountryID"); // Add the country object on the section axis section.getAxis().addExpr(ctryExpr); // Create a block in the section container ReportBlock 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 expressions

You 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.
Breaks
You can add breaks to report expressions. You can add breaks to report expressions belonging to an axis, and you can show or hide the breaks 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.
Calculations
You 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 block
A 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 tables

The 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 tables
Cross tables use the CrossTable specialization of Table, and the cells in a cross table are grouped into zones. Top - Left Body - Left Bottom - Left Top - Body Body - Body Bottom - Body Top - Right Body - Right Bottom - Right
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.
Forms
Forms 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.
Graphs
Graphs 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.
7
Graph category Bar Graph type Vertical Grouped Horizontal Grouped Vertical Line and Bar Horizontal Line and Bar Vertical Stacked Horizontal Stacked Vertical Percent Horizontal Percent 3D Vertical Mixed Horizontal Mixed Vertical Stacked Horizontal Stacked Vertical Percent Horizontal Percent 3D 3D Surface Vertical Absolute Horizontal Absolute Vertical Stacked Horizontal Stacked Vertical Percent Horizontal Percent 3D Area 3D Surface Pie Doughnut 3D Pie 3D Doughnut Stacked Area Radar Polar Scatter Radar Line
Line
Area
Pie
Radar & Scatter
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 decoration

Page 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.
Alignment
Using 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.
Attributes
The Attributes interface represents the non-font aspects of the cells 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).
Font
The 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 size
You 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.
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 recordset
In Web Intelligence SDK recordsets provide a generic way of representing the data about, or contained in, a group of objects.
a field current record d g j m p s b e h k n q t c f i l o r u 10.0 20.0 30.0 40.0 50.0 60.0 70.0 recordset fields
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 REBean
In REBean the Recordset class represents recordsets.
Field names
Recordset.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.
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 field

In 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 recordset The 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 flow rs.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 names StringBuffer sbn = new StringBuffer(); for (int j = 0; j < rs.getColumnCount(); j++) { sbn.append( rs.getColumnName(j).toString() ); sbn.append(";"); } System.out.println(sbn.toString()); // data for (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 services
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.
Documentation
You can find answers to your questions on how to install, configure, deploy, and use Business Objects products from the documentation.
Whats 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 products

Online 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 web

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

Look 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
Customer support, consulting and training
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: documentation@businessobjects.com. Note: 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.

A 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 Support

The 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
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
Useful addresses at a glance

Address Business Objects product information http://www.businessobjects.com Product documentation http://www.businessobjects.com/ support Business Objects Documentation mailbox documentation@businessobjects.com Online Customer Support http://www.businessobjects.com/ support/ Business Objects Consulting Services http://www.businessobjects.com/ services/consulting/ Business Objects Education Services http://www.businessobjects.com/ services/training Content Information about the full range of Business Objects products. Business Objects product documentation, including the Business Objects Documentation Roadmap. Send us feedback or questions about documentation. Information on Customer Support programs, as well as links to technical articles, downloads, and online forums. Information on how Business Objects can help maximize your business intelligence investment. Information on Business Objects training options and modules.
Migrating Business Objects 6 Customized Applications to BusinessObjects XI127
Index
A
accessing user profiles 25 actions drilling 85 Adobe Acrobat 34 see also PDF alignment 116 anchors vertical and horizontal 108 applets Web Intelligence Java Report Panel 94 area graph 114 attachments 108 authentication passwords 19 axis (block) 110 training services 126, 127
C
calculations 113 categories 3947 category details 46 category moving 46 creating 45 deleting 45 getting details 46 renaming 45 user rights, and 39 categorizing documents 39 cells creating 116 CESDK creating a ISessionMgr object 18 referencing 17 CESDK object creating 20 chunking lists of values 74 classes referencing 17 closing ReportEngine object 32 Web Intelligence sessions 20 colors 116 conditions 100 prompts 101 structure 101 consultants, Business Objects 126 contexts opening documents 48 cookies sending with JSP 20 creating blocks 110
B
background 116 bar graph 114 batched lists of values 74 blocks cells 116 creating 110 cross tables 114 forms 114 graphs 114 repeating 117 representing 113 borders 116 breaks 113 browsers storage tokens 38 building data providers 91 Business Objects consulting services 126, 127 support services 125
categories 45 cells 116
document structure 104 ISessionMgr object 18 ReportEngine object 31 sections 109 cross tables 114 custom 58 customer support 125
D
data providers 91102 building 94 data sources 92 executing queries 102 data sources 92 decoration pages 116 deleting categories 45 Developer Suite migration 11 dimensions drilling 82, 85 scope of analysis, and 88 displaying document lists 48 report maps 77 document structure 104 attachments 108 blocks 110 positioning elements 108 report expressions 109 sections 109 documentation feedback on 125 on product CD 124 on the web 124 roadmap 124 documents 50
see also reports categories 39 changing names 50 creating 104 dictionaries 93 displaying document lists 48 drillable 81 drilling 79 opening 13, 48 prompts 66 properties 58 refreshing 14, 66, 75 document lists 49 report maps 77 saving 50 sending 52 structure 104 types 34 Web Intelligence format 31, 83 drill bars 83, 89 drill hierarchies 82 drill mode 81, 82 entering and leaving 83 drill options 84 drill path 81, 81, 83 setting 81, 83, 85 drilling 7990 actions 85 dimensions 82 drill bars 83 drill hierarchies 83 drill mode 81, 87 drill path 81, 83, 85 filtering 89 generating HTML 82, 87 hierarchies 82, 85 hyperlinks 81, 83, 84 images 87
Java script files 87 overview 80
query string parameters 81, 81, 81, 83, 84 scope of analysis 82, 88, 99 setting parameters 86 slice 85 snapshots 90 transparent drill out of cube 82 Web Intelligence reports 8390
page decoration 116 paper size 117 reports 103 forms 114 free cells 116
E
editing blocks 110 cells 116 data providers 91 document structure 104 queries 98 sections 109 education. See training Enterprise Mode authentication 19 errors 30 exceptions 30 executing queries 102
G
getHTMLView 36 drilling 82, 87 getting started 11, 16 graphs 114
H
handling context prompts 76 exceptions 30 out of scope drill requests 88 prompts 66 hello world example 16 hierarchies drilling 83, 85 hyperlinks generating for drilling 81, 82, 83, 84, 87
F
feedback, on documentation 125 fields recordsets 120 filtering drill bars 83, 89 drill-by and drill-up actions 86 queries 100 query conditions 89 fonts 116 foreground 116 formats saving 50 formatting layout 117
I
images drilling 87 importing code in JSP 24 include directive in JSP 24 information resources 124 InfoView example workflows 13 user profiles 25 Introduction 9
J
Java Report Panel see Web Intelligence Java Report Panel Java script files drilling 87 java.util.Properties 26, 58 JSP importing code 24 reading a user profile 26 sending cookies 20 reports 77 nested prompts 74 NT Challenge Mode authentication 20
O
objects query results 99 Online Customer Support 125 opening documents 13, 48 out of scope drills 82, 88, 99
L
landscape layout 117 layout 117 line graph 114 listing documents 48 lists of values 7076 batched 74 chunking 74 constrained prompts, and 71 displaying 70 multicolumn 72 prompts in (nested) 74 refreshing 75 log in and log out 16 logins 18 LOV see lists of values
P
packages java.util.Properties 58 page layout 117 page decoration 116 paper size 117 passwords 18 storage token 36 PDF displaying Web Intelligence reports 62 output format 64 .pdf see PDF pie chart 115 portrait layout 117 prompts 6676 conditions 101 constrained 71 context 66, 76 drilling 89 entering values 72 lists of values 70 multicolumn lists of values 72 multivalued 71 nested 74 storage tokens 36
M
managing documents 34 Microsoft Excel displaying Web Intelligence reports 62 output format 64 migration 11, 50 multivalued prompts 71
N
navigating
properties 58 documents 58
Q
queries 92 editing 98 executing 102 query conditions 89, 100 query strings drilling 81, 81, 81, 83, 83, 84
R
radar & scatter graph 115 REBean building data providers 91 creating a ReportEngine object 31 document properties 58 exceptions 30 features 10 formatting reports 103 prompts 66 RECOM creating a ReportEngine object 31 prompts 66 RECOM.dll 31 recordsets 119122 changing records 121 fields 120 referencing CESDK 17 Web Intelligence SDK classes 17 refreshing document lists 49 documents 14, 66, 75 lists of values 75 renaming categories 45 RENET exceptions 30 features 10 report expressions 109, 110 adding to axes 112
breaks 113 calculations 113 sorting 113 report maps 77 snapshots, and 90 Report Panel see Web Intelligence Java Report Panel ReportEngine object 31 closing 32 reports drilling 79, 82, 87 filters 89 formatting 103117 report maps 77 viewing all the reports in a document 62 repository opening documents 48 sending documents 52 resolving universe contexts 76 resources 124 result objects 99 running queries 102
S
save to corporate see publishing saving documents 50 scope of analysis 80, 82, 99 handling manually 88 scripts drilling 87 sections creating 109 sending documents 5254 session ID cookies, and 20 sessions closing 20 creating 20, 48
setting drill actions 85
drill parameters 86 user profiles 28 settings in user profiles 25 slice drill action 85 snapshots 90 SQL executing 102 storage tokens advantages 38 browser navigation 38 generation triggers 35 life cycle 35 opening documents 48 viewing reports 62 support customer 125 locations 125 technical 125 web site 125
user names 18 user profiles 25, 48 accessing 25 adding to 29 setting 28 user rights 48 categories, for 39 transparent drill out of cube 82 user sessions see Web Intelligence sessions
V
values prompts 70 viewing binary view 62 Web Intelligence reports 6178
W
web customer support 125 getting documentation via 124 useful addresses 127 Web Intelligence documents building data providers 91 formatting reports 103 saving 50 sending 52 Web Intelligence Java Report Panel 94 launching 94 Web Intelligence SDK creating a ISessionMgr object 18 exceptions 30 features 34 hello world 16 login 18 migration 11 packages 10 referencing classes 17
T
tables cross tables 114 vertical and horizontal 113 technical support 125 temporary files storage tokens 35 training, on Business Objects products 126 transparent drill out of cube 82 traversing categories 41 report maps 77 triggers generating storage tokens 35
U
universes 92 resolving contexts 76
Index
Web Intelligence sessions closing 20 creating 48 storage tokens 38 web sites support 125 training 126
Index

Customizing Web Intelligence en

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Customizing Web Intelligence en

Enviado por

Direitos autorais:

Formatos disponíveis

Customizing Web Intelligence with REBean

BusinessObjects Enterprise XI Windows and UNIX

Introduction to drilling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Drilling in Web Intelligence reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Customizing Web Intelligence 3

Building and Editing Data Providers

Anatomy of a recordset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Appendix B Business Objects Information Resources 123

Customizing Web Intelligence 4

Customizing Web Intelligence 5

6 Customizing Web Intelligence

Customizing Web Intelligence

Introduction About this guide

About this guide

Who should read this guide

Business Objects information resources

8 Customizing Web Intelligence

Customizing Web Intelligence

Introduction to WebIntelligence SDK

Packages for customizing WebIntelligence

10 Customizing Web Intelligence

A typical Web Intelligence SDK application

Customizing Web Intelligence 11

Creating documents: building and editing data providers

12 Customizing Web Intelligence

Open document workflow

Customizing Web Intelligence 13

<open document workflow> update document toolbar

fill document toolbar fill report map fill rendering area

14 Customizing Web Intelligence

Customizing Web Intelligence

get name and password from user

Name = janderson Pass = *******

display Hello World and a logout link

Table 2-1 Application for logging in and out of BusinessObjects Enterprise

16 Customizing Web Intelligence

Referencing BusinessObjects Enterprise SDK

Referencing BusinessObjects Enterprise SDK

Customizing Web Intelligence 17

Creating a ISessionMgr object

BusinessObjects Enterprise sessions

Establish a valid BusinessObjects Enterprise session for the user.

Getting login information

18 Customizing Web Intelligence

Customizing Web Intelligence 19

Establishing a valid BusinessObjects Enterprise users session

Retrieving a BusinessObjects Enterprise session

Closing a BusinessObjects Enterprise session

20 Customizing Web Intelligence

BusinessObjects Enterprise session time-out

Customizing Web Intelligence 21

22 Customizing Web Intelligence

IEnterpriseSession enterpriseSession; try { ISessionMgr mySessionMgr = CrystalEnterprise.getSessionMgr();

Customizing Web Intelligence 23

} catch( SDKException mySDKExept) { response.sendRedirect("index.jsp"); }

24 Customizing Web Intelligence

Accessing Web Intelligence user preferences

Customizing Web Intelligence 25

Getting a users Web Intelligence preferences

26 Customizing Web Intelligence

Customizing Web Intelligence 27

28 Customizing Web Intelligence

Adding custom options to a users profile

Customizing Web Intelligence 29