SAP XI 4.0 Web Intelligence ReportEngine Developer guide
Below you will find brief information for Web Intelligence ReportEngine XI 4.0. The Web Intelligence ReportEngine is a Java SDK that allows developers to create web applications that can access the back-end SAP BusinessObjects BI server. The SDK provides functionalities to view, refresh, fill prompts, fill contexts, drill (partially) and save Web Intelligence documents.
advertisement
SAP BusinessObjects Web Intelligence ReportEngine Java SDK developer guide
■ SAP BusinessObjects XI 4.0
2012-06-15
Copyright © 2012 SAP AG. All rights reserved.SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP
BusinessObjects Explorer, StreamWork, SAP HANA and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in
Germany and other countries.Business Objects and the Business Objects logo, BusinessObjects,
Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd. Business Objects is an SAP company.Sybase and
Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Sybase,
Inc. Sybase is an SAP company. Crossgate, m@gic EDDY, B2B 360°, B2B 360° Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.
2012-06-15
Contents
3
List of APIs not functional from the SAP BusinessObject XI 4.0 release onwards....................8
2012-06-15
4
Contents
2012-06-15
5
Document History
Document History
The following table provides an overview of the most important document changes
Version Date Description
Customizing SAP BusinessObjects
Interactive Analysis with ReportEngine SDK for XI 3.x
November 2010 First release of the document.
Customizing SAP BusinessObjects
Web Intelligence with ReportEngine
SDK 4.0
April 2012
The following chapters have been removed:
Organizing documents in categories and folders ,
Displaying documents lists
Refreshing a document list
Scheduling documents
Sending documents to users, groups and categories see
Business Intelligence platform Java SDK developer guide at the link reference below.
Related Topics
• http://help.sap.com
2012-06-15
Document History
6 2012-06-15
Preface
Preface
The ReportEngine Java developer guide helps you to customize web application using Java SDK.
2.1 What you can learn from this guide?
This guide describes the processes and procedures for creating web applications using SAP
BusinessObjects Business Intelligence platform SDK and the ReportEngine SDK.
2.2 Who should use this guide?
This guide is intended for developers who are interested in developing web applications using SAP
BusinessObjects Business Intelligence platform SDK and the ReportEngine SDK.
2.3 What should you know?
To use the SAP BusinessObjects Business Intelligence platform SDK and ReportEngine SDK, 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 SAP BusinessObjects product line. Familiarity with SAP BusinessObjects Business Intelligence is assumed.
2.4 Related documents
For more information on classes and interfaces of SAP BusinessObjects Business Intelligence platform
SDK and ReportEngine SDK, refer to the following guides:
• Business Intelligence platform Java API Reference
7 2012-06-15
Preface
• Business Intelligence platform Java SDK Developer Guide
• Web Intelligence ReportEngine API Reference guide
2.5 List of APIs not functional from the SAP BusinessObject XI 4.0 release onwards
In SAP BusinessObjects XI 4.0 release, the Report Engine SDK does not support the following features:
• A subset of drilling features in Web Intelligence documents
• Building queries
• Document and report editing
2.5.1 Classes and interfaces no longer functional
The following tables list the set of classes/interfaces that are no longer functional from the SAP
BusinessObjects XI 4.0 release onwards
Table 2-1: Classes and Interfaces from A to D
A B
AdvancedCondition
AggregationFunction
Alertable
Alerter
Alerters
AlertersDictionary
Alignment
AllAvailableFunctionsId entifiers
BarType
Block
BlockAxis
BlockBreak
BlockCalcula tion
BlockInfo
Blocks
BlockSort
C
Calculation
CalculationElement
Cell
CellContentType
CellMatrix
D
DataProvider (partially supported)
DataProviders (partially supported)
DataSource (partially supported)
DataSourceObject
DataSourceObjectProper tiesType
ChangeDataSourceMap ping
ChangeDataSourceMap pingDetail
ChangeDataSourceOb jectMapping
DataSourceObjects
DataSourceObjectUsage
Decoration (partially supported)
8 2012-06-15
Preface
9
A
AllAvailableOperatorsI dentifiers
AreaType
Attachable
Attributes
AxisType
B
BlockType
Border
BorderSize
BreakElement
C D
CombinedQueryOperator DefaultUnit
ComparisonOperator
CrossTable
CustomSortLov
CustomSortValues
DocumentInstance (partially supported)
DPExpression ComplexBorder
ConditionContainer
ConditionObject
ConditionObjectValue
ConditionOperator
DrillBar
DrillBarObject
DrillBlock
DrillDetail
ConditionOperatorFeature DrillDetails
ConditionPrompt
DrillDimension (partially supported)
CreateDefaultTablesPa rameters
DrillHierarchy (partially supported)
DrillInfo (partially supported)
DrillOption
Table 2-2: Classes and Interfaces from F to P
F
Filterable
FilterCondition
FilterConditionConstant
FilterConditionContainer
FilterConditionNode
FilterConditionObject
FilterConditionOperand
FilterConditionValue
G - H - I - L
Graph
GraphAxis
GraphAxisProperties
GraphAxisValues
GraphData
GraphGrid
GraphTitle
GraphType
M - P
Margins
ObjectQualification
ObjectType
OpenDocumentInfo
Operator
Orientation
OutputCacheEntry
PageHeaderFooter
2012-06-15
Preface
10
F
FilterContainer
FilterObject
Font (partially supported)
FontOrientation
Form
FormulaExpression
FormulaOperator
FreeCell
Function
FunctionCategory
Table 2-3: Classes and Interfaces from Q to V
Q - R
Query
QueryContainer
QueryException
QueryFeature
QueryNode
S
SamplingMode
Scope
ScopeLevel
SectionContainer
SimpleBorder
QuerySort
RadarType
RankCondition
RankConditionPrompt
SimpleTable
Skin
SkinReportElementType
SortElement
Report (partially supported)
ReportBlock
SortInfo
SortInfoType
ReportBody
ReportCell
SortType
SQLContainer
G - H - I - L
HAlignmentType
M - P
PageInfo
HAnchorType
HTMLView (partially supported)
PageLayout
PaperSize
HZoneType
ImageDisplayMode
Legend
LegendPosition
LineType
Link
LogicalOperator
PersonalDataProvider
PieType
Podium
Position
PromptOrder
T - U - V
Table
TableAxis
TableCell
TableFormBase
TableType
Unit
UnitType
VAlignmentType
VAnchorType
VariableExpression
VZoneType
2012-06-15
Preface
Q - R
ReportContainer
S
SQLDataProvider
ReportDictionary
ReportElement
SQLNode
SQLSelectStatement
ReportElementContainer SynchroManager
ReportEngine (partially supported)
ReportExpression
ReportInfo
ReportStructure
Representation
T - U - V
11 2012-06-15
Preface
12 2012-06-15
Introduction to the ReportEngine SDK
Introduction to the ReportEngine SDK
The ReportEngine SDK is used to view Web Intelligence. The ReportEngine SDK is considered as a component of SAP BusinessObjects Business Intelligence SDK as they are designed to work together.
You can use, Java API interfaces to create web portals that access the back-end SAP BusinessObjects
BI server.
3.1 Packages for customizing SAP BusinessObjects Enterprise
There are two packages for customizing SAP BusinessObjects Business Intelligence platform:
• SAP BusinessObjects BI platform SDK
This package is called the platform package and provides platform functions of the SAP
BusinessObjects BI servers and document scheduling.
• ReportEngine SDK
This package plugs into SAP BusinessObjects BI platform SDK. It provides functionalities of Web
Intelligence ReportEngine.
13 2012-06-15
Introduction to the ReportEngine SDK
3.2 ReportEngine SDK in SAP BusinessObjects Enterprise environment
SAP BusinessObjects Business Intelligence Framework is a framework of servers that facilitates enterprise-wide, web-based management and distribution of reports. Web applications can access the functionality of SAP BusinessObjects BI through APIs provided by the SAP BusinessObjects Business
Intelligence SDK and ReportEngine SDK. For detailed information on SAP BusinessObjects BI, see the Business Intelligence Java SDK Developer Guide.
The diagram below illustrates the relationship between the ReportEngine SDK and other SAP
BusinessObjects BI platform components.
14 2012-06-15
Workflow of ReportEngine SDK application
Workflow of ReportEngine SDK application
All applications that use ReportEngine SDK do not have the same features. But all typically provide features for listing and viewing documents contained in the SAP BusinessObjects BI Central Management
System (CMS).
4.1 Application essentials
Every application that uses ReportEngine SDK has to perform common tasks such as importing the appropriate packages, and creating and managing the user's SAP BusinessObjects BI session (login).
Every application has to take user profiles into account and ensure that errors are handled properly.
4.2 Viewing reports
An application that allows to view documents can display them using the default DHTML format. It is easy to extend the functions to handle documents that contain prompts, and to provide drilling functions.
These extended functions are handled when a document is refreshed.
The viewing features depends on the type of document opened (Web Intelligence, Adobe Acrobat,
Microsoft Excel, XML).
4.3 Open document workflow
The following diagram shows the workflow for opening a document.
15 2012-06-15
Workflow of ReportEngine SDK application
The document contains data that is retrieved from the data source (universe). Each document is identified by an unique ID which is required to open a document.
4.4 Refresh document workflow
The following diagram shows the workflow for refreshing a document.
16
The document must be refreshed to get the latest information from the data source. The refresh action requires prompt information if the document contains prompts, and context information if the document contains contexts.
2012-06-15
Setting up development environment
Setting up development environment
This section describes how to set up a development environment for web application based on
ReportEngine SDK in a Java environment.
5.1 Setting up the Java environment
To setup the ReportEngine Java environment, refer the following sections:
• Setting up the Eclipse environment
• Project Setup
5.1.1 Setting up the Eclipse environment
Eclipse is an Integrated Development Environment (IDE) which provides a universal toolset for application development. Eclipse is an open development platform and can be downloaded from the eclipse web site for free of cost.
To create a Java web-based application, you must have an application server and Java Development
Kit (JDK) installed on the machine. By default, Apache Tomcat application server is installed along with
SAP BusinessObjects Business Intelligence installation. Hence, an example on creating a dynamic web project is explained considering Apache Tomcat as an application server.
5.1.2 Project Setup
It is recommended to create a dynamic web project using Eclipse. It has the following advantages:
• External jars and other Eclipse projects can be included in the working project.
• Easy to export a war file which can be deployed in any application server.
• Easy to run the application code.
17 2012-06-15
Setting up development environment
The Web project contains the JSP files, images and various web components in a structured manner.
The WEB-INF, lib, classes and other directories which are required to create a web application will be predefined. This makes the coding simpler.
5.1.2.1 Creating a dynamic web project
The following are the pre-requisites for creating a web application:
• Eclipse IDE for Java EE Developers must be installed and configured.
• Apache Tomcat application server must be installed.
• Java Development Kit (JDK) must be installed and configured.
1.
Launch Eclipse by selecting a workspace.
2.
In the Package Explorer panel, right-click, select New Runtime and click Project.
"Select a Wizard" window appears.
3.
In the list box, expand Web and select Dynamic Web Project.
4.
Click Next.
"Dynamic Web Project" window appears.
5.
Enter the "Project Name".
6.
Under "Target Runtime", click New.
"New Server Runtime Environment" window appears.
7.
Under "Select the type of runtime that you want to define:", expand Apache and select the runtime.
8.
Click Next.
"Tomcat Server" window appears.
9.
Under "Tomcat installation directory", click Browse and select the Tomcat installation directory.
10.
Under JRE, click Installed JREs.
"Installed JREs" window appears.
11.
Click Add, select the type of JRE to add to the workspace, click Next.
12.
Enter "JRE name", "JRE home directory " and click OK
13.
In the "Installed JREs" window, select the JRE and click OK.
14.
Click Finish.
15.
Click Finish.
A dynamic web project is created. We recommend that you work in a JEE perspective.
5.1.2.2 Adding Rebean jars to the project
18 2012-06-15
Setting up development environment
1.
In the Project Explorer, right-click on the project, select Build Path and click Configure Build
Path.
"Properties for Project" window appears.
2.
Select Java Build Path and click on Libraries tab.
3.
Click on Add External JARS.
"Jar Selection" window appears.
4.
Navigate to <BOBJ_INST_DIR>\SAP BusinessObjects\SAP BusinessObjects Enterprise
XI 4.0\java\lib directory, select all the jars and click Open.
The Rebean jars gets added in the library ...\java resources\librairies.
5.
Click OK.
6.
Expand project, under WebContent directory, expand the WEB-INF directory. Right-click on lib directory and click on Import.
"Import" window appears.
7.
Expand General, select File System and click Next.
8.
Click Browse, navigate to <BOBJ_INST_DIR>\SAP BusinessObjects\SAP BusinessObjects
Enterprise XI 4.0\java\lib directory, select all the jars and click Finish.
The jars gets imported to WEB-INF\lib directory.
5.1.2.3 Creating and running a JSP page
1.
In the Project Explorer, right-click on the WebContent directory, select New and then click JSP
file.
"New JavaServer Page" window appears.
2.
Enter the "File name" and click Finish.
JSP file gets created under WebContent directory.
3.
Double-click on the JSP file and write the code in it.
4.
In the Project Explorer, right-click on the JSP file, select Run As and click Run On Server.
"Run On Server" window appears.
5.
Move the project to the right to configure it on the server and click Finish.
The JSP file will be executed and the result will be shown in a browser.
19 2012-06-15
Setting up development environment
20 2012-06-15
Developing a web application using ReportEngine SDK
Developing a web application using ReportEngine SDK
This section describes procedures to develop a custom web application using ReportEngine SDK.
6.1 Overview
Before providing viewing functions, the ReportEngine SDK applications need to perform basic tasks, such as referencing the appropriate package and creating a BusinessObjects Business Intelligence session for the user.
This section covers the essential concepts and tasks, which all the applications that customize
BusinessObjects Business Intelligence must use.
See Business Intelligence plaform Java SDK Developer Guide at the link referenced below.
Related Topics
• http://help.sap.com
6.2 Working with the ReportEngine SDK
All applications that view Web Intelligence documents must:
• reference ReportEngine SDK
• retrieve the ReportEngines service
• retrieve the ReportEngine instance
This links the ReportEngine and platform packages.
• close the ReportEngines object
Note:
You can use the ReportEngine SDK to view, refresh, fill prompt, fill context, drill (partially), save Web
Intelligence documents.
21 2012-06-15
Developing a web application using ReportEngine SDK
6.2.1 Referencing ReportEngine SDK
Referencing the ReportEngine packages gives your web application an access to the ReportEngine
SDK functions.
ReportEngine SDK allows users to work with the Web Intelligence documents. Use the ReportEngines factory object to retrieve the ReportEngine instance.
6.2.2 Closing a ReportEngines object
To close a BusinessObjects BI session, you must close a ReportEngines instance when you have finished with it. To close a ReportEngines instance use ReportEngines.close(). This method deallocates the memory assigned to the object and must be called before you call IEnterpriseSes sion.logoff()
.
6.3 Document Management - Overview
Two key parts of a typical ReportEngine SDK application are:
1.
Listing the documents that the user can view.
2.
Depending on the user's rights, allowing the user to browse and manage categories and folders used to organize the documents.
This section explains how to open, list, and work with documents.
6.3.1 Document types
With BusinessObjects Enterprise SDK, you can work with the following document types:
• Web Intelligence documents
• Crystal Reports documents
• third-party documents, for example Microsoft Excel (.xls), and Adobe Acrobat (.pdf) files
22 2012-06-15
Developing a web application using ReportEngine SDK
Working with the Web Intelligence documents using the ReportEngine SDK
Using ReportEngine SDK you can do everything that Web Intelligence users can do with Web Intelligence documents:
• view as DHTML
• view as PDF
• view as Excel
• view as XML
• refresh
• drill (partially)
• save
6.3.2 Document state: storage tokens
Storage tokens represents a state of a document at a particular stage, each time a document is modified.
For example, the document state changes when the document is refreshed.
Storage tokens are used to restore a document state previously saved.
6.3.2.1 Storage token life cycle
ReportEngine SDK creates a temporary state that contains information about the document's current state.
A temporary state is created when (an only when) one calls DocumentInstance.getStorageToken()
As the document changes state through the execution of JSP files, the storage token changes too, and more temporary states are created representing the document's states.
You can retrieve the maximum number of storage tokens that can be created as a document changes state programmatically and validate that a storage token is valid by calling ReportEngine.getStor
ageTokenStackSize() and ReportEngine.IsStorageTokenValid respectively.
6.3.2.2 Advantages of storage tokens
23 2012-06-15
Developing a web application using ReportEngine SDK
The advantages of storage tokens are as follows:
Performance
Using storage token, you can quickly switch between the document states. It also helps to optimize the memory usage.
Lifetime
A storage token lasts as long as the ReportEngines object used to create ReportEngine instance exists. Business Objects recommends you to store a ReportEngines object in the JSP session object once it is created and retrieve it again as required, for document storage tokens to be valid throughout an application.
Browser navigation: back and forward
After progressing through several document states, users can go back and forward in their browser to a previous document state and continue working from that state.
Undo mechanism
You can build an undo mechanism by passing the storage token from the previous action performed on the document to the next web page.
6.3.3 Working with documents
Working with documents involves opening and listing the documents, and providing facilities for saving, sending, scheduling, and organizing documents.
Note:
For more information on listing, sending, scheduling see
Business Intelligence platform Java SDK
Developer Guide at the link referenced below
Related Topics
• http://help.sap.com
6.3.3.1 Opening documents
After establishing a session for a user, you can open a document on behalf of the user.
1.
Establish a BusinessObjects BI session for the user.
2.
Get an identifier for the document.
24 2012-06-15
Developing a web application using ReportEngine SDK
The identifier can be a storage token, or more simply the document's ID.
3.
Retrieve the ReportEngine instance to open the document of desired type.
4.
Open the document using the ReportEngine.openDocument() method for Web Intelligence documents.
6.3.3.2 Saving documents
To save a document to Central Management Server, use DocumentInstance.save and DocumentIn stance.saveAs
.
Example: Saving a 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 = theReportEngines.getDocumentFromStorageToken(docToken); docToSave.save();
%>
6.3.3.3 Using ReportPart
A report part can be a block, section, image or cell within a report. Each report part is identified by a reference. You can extract a report part reference of the particular report element by getting the report output in XML format.
The report part feature allows you to select:
• A specific part of a report
• Multiple parts of the same report
• Report parts located in different reports, but in the same document
Each report part is associated with an Unique Reference and a Temporary Reference. A brief explanation of references is given below:
• Unique Reference: It is a constant reference that identifies a single element in the report structure.
Its occurrence in the report output is associated with the data in the cube.
25 2012-06-15
Developing a web application using ReportEngine SDK
• Temporary Reference: It is a temporary reference that identifies a single element in the report structure. Its occurrence in the report output is index-based.
For example, consider a report with sections containing "Year" object.
2001 - (temporary reference - t1, unique reference - u1)
2002 - (temporary reference - t2, unique reference - u2)
2003 - (temporary reference - t3, unique reference - u3)
When you request for report part using "t2" temporary reference, you will get "2002" section.
Again, consider that after data refresh, the "2002" section in the report gets deleted,
2001 - (temporary reference - t1, unique reference - u1)
2003 - (temporary reference - t2, unique reference - u3)
2004 - (temporary reference - t3, unique reference - u4)
When you request for report part using "t2" temporary reference, you will now get "2003" section.
However, if you use "u3" unique reference in both cases, you will get "2003" section.
Example: Accessing the report part using the ReportPartReference in Java
DocumentInstance wiDoc = repEng.openDocument(Integer.parseInt(strDocId));
String[] reference = new String[1];
//Find the report part reference by getting XMLView of the document.In the XMLView, you will find only temporary reference(for example,<bag layout="bag" index = "Caroline" ref =
"2.3----y.1">) reference[0] = "2.3----y.1";
ReportParts objReportParts = wiDoc.getReportParts(reference,OutputFormatType.PDF);
ReportPart objReportPart = objReportParts.getItem(0);
//To find unique reference, you should get the ReportPart using temporary reference and find out unique reference associated to it.
String uniqueRef = objReportPart.getUniqueReference();
BinaryView myBOView = (BinaryView) objReportParts.getView();
OutputStream outputStream = response.getOutputStream(); response.setContentType("application/pdf"); response.setHeader("Content-Type","application/pdf"); response.setDateHeader("expires", 0); myBOView.getContent(outputStream);
6.3.3.3.1 Report part output customization
A set of properties could be used for output customization.
The following properties are supported only in XML format:
•
OutputPropertiesType.XML_UNIT(metric, pixel) requests the XML report output to be expressed using a specific measurement unit.
•
OutputPropertiesType.XML_FONT_MAPPING(none, html, java, win, ttf) requests that the XML report output maps logical font names to platform specific names.
•
The following property is available for all output formats:
26 2012-06-15
Developing a web application using ReportEngine SDK
•
OutputPropertiesType.XML_DPI_FACTOR(default 96 dots per inch) sets the DPI factor used by the report engine to performe measurement unit conversions
Example: Example of retrieving a report part
Properties properties = new Properties(); properties.setProperty(OutputPropertiesType.DPI_FACTOR, "600");
ReportParts objReportParts = wiDoc.getReportParts(reference,OutputFormatType.PDF,properties);
6.3.4 Document properties
Some important characteristics of Web Intelligence documents are stored as part of the document. You can access these properties using the DocumentInstance object.
For ReportEngine SDK, following is the process for accessing the properties of a Web Intelligence document:
1.
Get the collection of properties.
2.
Set/Read the property.
3.
Commit the change, if any, to the collection of properties.
6.3.4.1 Working with properties
Using ReportEngine SDK, you can access the properties of the document using DocumentIn stance.getProperties
and DocumentInstance.setProperties methods. These methods make use of the java.util.Properties class.
There are predefined properties defined in PropertiesType. You can also add your own properties to the document.
To avoid confusion in the Central Management System, PropertiesType.NAME is read only.
Example: Getting the name of a document
The following 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);
27 2012-06-15
Developing a web application using ReportEngine SDK
6.3.4.2 Adding your own properties to the document
Use Properties.setProperty to add your own properties to the document.
Example: Adding RefreshCount property to a document
The following 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"); doc.setProperties (props);
If you create a new Properties collection and add properties to that collection, when you call Doc umentInstance.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 the properties that you have set in the new collection take precedence over those in the one attached to the DocumentInstance.
6.4 Viewing reports - Overview
Web Intelligence ReportEngine SDK contains classes and methods for viewing documents. Applications for viewing Web Intelligence documents handle prompts, and provide report and section navigation using the ReportMap.
This chapter discusses how to use ReportEngine SDK to view Web Intelligence reports.
6.4.1 Viewing reports
You can view complete documents, including all reports or individual reports or report pages in a variety of different formats. The following tables show the different formats available:
Web Intelligence Documents
28 2012-06-15
Developing a web application using ReportEngine SDK
Document
Report
Report Page
DataProviders
BINARY
CONTENT
EXCEL
DataCentric
EXCEL PDF CSV XML DHTML HTML MHTML
Y Y
Y
Y
Y
Y
Y Y Y
Y Y Y Y Y
Y
Y
Y
Y
Y
Y
Y
Y DataProvider
Report part Y Y Y Y Y Y
Quick Display
Mode
Y Y Y Y Y Y Y
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 DHTML format, you need to get views of each report in DHTML and display them separately. For more information on supported views refer API documentation of the SupportedViews interface.
6.4.1.1 Viewing all the reports in a document
To view all the reports in a document:
1.
Open the document.
2.
Get a binary view of the document.
You can get a binary view of a document in PDF or Microsoft Excel format. When ReportEngine
SDK converts the document into PDF, it places the 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.
29 2012-06-15
Developing a web application using ReportEngine SDK
3.
You must prepare the response object to receive an appropriate content type. For Adobe Acrobat format, set the content type to "application/pdf". For Microsoft Excel format, set the content type to
"application/vnd.ms-excel".
Example: Viewing all the reports in a Web Intelligence document
The following code fragment displays all the reports of 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 parameters are passed to the script in the query string.
<%
// get the document
String strDocID = request.getParameter("DocID"); int intDocID = Integer.parseInt(strDocID)
String strQuery = "Select SI_KIND from CI_INFOOBJECTS "
+ "where SI_ID=" + strDocID;
IInfoObjects iDocuments = iStore.query(strQuery);
IInfoObject iDocument = (IInfoObject) iDocObjects.get(0);
String strKind = iDocObject.getKind();
// Instantiate appropriate ReportEngine according to
// document type
ReportEngine repEng = null;
// Open the document using its repository ID
DocumentInstance doc = repEng.openDocument(intDocID);
BinaryView docBinaryView = (BinaryView)doc.getView(OutputFormatType.PDF);
//Parameterize the response response.setContentType("application/pdf"); esponse.setDateHeader("expires", 0);
//output the binary stream via the response object docBinaryView.getContent(response.getOutputStream());
%>
6.4.1.2 Navigating the report
The PaginationMode object helps you to navigate through the displayed report.
The following are the supported pagination modes:
1.
Page mode: In Page mode, a report is displayed in different pages as per the format settings. You can use all the methods in PageNavigation interface to navigate to different pages of the report.
2.
Listing mode: In Listing mode, the entire report is displayed in a single page.
Note:
Listing mode can bring in performance overhead on the large report data.
3.
QuickDisplay mode: In QuickDisplay mode, you can control the amount of data displayed in the report. You can also use all the methods in PageNavigation interface to navigate to different pages of a report. The maximum number of records, height and width of page can be managed through Central Management Console Web Intelligence Properties.
When you save a document, the current PaginationMode is saved along with each report of the document. When the user reopens the document, the pagination mode information with which it was
30 2012-06-15
Developing a web application using ReportEngine SDK saved, is automatically considered. For performance reason, when viewing a document, the Listing mode is changed to QuickDisplay mode by default.
To navigate to the last page of the report in QuickDisplay mode:
1.
Get the document instance.
2.
Choose a report.
3.
Set the pagination mode to QuickDisplay.
4.
Navigate the report to the last page using PageNavigation.last().
5.
Display the report.
The following code explains how to navigate to the last page of the report using ReportEngine SDK
API.
Example: Navigating to last page of a report using QuickDisplay mode
DocumentInstance wiDoc = repEng.openDocument(docId);
Reports reps = wiDoc.getReports();
Report rep = reps.getItem(0); rep.setPaginationMode(PaginationMode.QuickDisplay);
PageNavigation pageNavigation = rep.getPageNavigation(); pageNavigation.last();
HTMLView htmlView = (HTMLView)rep.getView(OutputFormatType.DHTML);
PrintWriter writer = response.getWriter(); htmlView.getContent(writer, "", ""); writer.close();
31
6.4.1.3 Viewing an individual report in DHTML
DHTML is the standard format for viewing reports.
To view an individual report in DHTML format:
1.
Get a document instance
2.
Choose a report
3.
Get a view of the report in DHTML format
4.
Display the report
Example: Viewing a report in a Web Intelligence document
The following code fragment displays a selected report of a Web Intelligence document in DHTML format.
<%
// Get query string parameters and initialize variables
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
2012-06-15
Developing a web application using ReportEngine SDK
// Get the document doc = reportEngine.getDocumentFromStorageToken(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 DHTML format
HTMLView docHtmlView = null; docHtmlView = (HTMLView)rep.getView(OutputFormatType.DHTML);
// Set user agent (IE, FireFox…)
String strUserAgent = request.getHeader("User-Agent"); docHtmlView.setUserAgent(strUserAgent);
// Full Report HTML to the output stream docHtmlView.getContent(out, "", "");
%>
<%=docHTMLView%>
6.4.1.4 Viewing an individual report in another format
You can view reports in Adobe Acrobat or Microsoft Excel format. The procedure is same as DHTML format except that, for viewing all the reports in a document, you must get the content of the report as a binary stream which you can output through the response object.
To view a report in a non-DHTML format:
1.
Get the binary view of the report.
2.
The binary view of the document can be obtained through an implicit response object.
Example: Viewing a report in Microsoft Excel format
The following 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);
//output the binary stream via the response object response.setContentType("application/vnd.ms-excel"); response.setDateHeader("expires", 0);
//output the binary stream via the response object byte[] abyBinaryContent = docBinaryView.getContent();
//output the binary stream via the response object outputStream.write(abyBinaryContent);
6.4.1.5 Track Data Changes
32 2012-06-15
Developing a web application using ReportEngine SDK
33
The following sections briefly describe the Track Data Changes feature and the workflow you need to perform to activate and deactivate Track Data Changes feature.
The Track Data Changes feature
The Track Data Changes feature allows you to visualize the differences between two states of the data: a reference state and the last refresh. It saves your time in the data analysis and reduces the time exploring the irrelevant data. This feature compares the current data with the data that is set as a reference and highlights any data that is added, removed, updated, increased, or decreased.
Activating and disabling the Track Data Changes feature
Before showing the data changes, the system has to track the data changes along refreshes. Since tracking of the data changes consumes significant amount of memory and process time, it has to be explicitly activated in the document to maintain the performance.
Use TrackData.setTrackDataMode(ReferenceUpdateMode.USER_DEFINED | Reference
UpdateMode.AUTO) to activate the Track Data Changes and TrackData.setTrackDataMode(Ref erenceUpdateMode.DISABLED) to disable the Track Data Changes feature in the document .
Setting the data to use as a reference
When you activate the Track Data Changes, you need to set the data as a reference for comparison.
You can use the following modes to set the data reference:
•
ReferenceUpdateMode.AUTO
: automatically sets the current data as a reference when you refresh a document.
•
ReferenceUpdateMode.USER_DEFINED
: allows you to explicitly set the data as a reference using
TrackData.setCurrentAsReference()
. This way, you replace the previous data reference with the current data. The future refreshes will be compared with the current data.
•
ReferenceUpdateMode.DISABLED
: allows you to disable the Track Data Changes feature.
Example: Activating the Track Data Changes
if(repEng.getCanTrackData())
{
TrackData data =wiDoc.getTrackData();
// activate trackdata data.setTrackDataMode(ReferenceUpdateMode.USER_DEFINED); data.setCurrentAsReference();
}
Setting the display options
After you activate the Track Data Changes, you must set the display options for Track Data Changes.
The following table summarizes the type and condition of the tracked data changes according to object qualification:
Data changes event Dimension Details Measure
Added data Tracked Tracked Tracked
2012-06-15
Developing a web application using ReportEngine SDK
Data changes event
Removed data
Changed data
Increased data
Decreased data
Dimension
Tracked
N/A
N/A
N/A
Details
Tracked
Tracked
N/A
N/A
Measure
Tracked
N/A
Tracked
Tracked
The changed data are displayed with a predefined style based on a combination of the following cell settings:
• Font Style
• Text Underlined
• Text Strikethrough
• Text Color
• Cell Background
The default values for these parameters are defined at server side and managed through the Central
Management Console Web Intelligence Properties. These changes will take effect only after restarting the Web Intelligence server.
Example: Setting the track data changes options
//get style options
TrackDataOptions options = data.getTrackDataOptions();
TrackDataOption option = options.getInsertedOption();
Decoration decoration = option.getDecoration();
Attributes attributes = decoration.getAttributes(); attributes.setBackground(Color.WHITE); attributes.setForeground(Color.GREEN);
//change the font style
Font font = decoration.getFont(); font.setStyle(StyleType.ITALIC); data.update();
Viewing and hiding the data changes
The following table describes the methods you can use to view and hide the data changes:
34 2012-06-15
Developing a web application using ReportEngine SDK
In the current active report
In all reports
To view the data changes To hide the data changes
TrackDataIn fo.showChanges(true)
TrackDataIn fo.showChanges(false)
TrackDa ta.showChanges(true)
TrackDa ta.showChanges(false)
Example: Viewing the data changes in a specific report
Reports reps = wiDoc.getReports();
Report rep = reps.getItem(0);
TrackDataInfo trackDataInfo = rep.getTrackDataInfo(); trackDataInfo.showChanges(true);
6.4.2 Handling prompts
Prompts are the way to get supplementary information into a query before executing it. In ReportEngine
SDK, the way you handle prompts depends on the type of document you are working on. This section discusses how to handle prompts in Web Intelligence documents.
Prompts are raised when a document is refreshed using DocumentInstance.refresh . 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 the standard prompts.
6.4.2.1 Documents with a single simple prompt
One of the simplest and most common prompt 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.
35 2012-06-15
Developing a web application using ReportEngine SDK
Example: Handling a single, simple prompt
The following 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 is filled, view.jsp is executed.
DocumentInstance doc = reportEngines.getServiceFromStorageToken(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
%>
<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 the Boolean variable 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 simple prompt is:
1.
Get the DocumentInstance object for the document.
2.
Get the Prompts collection for the document.
3.
Enter the values and set the Prompt for the document.
Note:
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.
Do one of the following:
• if the Prompt is not filled, display a form to get a value from the user.
The first time the file is executed.
The form's action parameter is set to refresh.jsp so that this file is executed when the user clicks the OK (submit) button.
• Otherwise, execute view.jsp to display the document's reports.
36 2012-06-15
Developing a web application using ReportEngine SDK
6.4.2.2 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. .
For more information on storage tokens see the link referenced below.
Related Topics
•
Document state: storage tokens
37
6.4.2.3 Documents with many simple prompts
To handle many simple prompt objects, you can extend the workflow of a single simple prompt with a form into which the user can enter values for all the prompts, and a script that handles these values.
The problem this extension raises is that, you must dynamically set the names of the inputs in the form that carry the values of each prompt. To achieve 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 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 example "Handling many, simple prompts" for an illustration on 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.)
2012-06-15
Developing a web application using ReportEngine SDK
The code in this example is from a page called refresh.jsp. When the user chooses to refresh a document, refresh.jsp is executed, then, when the prompt is filled, view.jsp is executed.
<%
//get the document and its prompts
DocumentInstance doc = reportEngine.getServiceFromStorageToken(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)); if ((values != null)&&(values.length != 0)) prompts.getItem(j).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
%>
<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 now required 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 can also use the first prompt parameter PV0 for this purpose.
38 2012-06-15
Developing a web application using ReportEngine SDK
6.4.2.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. The Information Design tool can edit this set as a part of creating the object in the universe. For example, the Quarter object can have the following list of values {Q1, Q2, Q3, Q4}, and the Customer object can 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.
39
Handling prompts that contain Lov objects involves extending the workflow for many, simple prompts.
To do this, check if the prompt object has an associated Lov by calling 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 Lov.getValues, as options of HTML select tag.
Note:
Prompt.getLOV
refreshes data. This can cause problems with nested prompts which must be handled seperately.
Example: Displaying a simple list of values
The following code fragment illustrates how to get the values of a Lov object 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" 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><%
}%>
2012-06-15
Developing a web application using ReportEngine SDK
</select>
</td>
</tr><%
}
}
%><tr><td>
<input name="Submit" type="submit" value="OK">
</form>
<%}%>
<%
</tr></td>
</table>
Note:
The example "Handling multivalued prompts" shows how to modify the select tag to handle multivalued prompts.
6.4.2.5 Optional Prompts
When a prompt is set as optional and when you run the query, user input for that prompt is optional.
Use Prompt.isOptional() to check if the prompt is a optional prompt.
For example, if you have three prompts in a Web Intelligence report and one of them is defined as optional and when you run this query, you need not fill value for this optional prompt.
Note:
Optional prompts are not applicable for nested and hierarchical prompts.
6.4.2.6 Constrained prompts
A prompt is constrained if the answer must come from the prompt's list of values (Lov). In Web
Intelligence, to create constrained prompts select Select Only From List when creating a prompt filter for a query.
You can detect if a prompt is constrained with Prompt.isConstrained.
40
6.4.2.7 Multivalued prompts
Until now we have considered only prompts that can have one value. However, some prompts can require several values before it is 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.
2012-06-15
Developing a web application using ReportEngine SDK
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 is considered complete. However, Web Intelligence forms these kinds of prompts as two separate prompts, you need not treat them as a multivalued prompt.
Use Prompt.getType(), to detect how many values the prompt requires. A prompt can either be
PromptType.Mono
or PromptType.Multi.
Example: Handling multivalued prompts
The following code fragment illustrates how to modify the <select> tag of the previous example 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>
6.4.2.8 Refreshing a list of values
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.
6.4.2.9 Prompts with multicolumn lists of values
A universe designer can create a list of values that has many columns.
You can check a list of values with more than one column using Values.isMultiColumns.
41 2012-06-15
Developing a web application using ReportEngine SDK
In ReportEngine SDK, a multicolumn list of values is represented as rows in a table with the RowValue interface. Use Values.getRowValue to get a row in the table. And then RowValue.getHeader and
RowValue.getItem
displays 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.enter
Values
. The example below illustrates this.
Example: Handling multicolumn lists of values
The following code fragment illustrates how to display multicolumn lists of values in the select block.
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:
In multicolumn lists of values, value and valueText are different. 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 a row.
42 2012-06-15
Developing a web application using ReportEngine SDK
6.4.2.10 Chunking long lists of values
Some objects, for example Customer name, can have a very long list of values. The Lov interface 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.
Following are the methods used for Lov batching:
•
Lov.getCurrentBatchIndex
•
Lov.getValues
•
Lov.getCurrentBatchName
•
Lov.setBatchSize
6.4.2.11 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 country)
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.
Use Lov.mustFillNestedPrompts to check if a list of values contains its own prompts, then use
Prompt.enterValues
and Lov.setNestedPrompts to enter values and set the nested prompts respectively.
43 2012-06-15
Developing a web application using ReportEngine SDK
Example: Handling nested prompts
The following 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 (doc.getMustFillPrompts()) { this.fillPrompts (prompts, null);
} doc.setPrompts(); else //all prompts are filled and can now display the report response.sendRedirect("view.jsp?
Token="+doc.getStorageToken());
//FUNCTION - fill prompts and handle nested prompts public void fillPrompts (Prompts pmts, Lov parentLOV) {
//pmts is the set of prompts or nested prompts to be filled
//parentLOV is a LOV for which there are unfilled nested 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();
}
6.4.2.12 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.
Example: Refreshing a list of values containing nested prompts
The following code fragment shows how to use the fillPrompts function.
//get and display the LOV
//if the user clicks "Refresh List" lov.refresh();
Prompts nestedPmts = lov.getNestedPrompts(); this.fillPrompts (nestedPmts, lov);
6.4.2.13 Handling context prompts
44 2012-06-15
Developing a web application using ReportEngine SDK
Universe designers define context prompts in universes to ensure that the users retrieve appropriate data when there is more than one way to get the results of a query. For more information about defining contexts, see Information Design Tool User Guide.
The process of filling a context prompt is similar to that of filling many, simple prompts. The contexts in a document are represented by the Contexts collection, and you can check if a document has contexts to fill with DocumentInstance.getMustFillContexts.
To fill a context prompt:
1.
Get contexts.
2.
Display the possible values for each context and get the user's response.
3.
Enter the values for the context provided by the user.
4.
Set the contexts.
6.4.3 Displaying a report map
ReportMap is a representation of the reports and the report sections in a Web Intelligence document.
Content of a report map is retrieved incrementally, this means that only the requested information is calculated.
To get the report map of a document, call DocumentInstance.getReportMap.
Example: Traversing the report map of a Web Intelligence document
The following code fragment traverses the following report structure and gets a section as DHTML.
45
// 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
2012-06-15
Developing a web application using ReportEngine SDK
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
// 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 DHTML page associated with this section
Report report = doc.setPath(sectionPath);
HTMLView view = report.getView(OutputFormatType.DHTML);
6.5 Drilling in Web Intelligence Reports - Overview
Drilling is one of the key feature of Web Intelligence documents, that helps users to analyze the document data.
This chapter discusses how to provide drilling facilities for Web Intelligence documents.
Note:
Drill feature is partially supported starting with BusinessObjects BI 4.0 release.
6.5.1 Introduction to drilling
Drilling controls the amount of details 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 details in the reports by entering into the drill mode and also drill up or down according to the dimension hierarchies
(often called drill hierarchies).
Note:
Depending on the user rights, some users do not have access to the drilling functions.
Users set the scope of analysis to control how much data the Web Intelligence includes in the Dat aProvider
(cube) it creates, when a query is executed.
When a user executes a query, Web Intelligence retrieves data not only 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 DataProvider, and it is not necessary to execute a new query to display the drilled report. .
46 2012-06-15
Developing a web application using ReportEngine SDK
6.5.1.1 The drilling process
To provide users with a drill function, implement the following process:
1.
Request for 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.
Define the drill operation by initializing the document's drilling objects with the information passed in the drill request.
3.
The script instructs Web Intelligence to generate the HTML for the drilled report.
Web Intelligence uses the information in the document's drilling classes to generate the drilled view.
4.
Display the drilled view generated by Web Intelligence .
5.
Repeat steps 2 to 4 for each request for a drill operation.
47
6.5.1.2 Defining the drill operation
You can only define drill operations for drillable documents. A document is considered as 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
2012-06-15
Developing a web application using ReportEngine SDK
• setting the drill path
The details of how you define the drill operation depends on the type of report..
6.5.1.3 Generating the HTML and viewing a drilled report
This step 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.
6.5.1.4 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 DataProvider. 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.
6.5.1.5 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.
Administrators can control a user's access to this facility using Central Management Console.
6.5.1.6 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.
48 2012-06-15
Developing a web application using ReportEngine SDK
6.5.2 Drilling in reports
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") get a DrillInfo instance.
To get the DrillHierarchies 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 the hierarchy but are used in the report, use
DrillInfo.getFreeDimensions
.
Defining the drill operation
A drill operation is defined in terms of drill path. A drill path is represented in ReportEngine SDK by the
DrillPath interface, and consists of a set of parameters such as the IDs of the objects (dimensions)
"from" and "to" which the user is drilling. Defining the drill operation, therefore, involves setting the parameters of the drill path object.
To define the drill operation:
1.
Enter drill mode.
2.
Define the query string parameters, if required.
3.
Get the parameters of the drill request.
4.
Set the drill path.
Entering and leaving drill mode
You must switch a Web Intelligence report into a drill mode so that it can perform the drilling functions.
There are two modes: ReportMode.Viewing and ReportMode.Analysis.
Calling DrillInfo.beginDrill puts a report in ReportMode.Analysis (drill) mode. Calling
DrillInfo.endDrill
stops the drill session and puts a report in ReportMode.Viewing mode.
Setting the drill path
The DrillPath defines the drill operation. To set the drill path:
1.
Get the DrillPath object.
2.
Set the drill action.
3.
Set the block id.
4.
Set the object id of the "drill to" element.
49 2012-06-15
Developing a web application using ReportEngine SDK
5.
Set the object id of the "drill from" element.
6.
Set the filter.
Setting the action: up, down, by, or slice
A user's drill actions are classified by the way they move through the drill hierarchies.
Drill action Resulting report engine action
Up
The report engine replaces the current object with its parent in the drill hierarchy.
Down
By
Slice
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.
50
You set the drill action with DrillPath.setAction. The actions are enumerated by DrillAction
Type
.
Setting the "from" and "to" parameters
To set the from and to parameters of the drill, you must 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 are DrillElements object for the "to" and the "from" dimensions. Individual "from" and "to" elements are represented by DrillFromElement and DrillToElement respectively.
For each drill operation:
1.
Get the drill from and to elements with DrillPath.getTo and DrillPath.getFrom respectively.
2.
Add drill elements to each collection.
3.
Set the object IDs of each drill element using the values you retrieve from the query string.
4.
For each from element, set the filter, if any.
2012-06-15
Developing a web application using ReportEngine SDK
51
a.
The filter remains for drill-by actions between dimensions in the same hierarchy. However for drill-up actions, the filter is removed.
b.
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.
DrillPath drill = info.getDrillPath();
//set the ACTION if (action.equals("down")) drill.setAction(DrillActionType.DOWN); else if (action.equals("up")) drill.setAction(DrillActionType.UP); else if (action.equals("slice")) drill.setAction(DrillActionType.SLICE); else if (action.equals("by")) drill.setAction(DrillActionType.BY);
//set the BLOCK drill.setBlockID(block);
//set the TO drill elements if (to.length > 0) {
DrillElements toElements = drill.getTo(); for (int j = 0;j < to.length; j++) {
DrillToElement toElement =
}
}
(DrillToElement) toElements.add(); toElement.setObjectID(to[j]);
//set the FROM drill elements if (from.length > 0) {
DrillElements fromElements = drill.getFrom(); for (int k = 0; k < from.length; k++) {
DrillFromElement fromElement =
(DrillFromElement) fromElements.add(); fromElement.setObjectID(from[k]);
}
} if ((filter != null) && (filter.length > 0)) fromElement.setFilter(filter[0]);
This example assumes that there is only one value in the array filter: fromElement.setFilter(fil ter[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, to set the filter, you can add the condition if !ac
tion.equals("up")
, since there is no filtering in a drill-up operation. If you set a filter for a drill-up operation, the filter 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.getContent.
6.5.2.1 Displaying the drilled report
To display the drilled report, call HTMLView.getContent.
2012-06-15
Developing a web application using ReportEngine SDK
52
Example: Displaying the drilled report
The following code fragment illustrates how to display a report after executing the drill:
<%
HTMLView htmlView = null; htmlView = (HTMLView) rep.getView(OutputFormatType.DHTML);
String htmlHeader = htmlView.getStringPart("head", false);
%>
<html>
<!-- DRAW HEADER -->
<head>
<link rel="stylesheet" type="text/css" href="style/bomenu.css">
<%=htmlHeader%>
</head>
<!-- DRAW REPORT-->
<%=htmlView.getStringPart("body", true)%>
</html>
6.5.2.2 Manually handling out of scope drill requests
Once you have set the DrillTo and DrillFrom elements, you can check if a drill dimension is not in scope with DrillDimension.isInScope.
If the defined drill operation contains out of scope dimensions with DrillInfo.willGoOutOfScope.
If the DrillDimension is outside the scope of analysis, you can manually extend the scope of analysis with DrillInfo.extendScopeOfAnalysis . This method returns DrillElements collection to which you can add extra drill dimensions that the user wants to include in the analysis.
Use DrillInfo.executeDrill to commit the changes you make to the scope of analysis.
If you want to add a query filter to the extended scope of analysis, use DrillInfo.addQueryCondi
tions
. 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.
6.5.2.3 Adding objects that have prompts
If you extend the scope with an object that contains a prompt in its universe definition, you must fill the prompts it raises before you execute the drill.
6.5.2.4 Taking a snapshot of a drill
2012-06-15
Developing a web application using ReportEngine SDK
You can use DrillInfo.snapshot to take a snapshot of a drilled view and continue drilling. This method adds a report containing the current view to the document's report list and report map.
6.6 Working with Recordsets - Overview
The ReportEngine SDK often uses the recordset data structure for storing information such as the results in a data provider.
This section explains how to use the recordset classes of the ReportEngine SDK.
6.6.1 Anatomy of a recordset
In ReportEngine SDK, recordsets provide a generic way of representing the data contained in a group of objects.
53
Each recordset is divided into rows and columns. Each row can be considered as a record (or a set of fields) and you can access only one record at a time.
Recordsets
In ReportEngine SDK, the Recordset interface represents recordsets.
Field names
The 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 Report Engine Java API Reference
The exception to this is DataProvider.getResult which returns a recordset in which the names of the fields are the names of the results (columns) of the query.
2012-06-15
Developing a web application using ReportEngine SDK
54
Moving around the recordset
To navigate into a recordset, use the following 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. 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.first and Recordset.isFirst to control loops that move through recordsets.
Accessing the value of a field
In ReportEngine SDK, 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 code fragment prints the types of 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 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();
}
2012-06-15
Developing a web application using ReportEngine SDK
This code fragment assumes that rs.getDirection equals FORWARD, and the data provider (dp) is populated.
55 2012-06-15
Developing a web application using ReportEngine SDK
56 2012-06-15
Best Practices to improve ReportEngine performance
Best Practices to improve ReportEngine performance
The following sections helps you to work with ReportEngine in a better way.
7.1 Best Practices
SAP BusinessObjects recommends the following best practices while working with ReportEngine SDK:
• The documents opened during the BusinessObjects Enterprise session are stored and available for the user as long as the session lasts. As a consequence, opening many documents will significantly consume heap memory of the server. To increase the performance, close the document explicitly when it is no longer required. Use DocumentInstance.closeDocument() method to close documents.
• It is recommended to store a ReportEngines object in the JSP session object once it is created for document storage tokens to be valid throughout an application. You can retrieve ReportEngines object when required through session object.
• Store the users IEnterpriseSession object in the Application server's session object, in this way the user session has the same time-out as the Application server's session.
• It is recommended to use getContent(java.io.OutputStream outputStream) method to retrieve the view of the report content. This method improves the performance and scalability of the document retrieval by enabling chunked data transfer. It also improves the memory consumption on both the application and the BusinessObjects servers.
• It is recommended to retrieve the List Of Values(LOV) in chunks or batches when the LOV size is large. This will significantly reduce the amount of time taken to display the LOVs. For even better performance, you can enable the search mode and specify the search pattern which will retrieve only required LOVs.
• It is not recommended to use ReportInfo.getNumberOfPages()method for very large reports.
As the report must be completely computed to retrieve the number of pages, it introduces performance overhead on the server.
• It is not recommended to use PageNavigation.last() method unless it is mandatory. This method will compute all the pages in a report and can cause performance overhead on the server.
• Each time DocumentInstance object is retrieved from the SAP BusinessObjects Web Intelligence server, it is serialized and its state is recreated. Calling ReportEngine.getDocumentFromStor
ageToken(java.lang.String) method uses many resources on the SAP BusinessObjects
57 2012-06-15
Best Practices to improve ReportEngine performance
Web Intelligence server. So, it is recommended to use this method as less as possible for optimal performance.
7.2 Developer tips
• When working with report parts, use unique reference to retrieve the report part from the report. An unique reference is a constant reference that identifies a single element in the report structure, and is associated with the data in the cube.
• If a document contains many optional prompts, then calling Prompt.enterValues() method is optional, but DocumentInstance.setPrompts() method must be called in any case.
• The ViewModeType.ReportPart does not support OutputFormatType.HTML. Hence you cannot view a Web Intelligence document using ViewModeType.ReportPart and OutputFor matType.HTML
in combination.
• The Lov.setSearchMatchCase(boolean) call does not have any effect on the LOVs defined as "Delegated Search" in the universe, as they are searched directly from the database in a case-sensitive manner.
58 2012-06-15
More Information
More Information
Information Resource
SAP product information
SAP Help Portal
Location
http://www.sap.com
http://help.sap.com/businessobjects
Access the most up-to-date English documentation covering all SAP
BusinessObjects products at the SAP Help Portal:
• http://help.sap.com/bobi (Business Intelligence)
• http://help.sap.com/boepm (Enterprise Performance Management)
• http://help.sap.com/boeim (Enterprise Information Management)
Certain guides linked to from the SAP Help Portal are stored on the SAP
Service Marketplace. Customers with a maintenance agreement have an authorized user ID to access this site. To obtain an ID, contact your customer support representative.
To find a comprehensive list of product documentation in all supported languages, visit: http://help.sap.com/boall .
SAP Support Portal
Developer resources http://service.sap.com/bosap-support
The SAP Support Portal contains information about Customer Support programs and services. It also has links to a wide range of technical information and downloads. Customers with a maintenance agreement have an authorized user ID to access this site. To obtain an ID, contact your customer support representative.
http://www.sdn.sap.com/irj/sdn/bi-sdk-dev https://www.sdn.sap.com/irj/sdn/businessobjects-sdklibrary
SAP BusinessObjects articles on the SAP Community Network http://www.sdn.sap.com/irj/boc/articles
These articles were formerly known as technical papers.
59 2012-06-15
More Information
Information Resource
Notes
Location
https://service.sap.com/notes
These notes were formerly known as Knowledge Base articles.
Forums on the SAP Community
Network https://www.sdn.sap.com/irj/scn/forums
Training http://www.sap.com/services/education
From traditional classroom learning to targeted e-learning seminars, we can offer a training package to suit your learning needs and preferred learning style.
Consulting http://www.sap.com/services/bysubject/businessobjectsconsulting
Consultants can accompany you from the initial analysis stage to the delivery of your deployment project. Expertise is available in topics such as relational and multidimensional databases, connectivity, database design tools, and customized embedding technology.
60 2012-06-15
61
Index
A
Adobe Acrobat 22 see also PDF 22
B
BI launch pad
browsers
Business Objects BI sessions
Business Objects Business Intelligence platform sessions
generating HTML 48 hierarchies 48
hyperlinks 47 overview 47 query string parameters 47
transparent drill out of cube 48
F formats
C chunking
closing
contexts
G
D dimensions
displaying
documents 25 changing names 25
H handling
out of scope drill requests 52
hyperlinks
generating for drilling 47, 48
J
L
lists of values (continued)
M managing
Microsoft Excel
N navigating
O opening
P packages
passwords
multicolumn lists of values 41
2012-06-15
Index
Q query strings
R
REBean
refreshing
documents 16, 35, 41 lists of values 41
ReportEngine object
ReportEngine SDK
reports
viewing all the reports in a
repository
RESDK
resolving universe contexts 44
S
sessions
storage tokens
advantages 24 browser navigation 24
generation triggers 23 life cycle 23
T temporary files
transparent drill out of cube 48
traversing
triggers
U universes
user rights
transparent drill out of cube 48
V values
viewing
62 2012-06-15
advertisement
Key Features
- View Web Intelligence documents
- Refresh Web Intelligence documents
- Fill prompts in Web Intelligence documents
- Fill contexts in Web Intelligence documents
- Drill (partially) in Web Intelligence documents
- Save Web Intelligence documents
