installing visualization platform - opentext

Installing Visualization Platform

Information in this document is subject to change without notice. Examples provided are fictitious. No part of this document may be reproduced or transmitted in any form, or by any means, electronic or mechanical, for any purpose, in whole or in part, without the express written permission of Actuate Corporation.

© 1995 - 2014 by Actuate Corporation. All rights reserved. Printed in the United States of America.

Contains information proprietary to:Actuate Corporation, 951 Mariners Island Boulevard, San Mateo, CA 94404

www.actuate.com

The software described in this manual is provided by Actuate Corporation under an Actuate License agreement. The software may be used only in accordance with the terms of the agreement. Actuate software products are protected by U.S. and International patents and patents pending. For a current list of patents, please see http://www.actuate.com/patents.

Actuate Corporation trademarks and registered trademarks include:Actuate, ActuateOne, the Actuate logo, Archived Data Analytics, BIRT, BIRT 360, BIRT Analytics, The BIRT Company, BIRT Content Services, BIRT Data Analyzer, BIRT for Statements, BIRT iHub, BIRT Metrics Management, BIRT Performance Analytics, Collaborative Reporting Architecture, e.Analysis, e.Report, e.Reporting, e.Spreadsheet, Encyclopedia, Interactive Viewing, OnPerformance, The people behind BIRT, Performancesoft, Performancesoft Track, Performancesoft Views, Report Encyclopedia, Reportlet,X2BIRT, and XML reports.

Actuate products may contain third-party products or technologies. Third-party trademarks or registered trademarks of their respective owners, companies, or organizations include: Mark Adler and Jean-loup Gailly (www.zlib.net): zLib. Adobe Systems Incorporated: Flash Player, Source Sans Pro font. Amazon Web Services, Incorporated: Amazon Web Services SDK. Apache Software Foundation (www.apache.org): Ant, Axis, Axis2, Batik, Batik SVG library, Commons Command Line Interface (CLI), Commons Codec, Commons Lang, Commons Math, Crimson, Derby, Hive driver for Hadoop, Kafka, log4j, Pluto, POI ooxml and ooxml-schema, Portlet, Shindig, Struts, Thrift, Tomcat, Velocity, Xalan, Xerces, Xerces2 Java Parser, Xerces-C++ XML Parser, and XML Beans. Daniel Bruce (www.entypo.com): Entypo Pictogram Suite. Castor (www.castor.org), ExoLab Project (www.exolab.org), and Intalio, Inc. (www.intalio.org): Castor. Alessandro Colantonio: CONCISE. Day Management AG: Content Repository for Java. Eclipse Foundation, Inc. (www.eclipse.org): Babel, Data Tools Platform (DTP) ODA, Eclipse SDK, Graphics Editor Framework (GEF), Eclipse Modeling Framework (EMF), Jetty, and Eclipse Web Tools Platform (WTP). Dave Gandy: Font Awesome. Gargoyle Software Inc.: HtmlUnit. GNU Project: GNU Regular Expression. Groovy project (groovy.codehaus.org): Groovy. Guava Libraries: Google Guava. HighSlide: HighCharts. headjs.com: head.js. Hector Project: Cassandra Thrift, Hector. Jason Hsueth and Kenton Varda (code.google.com): Protocole Buffer. H2 Database: H2 database. Groovy project (groovy.codehaus.org): Groovy. IDAutomation.com, Inc.: IDAutomation. IDRsolutions Ltd.: JBIG2. InfoSoft Global (P) Ltd.: FusionCharts, FusionMaps, FusionWidgets, PowerCharts. Matt Inger (sourceforge.net): Ant-Contrib. Matt Ingenthron, Eric D. Lambert, and Dustin Sallings (code.google.com): Spymemcached. International Components for Unicode (ICU): ICU library. JCraft, Inc.: JSch. jQuery: jQuery. Yuri Kanivets (code.google.com): Android Wheel gadget. LEAD Technologies, Inc.: LEADTOOLS. The Legion of the Bouncy Castle: Bouncy Castle Crypto APIs. Bruno Lowagie and Paulo Soares: iText. MetaStuff: dom4j. Microsoft Corporation (Microsoft Developer Network): CompoundDocument Library. Mozilla: Mozilla XML Parser. MySQL Americas, Inc.: MySQL Connector. Netscape Communications Corporation, Inc.: Rhino. nullsoft project: Nullsoft Scriptable Install System. OOPS Consultancy: XMLTask. OpenSSL Project: OpenSSL. Oracle Corporation: Berkeley DB, Java Advanced Imaging, JAXB, JDK, Jstl, Oracle JDBC driver. PostgreSQL Global Development Group: pgAdmin, PostgreSQL, PostgreSQL JDBC driver. Progress Software Corporation: DataDirect Connect XE for JDBC Salesforce, DataDirect JDBC, DataDirect ODBC. Quality Open Software: Simple Logging Facade for Java (SLF4J), SLF4J API and NOP. Rogue Wave Software, Inc.: Rogue Wave Library SourcePro Core, tools.h++. Sam Stephenson (prototype.conio.net): prototype.js. Sencha Inc.: Ext JS, Sencha Touch. Shibboleth Consortium: OpenSAML, Shibboleth Identity Provider. Matteo Spinelli: iscroll. StAX Project (stax.codehaus.org): Streaming API for XML (StAX). SWFObject Project (code.google.com): SWFObject. ThimbleWare, Inc.: JMemcached. Twittr: Twitter Bootstrap. VMWare: Hyperic SIGAR. Woodstox Project (woodstox.codehaus.org): Woodstox Fast XML processor (wstx-asl). World Wide Web Consortium (W3C)(MIT, ERCIM, Keio): Flute, JTidy, Simple API for CSS. XFree86 Project, Inc.: (www.xfree86.org): xvfb. ZXing Project (code.google.com): ZXing.

All other brand or product names are trademarks or registered trademarks of their respective owners, companies, or organizations.

Document No. 131215-2-640350 February 20, 2014

i

ContentsAbout Installing Visualization Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Chapter 1Understanding Visualization Platform clients . . . . . . . . . . . . . . . . . . . . . . . 1About Actuate Visualization Platform client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Planning Visualization Platform client installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Setting up Visualization Platform client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Understanding Visualization Platform client load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Deploying a load balancer for an BIRT iHub cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Using a cluster of application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Visualization Platform client architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Using proxy servers with Visualization Platform client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Disabling administrative capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2Installing Visualization Platform stand-alone client . . . . . . . . . . . . . . . . . . 9Preparing to install Actuate Visualization Platform client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Setting ClearType text properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Setting up Visualization Platform client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Installing using electronic distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Performing a full iHub installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Installing Visualization Platform client on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Installing Visualization Platform client on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Configuring a Linux user account for the Visualization Platform . . . . . . . . . . . . . . . . . . . . . . 16Setting up libstdc++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Using run level 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17About Openmotif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Using the installation scripts for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Using the WAR file to install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19About deployment formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Avoiding cache conflicts after installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Testing the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 3Configuring Actuate Visualization Platform client . . . . . . . . . . . . . . . . . . 25Visualization Platform client web application structure and contents . . . . . . . . . . . . . . . . . . . . 26

Visualization Platform client pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Visualization Platform client directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Configuring a custom Visualization Platform client web application . . . . . . . . . . . . . . . . . . . . . 31

ii

Setting the default locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Controlling the Message Distribution service load balancing . . . . . . . . . . . . . . . . . . . . . . . . . .33Setting the JavaScript MIME types for Apache Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Configuring connections to iHub using volumeProfile.xml . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Modifying global style elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37Visualization Platform client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Configuring Visualization Platform client using web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Configuring locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Configuring time zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47Customizing messages and text according to locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47Configuring the connection to iHub Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Restricting access to Actuate Visualization Platform client features using functionality levels

50Visualization Platform client JavaScript reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53Using Visualization Platform client Java servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

base servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54Invoking a servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Java servlets reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

Visualization Platform client JavaBeans overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59Visualization Platform client JavaBeans package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . .59Visualization Platform client JavaBeans class reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Visualization Platform client UserInfoBean class reference . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Chapter 4Configuring Report Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Assigning license options to a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70Enabling or disabling functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Configuring toolbar and context menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Specifying the default position of aggregate values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82Using sample data in a preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82Configuring advanced data operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

Configuring the application environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

Chapter 5Customizing and integrating Report Studio . . . . . . . . . . . . . . . . . . . . . . . 87About report templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88Design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Separating or combining visual and data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88Designing themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89Improving usability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90

Creating a report template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91Providing data with a report template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Using a CSV file as a data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

iii

Excluding a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Creating themes for a report template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Publishing a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Setting the default template category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Publishing resources associated with a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Types of data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Using data objects as a data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Deploying data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Deploying cross tab templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Creating data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Building a data object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Deploying data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Creating a custom data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Sample ODA data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Extended sample ODA example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112Developing an open data access (ODA) data driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114Developing a custom query builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115Configuring the extended custom data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118

Chapter 6Configuring BIRT Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Configuring the Actuate BIRT Viewer toolbar using iv_config.xml . . . . . . . . . . . . . . . . . . . . . . 122Configuring Actuate BIRT Viewer using web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Configuring a BIRT Viewer Java extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Configuring default export formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

A b o u t I n s t a l l i n g V i s u a l i z a t i o n P l a t f o r m v

A b o u t I n s t a l l i n gV i s u a l i z a t i o n P l a t f o r m

Installing Visualization Platform discusses how to administer a BIRT iHub System volume. The chapters in this guide are:

■ About Installing Visualization Platform. This chapter provides an overview of this guide.

■ Chapter 1. Understanding Visualization Platform clients. This chapter introduces Actuate iHub Visualization Platform client.

■ Chapter 2. Installing Visualization Platform stand-alone client.Installing Actuate Visualization Platform. This chapter discusses installing Actuate iHub Visualization Platform client.

■ Chapter 3. Configuring Actuate Visualization Platform client. This chapter discusses configuring Actuate iHub Visualization Platform client.

■ Chapter 4. Configuring Report Studio. This chapter introduces BIRT Studio.

■ Chapter 6. Configuring BIRT Viewer. This chapter discusses configuring BIRT Viewer.

vi I n s t a l l i n g V i s u a l i z a t i o n P l a t f o r m

C h a p t e r 1 , U n d e r s t a n d i n g V i s u a l i z a t i o n P l a t f o r m c l i e n t s 1

C h a p t e r

1Chapter 1Understanding

Visualization Platformclients

This chapter contains the following topics:

■ About Actuate Visualization Platform client

■ Planning Visualization Platform client installations

2 I n s t a l l i n g V i s u a l i z a t i o n P l a t f o r m

About Actuate Visualization Platform clientUsers access iHub resources using a suite of web-based visualization applications called Visualization Platform client. The Visualization Platform client is a web application that connects to the iHub server and includes a web-based repository content manager that can access visualization tools and web components to service user requests. For example, to open a BIRT Dashboard, Visualization Platform client activates the Dashboard application, which is part of the visualization suite. Additionally, the Actuate APIs extend many of the features of these services so they can be implemented in custom applications. For more information on the Actuate APIs, see Application Integrator Guide.

The web components and visualization tools available from Visualization Platform client are:

■ iHub AdministrationAn application manager for Visualization Platform client services and tools that manages Visualization Platform client users and user groups. Visualization Platform client administration only affects Visualization Platform client services. To handle administrative tasks like managing volumes, use the System Console.

■ Visualization SuiteA suite of web-based applications that you browse, manage, import, export, and modify iHub repository contents. The visualization suite includes the following licensed applications:

■ BIRT Interactive ViewerA web viewer for BIRT report content which also supports printing and saving reports to many formats.

■ BIRT DashboardsA BIRT dashboard manager and editor, that creates and displays custom web and mobile viewing arrangements with interactive elements.

■ Report StudioA BIRT Design and Document editor that manages presentation and whose editing permissions can be finely defined by the administrator or the original designer.

Actuate Visualization Platform client is independent and customizable. You can deploy Visualization Platform client on machines separate from iHub as a standalone application, WAR, or EAR, and all of its component applications deploy with it. In addition, every iHub installation also contains an embedded Visualization Platform client that can be accessed remotely.


Visualization Platform client accesses and stores documents on a volume managed by iHub. Visualization Platform client technology is scalable and supports clustering. On a Windows system, the default context root for Visualization Platform client is the name of the WAR or EAR file, or <installation directory>\iHub3\modules\BIRTiHub\iHub\web\iportal for Visualization Platform client embedded in the BIRT iHub application or setup as a standalone application. On a UNIX-based system, the default context root for Visualization Platform client is the name of the WAR or EAR file or $Home/iHub/web/iportal for Visualization Platform client embedded in the BIRT iHub application or setup as a standalone application.

Planning Visualization Platform client installationsBefore installing Visualization Platform client, you must prepare the operating system and network environments to ensure that you have all the necessary software and configuration resources in place. This section describes how to prepare these environments before starting the Visualization Platform client installation process and discusses deployment concerns that may affect your Visualization Platform client installation and how you wish to deploy reports to the web.

Setting up Visualization Platform clientYou can install Visualization Platform client in several ways:

■ As a separate web application packaged in a WAR or EARThis method employs a third-party web or application server that manages the network traffic to the iHub Visualization Platform client application. An Visualization Platform client WAR or EAR can use native load balancing for iHub clusters, redundancy to support constant report services over the web, and iHub security measures in addition to third party load balancing and security measures.

■ As a windows serviceThis method uses the iHub installer to install Visualization Platform client as a windows service with an embedded web server to handle network traffic. The windows service installation can integrate with iHub security and load balancing, but does not employ a third-party web or application server, so requires different configuration procedures than a WAR or EAR deployment.

■ Automatically on the same host with iHubThis method provides reports locally on each iHub machine. For more information about installing iHub, see Installing Actuate BIRT iHub on Linux or Installing Actuate BIRT iHub on Windows.


For enterprise architectures, installing Visualization Platform client on several web servers is recommended.

To deploy a report to the web, you need:

■ A Visualization Platform client installation.

■ An application server or JSP or servlet engine such as Actuate embedded servlet engine or IBM WebSphere.

■ One or more Actuate designer tools and Actuate BIRT iHub System with iHub Visualization Platform client configuration.

■ Actuate BIRT iHub administrator privileges.

■ Permission to read, write, and modify operating system directories as necessary. For example, the directory Java uses to hold temporary files is defined by the java.io.tmpdir property and is by default the value of the TMP system variable in the Windows environment and /var/tmp in the UNIX and Linux environments. Read and write permission must be provided to the application server running Visualization Platform client for this directory.

Visualization Platform client load balancingVisualization Platform client supports two kinds of load balancing, as illustrated in Figure 1-1, to ensure high availability and to distribute tasks for efficient processing:

Figure 1-1 Load-balancing architecture for Visualization Platform client

■ Actuate Message Distribution service (MDS) balances the request load among BIRT iHub machines in an BIRT iHub cluster.

Web browser

Web browser

Web browser

Third-party application server load balancer

Volume

Volume

Volume

Actuate BIRT iHub

StateServer or SqlServer

Visualization Platform

Application server

Visualization Platform

Application server

Application server

Actuate BIRT iHub

System Console


The Message Distribution service eliminates the need for a third-party network load balancer in front of the BIRT iHub tier. iHub determines which machines in a cluster have MDS running and detects when the MDS machines go offline. MDS distributes the load among the available servers and does not attempt to send a request to an offline machine.

■ Clustered Visualization Platform client machines can use a third-party application to balance the load among the application servers.

Deploying a load balancer for an BIRT iHub clusterTo deploy a load balancer or proxy layer in front of the BIRT iHub tier, disable the Actuate load-balancing support by setting the MDS_ENABLED configuration parameter to False in the web.xml Visualization Platform client configuration file. For EAR and WAR installations, this must be done before deployment. When installing as a Windows service, you can make the configuration change after installing.

Using a cluster of application serversIf the application servers running Visualization Platform client support session state management, you can configure Visualization Platform client and the application servers to share and maintain a web browsing session state across a cluster of Visualization Platform client instances. Configuring the application servers to track the state of each Visualization Platform client instance supports reusing authentication information. In other words, you can log in to a Visualization Platform client instance and send a request using another Visualization Platform client instance without logging in again using the second instance.

If you do not use an application server to track session state information, managing the session state is fast, but you lose a user’s state information when you restart Visualization Platform client or your application server.

Sharing session state information takes advantage of the application servers’ failover features. If a user is on a cluster application server running Visualization Platform client and that application server fails, another application server running Visualization Platform client can manage the user’s session.

An application server works with one or more database servers to manage session state information. All application servers must have access to the database server to store and retrieve session state information. For specific information about configuring your installation, see your application server documentation.


Visualization Platform client architectureThe general Visualization Platform client network architecture is illustrated in Figure 1-2.

Figure 1-2 Visualization Platform client architecture overview

A user submits a request by choosing a link on a web page that specifies an Visualization Platform client URI. As shown in Figure 1-2, the web or application server receives the URI as an HTTP request and passes the request to the servlet or page engine. The engine invokes Visualization Platform client, interprets the URI, and communicates with the BIRT iHub using the Actuate Information Delivery API (IDAPI). The IDAPI manages the request and returns the results to Visualization Platform client and the servlet or page engine. The web server returns the results to the web browser. Then, the web browser displays the results for the user.

Visualization Platform client manages requests as part of a JSP engine within a web or application server. There is no default user interface for the engine. On a Windows system, Visualization Platform client installation places an Visualization Platform client link on the Start menu.

Using proxy servers with Visualization Platform clientWhen setting up a proxy server with Visualization Platform client, there are steps you must take if your internal application server port is protected by a firewall. In this situation, when the proxy server changes the URL to point to the new context’s port, that port is unavailable due to the firewall. The usual solution is to configure a reverse proxy, but if you are using multiple proxies and a reverse proxy is not practical for your installation, Visualization Platform client can perform the redirection.

To redirect a page without using a reverse proxy, Visualization Platform client forwards the URL to redirect to the processRedirect.jsp page and updates the browser’s location bar accordingly. This action processes on the client. The browser takes the current URL location and updates the rest of the URI using the redirected URL. You must also set the ENABLE_CLIENT_SIDE_REDIRECT

Web or Application server

Servlet or Page engine

Visualization Platform client Actuate BIRT

iHub System

Firewall

Web browser

Database Server

Firewall

SOAP portActuate load balancing

IDAPI Proxy

configuration parameter in the <context root>/WEB-INF/web.xml file to True and modify the redirect attributes in the <context root>/WEB-INF/struts-config.xml file. The necessary modifications are included as comments in the file. You just need to comment out the lines that have the redirect attribute set to True and uncomment the lines that forward to the processRedirect.jsp page.

For example, the following code is the struts-config.xml entry for the login action:

<action

path="/login"name="loginForm"scope="request"input="/iportal/activePortal/private/login.jsp"type="com.actuate.activeportal.actions.AcSsoLoginAction"validate="false"><forward name="loginform"

path="/iportal/activePortal/private/login.jsp"/><forward name="success" path="/dashboard/jsp/myfiles.jsp"

redirect="true"/><forward name="dashboard" path="/dashboard" redirect="true"/><forward name="ajcLogin" path="/ajclanding.jsp"

redirect="true"/><forward name="landing" path="/landing.jsp" redirect="false"/><forward name="activate" path="/activate.jsp" redirect="false"

/><forward name="wait" path="/checksaml.jsp" redirect="false" />

</action>

By default the forward statement for success points to myfiles.jsp with the redirect attribute set to True. This code instructs the application server to send a redirect with the myfiles.jsp URL when the user logs in.

From behind a firewall and proxy, this redirect method fails because the redirect sent by the application server points to the application server port instead of the firewall and proxy port. For success, comment out the line having redirect="true". Uncomment the line that points to processRedirect.jsp. The following code shows the updated entry in struts-config.xml:

<action

path="/login"name="loginForm"scope="request"input="/iportal/activePortal/private/login.jsp"type="com.actuate.activeportal.actions.AcSsoLoginAction"

validate="false"><forward name="loginform"

path="/iportal/activePortal/private/login.jsp"/><forward name="success" path="/iportal/activePortal/private

/common/processredirect.jsp?redirectPath=/getfolderitems.do" />



<forward name="dashboard" path="/dashboard" redirect="true"/><forward name="ajcLogin" path="/ajclanding.jsp"

redirect="true"/><forward name="landing" path="/landing.jsp" redirect="false"/><forward name="activate" path="/activate.jsp" redirect="false"

/><forward name="wait" path="/checksaml.jsp" redirect="false" />

</action>

This change needs to be made for all the actions in struts-config.xml that send a redirect to the browser.

Disabling administrative capabilitiesFor most users, the Administrative features in Visualization Platform client are not used and should not be exposed. To remove all administrative capabilities from a Visualization Platform client installation, locate the /admin directory in the application or application WAR. For example, for the Visualization Platform client embedded in iHub, the /admin directory is located in the <iHub install directory>\modules\BIRTiHub\iHub\web\iportal directory. Once the /admin directory is removed, restart the Actuate iHub 3 service.

C h a p t e r 2 , I n s t a l l i n g V i s u a l i z a t i o n P l a t f o r m s t a n d - a l o n e c l i e n t 9

C h a p t e r

2Chapter 2Installing Visualization

Platform stand-alone clientThis chapter contains the following topics:

■ Preparing to install Actuate Visualization Platform client

■ Using the WAR or EAR file to install


Preparing to install Actuate Visualization Platform client

Before installing Visualization Platform client, you must prepare the operating system environment to ensure that you have all the necessary software and configuration resources in place. This section describes how to prepare the environment before starting the Visualization Platform client installation process. This section discusses deployment concerns that affect your Visualization Platform client installation and how you wish to deploy reports to the web.

To deploy a report to the web, you need:

■ A Visualization Platform client WAR or EAR appropriate to your web or application server.

■ An application server or JSP or servlet engine such as Actuate embedded servlet engine or IBM WebSphere.

■ One or more Actuate designer tools and Actuate BIRT iHub System with iHub Visualization Platform client configuration.

■ Actuate BIRT iHub administrator privileges.

■ Permission to read, write, and modify operating system directories as necessary. For example, the directory Java uses to hold temporary files is defined by the java.io.tmpdir property and is by default the value of the TMP system variable in the Windows environment and /var/tmp in the UNIX and Linux environments. Read and write permission must be provided to the application server running Visualization Platform client for this directory.

For optimal appearance of BIRT iHub pages, ensure that ClearType is set on the Windows system used to access BIRT iHub.

Setting ClearType text propertiesUsing ClearType text on a Windows system provides the optimal appearance for BIRT iHub pages. All Visualization Platform users need this configuration setting.

How to configure ClearType text

To configure ClearType text, perform the following steps.

1 In Windows Control Panel➛Appearance and Personalization, choose Adjust ClearType text. ClearType Text Tuner appears.

2 Select Turn on ClearType. Choose Next.

3 For each of the pages in ClearType Text Tuner, select the sample that looks best to you and then choose Next.

4 In You have finished tuning the text on your monitor, choose Finish.


Setting up Visualization Platform clientYou install Visualization Platform client in either of two ways:

■ As a stand-alone web application. This method enables native load balancing for iHub clusters, redundancy to support constant report services over the web, and secure networks using firewalls and proxy severs.

■ Automatically on the same host with iHub. This method provides reports locally on each iHub machine.

For enterprise architectures, installing Visualization Platform client on several web or application servers is recommended.

Installing using electronic distribution If you download an Actuate product from the Actuate FTP or HTTP site, keep all the files together in their original relative locations when you extract them. The installation program verifies that all necessary files are present before installing Visualization Platform client. If any files are missing, the installation program exits. Files can be missing if you extract the files, move only some of the files to a new location, and attempt to install from that location.

Performing a full iHub installationBIRT iHub Visualization Platform installs Visualization Platform client automatically on the machine where it resides. Typically, a manual Visualization Platform client installation is done to provide network access to iHub from a remote machine.

To access online documentation, such as the online help and PDF files of the product manuals, install the documentation files from the following location:

http://www.actuate.com

Installing Visualization Platform client as a stand-alone application

This procedure installs Visualization Platform client as a separate web application without integrating a new node with an iHub cluster.

1 Install Visualization Platform client on the client system using the install script.

1 Extract iHub3.zip to a folder on the file system just as you would for an iHub Installation.

2 Open acinstall.properties for editing.

3 Modify the value of the ac.package parameter to include m and c, as showing the following code:

ac.package=m,c


4 Save acinstall.properties and close it.

5 Choose Start and type cmd. Then, type Ctrl+Shift+Enter to run the command window as Administrator.

6 Navigate to the iHub extraction folder and type install. The installer installs Visualization Platform client and the JDK the Actuate iHub 3 service uses.

7 Exit the command line.

2 Navigate to the <context root>\WEB-INF directory and open web.xml for editing.

3 Find the SAMLEntityID parameters and change the parameter value to the iportal service URL for the iHub Server. For example, if the iHub server was deployed on server1, the SAMLEntityID parameter would look like the following:

<context-param><description>The SP ID for SAML SSO</description><param-name>SAMLEntityID</param-name><param-value>http://server1:8700/iportal</param-value>

</context-param>

4 Save web.xml and close it.

5 Restart the Actuate iHub 3 Service.

1 Choose Start➛Control Panel. Open Administrative Tools.

2 In Administrative Tools, choose Services.

3 In Services, select Actuate iHub 3 Service and choose restart.

6 Open a web browser and navigate to the system console for the iHub Server. The default URL for the system console is shown in the following URL:

http://iHubSystem:8500/sysconsole

where iHubSystem is the fully qualified domain name or IP address of the iHub Server system.

7 Choose Clusters. Open the context menu for a cluster and choose edit.

8 Choose Single Sign-On, and choose iHub User Management (default) from the Select User Management drop-down menu.

9 Choose Add Service provider.

10 In Add Service Provider, in Server URL type the iportal application URL for the Visualization Platform client. Entity Id fills automatically, as shown in Figure 2-3.


Figure 2-3 Adding a Service Provider for Visualization Platform client

Choose OK, then choose Save. On the confirmation dialog, choose OK

Using the WAR or EAR file to installIf Actuate supports your application server, you can deploy Visualization Platform client as a WAR file. See your application server documentation about how to deploy a WAR file. For information about application servers on which Actuate supports deployment of Visualization Platform client, see the Supported Products Matrix for this release on the Actuate Support site at the following URL:

http://support.actuate.com/documentation/spm

Customize Visualization Platform client for your local environment, if necessary, before beginning deployment. To customize the application for your local environment, follow the steps in “Preparing the WAR file,” later in this section. Deploy the customized Visualization Platform client WAR file to the application server instead of the ActuateInformationConsole.war file that ships with Visualization Platform client.

About deployment formatsActuate provides Visualization Platform client in WAR and EAR formats individually packaged for the latest versions of specific web and application servers. The formats suitable for deployment on different application servers shown in Table 2-1.

Table 2-1 BIRT Visualization platform deployment formats

File Application server

WL_ActuateInformationConsole.war BEA WebLogic

TOMCAT_ActuateInformationConsole.war Apache Tomcat, Jetty HTTP and Application Server

http://support.actuate.com/documentation/spm


The Apache Tomcat and WebLogic servers do not support EAR deployment. Only the JBoss and WebSphere application servers support EAR deployment.

General deployment tasksYou must configure the Visualization Platform client WAR and application server for integration. You must also verify that you have a standard J2EE installation.

To integrate your application server with Actuate, complete the following tasks:

■ Configure the application server to operate with Actuate products.

■ Configure the Visualization Platform client WAR to integrate with the application server as described in “Preparing the WAR file,” later in this chapter.

■ Deploy Visualization Platform client to the application server.

■ If the application server has deployment tools, use those tools to integrate the application server with Actuate products. For more information about deployment tools, see your application server’s documentation.

■ If your application server does not have deployment tools, add the Actuate context root to your application server, typically by modifying the application server’s configuration file.

Preparing the serverActuate recommends the following configuration for best performance:

■ Use at least a two-CPU machine for Visualization Platform client.

■ If BIRT iHub system uses more than four CPUs, configure one CPU for Visualization Platform client for every two CPUs that iHub uses.

Set the following configuration values on the application or web server:

■ On a machine with 1 GB of available physical memory, set the Java heap size to a value between 256 MB and 512 MB.

■ Set the number of threads to a value between 50 and 75.

Preparing the WAR fileYou can use a WAR file to deploy Visualization Platform client to many supported servers. To enable shindig 2.0 support for a deployable Visualization

JBOSS_ActuateInformationConsole.ear JBoss

WAS_ActuateInformationConsole.ear IBM WebSphere

Table 2-1 BIRT Visualization platform deployment formats

File Application server


Platform client’s WAR or EAR file, modify the host name, port, and context root in the following configuration files:

<context root>/WEB-INF/web.xml<context root>/WEB-INF/classes/shindig.properties <context root>/WEB-INF/classes/containers/default/container.js

In web.xml, update the following parameters:

<param-name>system.properties</param-name><param-value> shindig.host=<host name> shindig.port=<port> </param-value>

■ <host name> is the name of the web server hosting the Visualization Platform client web application.

■ <port> is the TCP port assigned to the Visualization Platform client web application.

In shindig.config, update the following parameter:

shindig.signing.global-callback-url=http://<host name>:<port>/<context>/gadgets/oauthcallback

■ <host name> is the name of the web server hosting the Visualization Platform client web application.

■ <port> is the TCP port assigned to the Visualization Platform client web application.

■ <context> is the context root of the Visualization Platform client web application.

In container.js update the following parameters:

"gadgets.jsUriTemplate" : "http://%host%/<context>/gadgets/js/%js%"

"gadgets.oauthGadgetCallbackTemplate" : "//%host%/<context>/gadgets/oauthcallback"

"gadgets.osDataUri" : "http://%host%/<context>/social/rpc""proxyUrl" : "//%host%/<context>/gadgets/

proxy?refresh=%refresh%&url=%url%","jsonProxyUrl" : "//%host%/<context>/gadgets/makeRequest""path" : "http://%host%/<context>/social""endPoints" : [ "http://%host%/<context>/social/rpc", "http://

%host%/<context>/gadgets/api/rpc" ]

■ <context> is the context root of the Visualization Platform client web application.


Table 2-1 describes the Visualization Platform client configuration parameters to review and update before deployment.

How to customize the WAR file

The following steps describe the general procedure for customizing an Visualization Platform client WAR file:

1 Create a temporary directory, such as C:/Temp/ic.

If you use an existing directory, ensure that this directory is empty.

2 Open a command window and type the following commands, replacing the X: drive letter with a drive letter or download path appropriate to your system:

Table 2-1 Visualization Platform client configuration parameters

Parameter name Description Action

BIRT_RESOURCE_PATH

The location of the standard templates and properties files that BIRT Studio uses. This location can be in a WAR file or on a disk.

If you specify a location on disk, copy the contents of the Visualization Platform client resources folder to this physical location on the file system.

DEFAULT_LOCALE

The default locale is en_US. You can leave this value unchanged. A user can select a locale at login.

If you change the locale, select the new locale from the locales in /WEB-INF/Localemap.xml.

DEFAULT_TIMEZONE

The default time zone is Pacific Standard Time (PST). You can leave this value unchanged. A user can select a time zone at login.

If you change the time zone, select the new time zone from the time zones in the TimeZones.xml file, in the WEB-INF directory.

BIRT_VIEWER_LOG_DIR

The location of the files that log Actuate BIRT viewer activity.

You must create this physical location on the file system.

LOG_FILE_LOCATION

The location of the files that log Visualization Platform client activity.


TEMP_FOLDER_LOCATION

The location where Visualization Platform client creates temporary files.


TRANSIENT_STORE_PATH

The location where Visualization Platform client creates temporary files.



1 Copy the appropriate Visualization Platform client WAR file for your environment, such as TOMCAT_ActuateInformationConsole.war, to the temporary directory, as shown in the following example:

cd C:/Temp/iccopy X:/TOMCAT_ActuateInformationConsole.war .

2 Decompress the file, as shown in the following example:

jar -xf TOMCAT_ActuateInformationConsole.war

The Visualization Platform client files appear in the temporary directory. Leave the Command window open.

3 Using a text editor that accepts UTF-8 encoding, edit web.xml to configure Visualization Platform client for the application server.

If you used the temporary path in step 2, the file location is C:/Temp/ic/WEB-INF/Web.xml. Refer to Table 2-1 for a list of entries to modify in web.xml.

4 Save and close web.xml.

5 Perform this step only if you are deploying Visualization Platform client using one of the following WAR files:

■ WAS_ActuateBIRTJavaComponent.warFor deploying Visualization Platform client to the IBM WebSphere application server. WAS_ActuateBIRTJavaComponent.ear contains WAS_ActuateBIRTJavaComponent.war.

■ WL_ActuateBIRTJavaComponent.warFor deploying Visualization Platform client to the Oracle WebLogic application server.

Remove the WEB-INF/lib/el-api.jar file from the WAR file if the /lib directory for your application server also contains el-api.jar. The presence of el-api.jar in both the Information Console WEB-INF/lib directory and the application server /lib directory may cause errors.

6 Type the following command:

jar -cf ../newinformationconsole.war *

This command creates newinformationconsole.war in the /temp directory. This new WAR file for Visualization Platform client contains the modified configuration values.

Use newinformationconsole.war to deploy Visualization Platform client to your application server.


About clusters of serversIf the application server supports clustering, see the application server documentation for more information about setting up clusters and deploying web applications such as Visualization Platform client.

Avoiding cache conflicts after installingVisualization Platform client uses Java Server Page (JSP) technology. Application servers and browsers cache pages. A browser can use a cached copy of a page instead of the new page. After you install, using a cached copy of some pages can lead to errors or missing functionality.

To avoid this problem, clear the application server cache after you install Visualization Platform client. With some application servers, you must restart the application server. For more information about the necessary steps for clearing the cache, see the application server documentation.

If possible, also clear the browser cache to ensure that the browser does not use an old copy of the page from its cache. Alternatively, you can refresh recently visited pages or clear the browser cache if a problem occurs. For more information about clearing the browser’s cache and refreshing a page, see the browser documentation.

Testing the installationComplete the steps in the following section to test the Visualization Platform client installation.

How to test the installation

1 Start the Actuate iHub 3 service or the application server and web server, if necessary.

2 To start using Visualization Platform client, type the Visualization Platform client URL into the address bar of your web browser. For example, type a URL similar to the following:

http://Actuate1:8700/iportal/

■ Actuate1:8700 is the name of your computer and the default port to access Visualization Platform client.

■ iportal is the default context root for Visualization Platform client.

The Visualization Platform client login page appears.

3 On the Visualization Platform client login page, type a user name and password.

4 Choose Log In.

C h a p t e r 3 , C o n f i g u r i n g A c t u a t e V i s u a l i z a t i o n P l a t f o r m c l i e n t 25

C h a p t e r

3Chapter 3Configuring Actuate

Visualization Platform clientThis chapter contains the following topics:

■ Visualization Platform client web application structure and contents

■ Configuring a custom Visualization Platform client web application

■ Modifying global style elements

■ Visualization Platform client configuration

■ Visualization Platform client JavaScript reference

■ Using Visualization Platform client Java servlets

■ Visualization Platform client JavaBeans overview


Visualization Platform client web application structure and contents

Actuate Visualization Platform client generates web pages using a set of default JSPs. Visualization Platform client JSPs use cascading style sheets, JavaScript, and custom tags to generate dynamic web page content. The JavaScript and tags provide access to other JSPs, JavaBeans, and Java classes.

The Visualization Platform client web application organizes these inter-operating components into a Model-View-Controller (MVC) architecture. To operate a web application, the MVC components perform the following functions:

■ Model contains the logic for sending requests to and processing responses from the repository. This component is the data model for Visualization Platform client.

■ View contains the pages that display data prepared by actions. This component is the presentation portion of Visualization Platform client.

■ Controller contains the servlets that implement actions. This component is the program control logic for Visualization Platform client and manages actions initiated from the browser.

The controller maps actions, designated by URLs with the .do extension, to an actionServlet. The actionServlet is configured with action paths specified in <Actuate home>\iPortal\iportal\WEB-INF\struts-config.xml.

Typically, an action path leads to a JSP with parameters as a web resource. Visualization Platform client file and directory names are case-sensitive. The first time you use a JSP, your web server compiles it into a servlet. Servlets are compiled Java programs or JSPs that run as part of a network service such as a web server. After compiling a JSP into a servlet, a web server can fulfill subsequent requests quickly, provided that the JSP source does not change between requests.

Users make requests to view the contents of a repository, run and view reports, and so on. Each JSP processes any URL parameters by passing them to JSP tags, including Actuate custom tags or your own custom tags.

You specify the user’s Actuate BIRT iHub System and volume as URL parameters. To specify the locale and time zone to which to connect, use parameter values in a Visualization Platform client request within a URL or by specifying the desired values in the login form. For example, the following URL specifies the en_US locale for U.S. English, and the Pacific standard time for the timezone parameter:

http://localhost:8700/iportal/login.do?locale=en_US&timezone=PST


Visualization Platform client pagesVisualization Platform client uses JSPs and servlets to generate web pages dynamically before sending them to a web browser. The JSPs use custom tags, custom classes, and JavaScript to generate dynamic web page content. The JavaScript, classes, and tags provide access to other pages, JavaBeans, and Java classes. For example, application logic in Visualization Platform client can reside on the web server in a JavaBean.

Web browsers can request a JSP with parameters as a web resource. The first time a web browser requests a page, the page is compiled into a servlet. Servlets are Java programs that run as part of a network service such as a web server. Once a page is compiled, the web server can fulfill subsequent requests quickly, provided that the page source is unchanged since the last request.

The dashboards servlet and JSPs support the dashboards and gadgets interface for Visualization Platform client. The dashboard pages reside in <context root>\dashboard\jsp. To provide dashboard access, enable the BIRT 360 license option.

The filesfolders JSPs and custom tags support accessing repository files and folders. These JSPs and custom tags reside in <context root>\iportal\activePortal\private\filesfolders.

The submit request JSPs and custom tags support submitting new jobs. The submit request JSPs reside in <context root>\iportal\activePortal\private\newrequest. For specific information about running jobs using Visualization Platform client, see Using Visualization Platform.

The options JSPs and custom tags support managing user option settings. The options pages reside in <context root>\iportal\activePortal\private\options.

The viewing JSPs and custom tags support the following functionality, depending on the report type:

■ Searching report data

■ Using a table of contents to navigate through a report

■ Paginating or not paginating a report

■ Fetching reports in supported formats

For specific information about viewing reports using Visualization Platform client, see Using Visualization Platform.

Use the default pages, customize the pages, or create entirely new pages to deploy your reporting web application.


Visualization Platform client directory structureThe Java Server Pages (JSPs) that implement Visualization Platform client URIs are grouped by method into directories under the context root. The context root is the home directory in which a Visualization Platform client web application resides. The default context root for the embedded Visualization Platform client for iHub on Windows systems is <Actuate home>\iHub\servletcontainer\iportal and on UNIX and Linux systems is <Actuate home>/iHub/servletcontainer/iportal. The default context root for a separate Visualization Platform client installation on Windows systems is <Actuate home>\iHub3\modules\BIRTiHub\iHub\web\iportal and on UNIX and Linux systems is <Actuate home>/iHub3/modules/BIRTiHub/iHub/web/iportal. The Visualization Platform client context root name in the web or application server’s configuration file is iportal. Figure 2-1 shows the Visualization Platform client directory structure.

Figure 2-1 Visualization Platform client directory structure

common

dtd

errors

private

viewer

images

common

diagnosis

jobs

newrequest

options

parameters

filesfolders

<iHub home>\web

common

da

iv

filesfolders

requests

viewer

activePortal

common

examples

jsapi

portlets

iportal

sample

options

bizRD

admin

dashboard

downloads

dtd

myfiles

newrequest

temp

js

WEB-INF

birtAdapter

iportal

mobile

jslib common

default

fonts

img


Visualization Platform client URIs convey user requests to Actuate BIRT iHub.

Pages supporting folder navigation and document viewing reside in the <context root>\iportal\myfiles directory. Pages supporting the BIRT Viewer reside in the iv directory, pages serving as templates for other pages reside in the templates directory, and so on. Table 2-1 lists and describes the general iHub2\servletcontainer\iportal or iPortal\iportal directories.

Table 2-1 <Context root> directories

Directory Contents

This directory landing.jsp, the default starting page for accessing Visualization Platform client functionality.

admin UI files for application administration. Do not change.

birtAdapter BIRT Viewer integration files.

bizRD Pages that support Report Studio.

common Common files for the user interface, style, and images.

da BIRT Data Analyzer support files.

dashboard Dashboard support files.

downloads Downloaded files.

dtd Document type definitions.

filesfolders Pages that support working with files and folders.

images Visualization Platform client user interface images and icons.

iportal The Visualization Platform client application internals.

iv Pages that support BIRT Interactive Viewer.

js JavaScript files that control specific web page elements such as search, toolbar, and table of contents.

META-INF The Visualization Platform client manifest file. iHub embedded InfoConsole directory.

myfiles Files for listing repository content controlled by myfiles.jsp.

newrequest Pages that support new requests, such as parameter processing, scheduling, and job status pages.

options Options-specific pages, such as notification pages.

requests Pages in this directory provide backward compatibility for custom web applications referencing these pages by URL. Use the action paths and the private\jobs directory for new customization projects.

(continues)


Table 2-2 lists and describes the directories in the common/jslib/common path.

Table 2-3 lists and describes the iportal directories.

Table 2-4 lists and describes the <context root>\iportal\activePortal directories.

temp Working directory for transient content.

viewer Pages that support legacy report viewing.

WEB-INF Files that manage session information such as current user login, roles, and volume.

Table 2-2 <Context root>/common/jslib/common directories

Directory Contents

default Style sheets for most pages in the Visualization Platform client

font Font definition files.

img Icon, button, and logo files.

Table 2-3 <Context root>/iportal directories

Directory Contents

activePortal Pages that support login and authentication and directories for the remaining pages

common Common elements included in the common template.

jsapi JavaScript pages to support the JavaScript API demonstration page

Table 2-4 <Context root>/iportal/activePortal directories

Directory Contents

This directory Pages that support login and authentication and directories for the remaining folder and document pages for the Visualization Platform client application.

common Common elements included in all reporting web pages, such as banner and side menu elements.

dtd Document type definitions.

errors Error pages.

Table 2-1 <Context root> directories (continued)

Directory Contents


Configuring a custom Visualization Platform client web application

Visualization Platform client’s configuration determines many of its essential methods. Configuring your web application customizes how it operates internally, and affects the user’s experience. Perform cosmetic customization tasks using the Visualization Platform client style sheets, as described in “Modifying global style elements,” later in this chapter.

Set configuration parameters for the Visualization Platform client application to tune performance and to control service and application execution. For example, you can perform the following tasks using configuration parameters:

■ Setting the default locale

■ Controlling the Message Distribution service load balancing

images Images for reporting web pages, such as buttons, icons, lines, and arrows.

private Most Visualization Platform client folders and documents web pages. Users cannot directly access pages in this directory using URLs. These pages are customizable.

private\common

Common elements included in all reporting web pages, such as banner and side menu elements.

private\diagnosis

Self-diagnostic utility page.

private\filesfolders

Pages that support working with files and folders.

private\jobs Pages that support requests such as completed requests, successful submission, and details pages by redirecting.

private\mobile Pages that support BIRT Mobile subscriptions.

private\newrequest

Pages that support new requests, such as parameter processing, scheduling, and job status pages.

private\parameters

Pages that support table parameters.

private\sample Example custom requester page.

viewer Pages that support report viewing.

Table 2-4 <Context root>/iportal/activePortal directories

Directory Contents


Configure the Visualization Platform client application by changing configuration file contents, such as web.xml. The following section describes the customization procedure using the text editor.

How to customize Visualization Platform client configuration parameters

Use the following procedure to customize configuration parameters for Visualization Platform client. In this procedure, it is assumed that <context root>\WEB-INF\web.xml is the configuration file.

1 Make a backup copy of web.xml.

2 Using a text editor that supports UTF-8 encoding, edit web.xml to change parameter values. Parameter definitions use the following format:

<param-name><keyword></param-name><param-value><value></param-value>

■ <keyword> is the name of the parameter.

■ <value> is the parameter value.

Do not enclose the keyword and value within quotes, and use no spaces between <param-name>, the keyword or value, and </param-name>. For example, the definition for the default locale parameter is:

<param-name>DEFAULT_LOCALE</param-name><param-value>en_US</param-value>

3 Save web.xml.

4 Restart the application server or servlet engine that runs Visualization Platform client and clear your browser cache.

Setting the default localeThe default locale and time zone for Visualization Platform client are set when you install it. To change the default settings, you modify the values of the DEFAULT_LOCALE and DEFAULT_TIMEZONE configuration parameters.

How to set a default Visualization Platform client locale and time zone

1 Using a UTF-8 compliant code editor, open the web.xml configuration file.

2 Navigate to the lines that define DEFAULT_LOCALE, similar to the following code:

<param-name>DEFAULT_LOCALE</param-name><param-value>en_US</param-value>

Change the current locale id, en_US in the above example, to the desired locale id in param-value. Valid locale id strings are listed in <context root>\WEB-INF\localemap.xml.


3 Navigate to the lines that define DEFAULT_TIMEZONE, similar to the following code:

<param-name>DEFAULT_TIMEZONE</param-name><param-value>America/Los_Angeles</param-value>

Change the current time zone id, Pacific Standard Time in the above example, to the desired default time-zone in param-value. Valid time zone id strings are listed in <context root>\WEB-INF\TimeZones.xml.

4 Save web.xml.


6 Open the Visualization Platform client web application. The login page for the custom application appears.

Controlling the Message Distribution service load balancingThe default load balancing for Visualization Platform client are set to when you install it. To change the default settings, you modify the values of the MDS_ENABLED and MDS_REFRESH_FREQUENCY_SECONDS configuration parameters.

If you are using third-party load balancing, you will need to refer to their documentation to configure load balancing. See “Visualization Platform client load balancing” in Chapter 1, “Understanding Visualization Platform clients.”

How to enable the Message Distribution service

The Message Distribution service (MDS) is enabled by default. This procedure assumes it has been disabled.

1 Using a UTF-8 compliant code editor, open the web.xml configuration file.

2 Navigate to the lines that define MDS_ENABLED, similar to the following code:

<param-name>MDS_ENABLED</param-name><param-value>false</param-value>

Change the current value, if it is false, to true.

3 Navigate to the lines that define MDS_REFRESH_FREQUENCY_SECONDS, similar to the following code:

<param-name>MDS_REFRESH_FREQUENCY_SECONDS</param-name><param-value>0</param-value>


Change the current refresh frequency in seconds, 0 in the above example, to the desired number of seconds so that MDS will attempt to discover new nodes added to the cluster or remove nodes dropped from the cluster.

4 Save web.xml.


Setting the JavaScript MIME types for Apache TomcatApache Tomcat 6.0.39 or newer requires a text MIME type for the JavaScript mime-mapping configuration for Visualization Platform and iHub to support the Actuate JavaScript API.

How to change the mime-mapping configuration for Visualization Platform

1 Navigate to the following directory:

~\Actuate\iHub3\modules\BIRTiHub\iHub\web\iportal\WEB-INF

2 Open web.xml for editing and navigate to the mime-mapping section shown in Listing 2-1:

Listing 2-1 mime-mapping in web.xml for Visualization Platform

<mime-mapping><extension>js</extension><mime-type>application/javascript</mime-type>

</mime-mapping>

3 Change the value of the mime-type parameter to the following:<mime-type>text/javascript</mime-type>

4 Save and close web.xml

5 Restart the Actuate iHub 3 Service

For more information about BIRT iHub Visualization Platform web.xml configuration, see Managing iHub Client Applications.

Configuring connections to iHub using volumeProfile.xmlTo include a Visualization Platform installation in an iHub cluster, register the Visualization Platform as a service provider. However, you can also configure the Visualization Platform to access any specific iHub instance and volume by configuring a connection in the volume profile. Because the volume profile conceals the iHub and volume values from the users of Visualization Platform, the system administrator can change the location of these resources without


affecting the URLs accessed by the users. To access iHub resources using a volume profile, add a __vp=ProfileName parameter to the URL.

Customize volume profiles by creating or modifying entries in the following file:

<context root>\WEB-INF\volumeProfile.xml

For example, the following is a volume profile definition for the server1 server:

<VolumeProfiles><Profile>

<Default>true</Default><ProfileName>server1</ProfileName><RepositoryType>enterprise</RepositoryType><ServerUrl>http://server1:8000</ServerUrl><Volume>volume1</Volume><DashboardTemplatePath></DashboardTemplatePath>

</Profile></VolumeProfiles>

■ <ProfileName> is the name of this profile.

■ <RepositoryType> has one of two values, either enterprise or workgroup.

■ <ServerUrl> contains the iHub URL, for example, http://server1:8000. If RepositoryType is workgroup, ServerUrl is ignored.

■ <volume> is the volume name. If RepositoryType is workgroup, volume is ignored.

■ <Default> is optional. Valid values are true and false. A value of true sets this profile as the default volume profile, and the server and volume in this profile is used if no volume profile is provided in the URL. Visualization Platform handles only the first profile with default set to true as the default profile.

■ <DashboardTemplatePath> is optional. This repository path is the location of the dashboard file that loads when a user creates a new dashboards.

To make a new profile available to Visualization Platform, add a new <Profile> element to the list in <VolumeProfiles> in volumeProfile.xml. Then, restart Visualization Platform. For example, the following profile accesses the volume2 volume on the server2 server:

<Profile><Default>false</Default><ProfileName>server2</ProfileName><RepositoryType>enterprise</RepositoryType><ServerUrl>http://server2:8000</ServerUrl><Volume>volume2</Volume><DashboardTemplatePath></DashboardTemplatePath>

</Profile>


Using a volume profile defined in volumeProfile.xmlVisualization Platform connects to the server and volume defined by the default volume profile entry when the URL does not include the __vp parameter or the volume parameter. For example, to connect to the default volume and server, use the following URL:

http://infoconsole:8900/iportal/getfolderitems.do?userid=userName&password=validPassword

Visualization Platform connects to the server and volume defined by a volume profile when the URL contains a __vp parameter with a valid profile name and the URL does not have a volume parameter. For example, to connect to volume2 on server2 defined by the volume profile example above, use the following URL:

http://infoconsole:8900/iportal/getfolderitems.do?userid=userName&password=validPassword&__vp=server2

Overriding the volume specified in a volume profileVisualization Platform supports using a volume profile to access a volume even if the volume is not specified in a volume profile definition. To override the volume specified by a volume profile, add the volume parameter to the URL. A URL with a valid __vp parameter and volume parameter connects to the server in the volume profile, but the volume assigned to the volume parameter. For example, to connect to volume3 on server2 explicitly, use the following URL:

http://infoconsole:8900/iportal/getfolderitems.do?userid=userName&password=validPassword&__vp=server2&volume=volume3

If the URL contains a volume parameter but not a __vp parameter, Visualization Platform connects to the server in the default volume profile and the volume assigned to the volume parameter. For example, to connect to volume3 on the default server, use the following URL:

http://infoconsole:8900/getfolderitems.do?userid=userName&password=validPassword&volume=volume3

Understanding temporary volume profilesIf a request URL contains serverurl, repositorytype, or volume parameters not defined in volumeProfile.xml, Visualization Platform generates a temporary profile name for this set of volume properties. A temporary name is not persistent and is lost every time the application restarts. If the request URL does not contain serverurl, volume, and repositorytype parameters, Visualization Platform uses the default profile for the request URL. If there is no default profile defined, Visualization Platform generates a temporary server profile having a random name and uses SERVER_DEFAULT, DEFAULT_VOLUME, and REPOSITORY_TYPE defined in WEB-INF/web.xml as the default values for serverurl, volume, and repositorytype.


Modifying global style elementsAlthough JSPs can use HTML to set colors, fonts, and other stylistic elements directly, the JSPs also use cascading style sheets (CSS), templates, and shared images to control the global styles of a Visualization Platform client web application. To modify the appearance of the entire Visualization Platform client web application, change global style elements.

Global style definitions are located in the <context root>\common\jslib\themes\default\yggdrasil.css file. To change the company logo displayed in the banner, modify the background:url property of the .ac .navbar .actuate class definition. This class definition in yggdrasil.css includes other properties, as shown in the following code:

.ac .navbar .actuate { text-indent: -9876px; outline: none; float: left; display: block; margin: 12px 0px 0px 0px; padding-right: 11px; background: url(../img/actuate_logo_navbar.png) no-repeat; width: 98px; height: 25px; border-right: #555 1px solid;}

To change the logo, replace the default value of actuate_logo_navbar.png with a custom logo file name, either as an absolute path, or as the same relative path as the default image by saving the image file in the <context root>\common\jslib\themes\img directory.


To change the background color or height of the top navigation bar, modify the value of the .ac .navbar-inner class definition.This class definition in yggdrasil.css includes other properties, which is shown in the following code:

.ac .navbar-inner { position: relative; height: 43px; padding-left: 15px; padding-right: 0px; background: #363636; -webkit-box-shadow: 0px 3px 3px rgba(0, 0, 0, 0.125); -moz-box-shadow: 0px 3px 3px rgba(0, 0, 0, 0.125); box-shadow: 0px 3px 3px rgba(0, 0, 0, 0.125); border-bottom: #222222 1px solid; z-index: 100; *zoom: 1;}

Replace the default value of the height parameter to change the height of the top navigation bar and change the value of the background parameter to change the color of the top navigation bar.

How to customize the company logo and banner color

1 Copy your custom logo image file to the following directory:

<context root>\common\jslib\themes\img

2 Open the yggdrasil.css file for editing.

3 Navigate to the following lines:

background: url(../img/actuate_logo_navbar.png) no-repeat;width: 98px;height: 25px;

4 Change the filename of the background image to the name of custom logo image file and change the width and height dimensions to match the custom image dimensions. For example, if the custom image file was called examplecorp_logo.gif and it had a height of 153 pixels and a width of 37 pixels, you would use the following entry:

background: url(../img/ExampleCorp_logo.gif) no-repeat;width: 153px;height: 37px;


5 Navigate to the following lines:

.ac .navbar-inner { position: relative; height: 43px; padding-left: 15px; padding-right: 0px; background: #363636;

6 Change the value of the height and the background to complement the custom logo. For example, if the custom logo has a yellow background and requires 60 pixels of height with its padding to be centered vertically on the navigation bar, you would use the following entry:

.ac .navbar-inner { position: relative; height: 60px; padding-left: 15px; padding-right: 0px; background: #FFFF00;

7 Save web.xml. Then, restart the Actuate iHub 3 Service to apply the changes.

1 Choose Start➛Control Panel. Open Administrative Tools.

2 In Administrative Tools, choose Services.

3 In Services, select Actuate iHub 3 Service and choose Restart.

8 Open the Visualization Platform client application in a web browser to view the new custom navigation bar. For example, if you followed the above steps for examplecorp_logo.png image, your landing page would appear as shown in Figure 2-2.

Figure 2-2 Viewing a custom logo and banner in Visualization Platform client


Visualization Platform client configurationThe Visualization Platform client application is configured using files in the context root’s WEB-INF directory. For example, the web.xml configuration file for your context root is located:

<context root>\WEB-INF\web.xml

Table 2-5 lists the configuration files discussed in this chapter.

Configuring Visualization Platform client using web.xmlWeb.xml contains parameters that control Visualization Platform client features. Table 2-6 describes the configuration parameters for the Visualization Platform client application.

Table 2-5 Visualization Platform client configuration files

File Features Description

erni_config.xml BIRT Studio Configures BIRT Studio functionality

functionality-level.config Visualization Platform client

Configures the Visualization Platform client user interface by iHub user groups

iv_config.xml BIRT Viewer Configures BIRT Viewer user interface

localemap.xml All Configures languages and locales

TimeZones.xml All Configures time zones

web.xml All Configures features of Visualization Platform client including security, networking, caching, labeling and storage

Table 2-6 Visualization Platform client web.xml parameters

Parameter name Description

BIRT360PLUS_URL URL for the BIRT 360 Plus web resources required for performance analytics gadgets, available in the gadget gallery.


BIRT_RENDER_FORMAT_EMITTER_ID_MAPPING

Specifies which emitter will be used for a specific BIRT report. Valid entries are of the format "render_format:emitter_ID" separated by a semicolon. The default value is:html:org.eclipse.birt.report.engine.emitter.html;xhtml:com. actuate.birt.report.engine.emitter.xhtml;pdf:org.eclipse.birt.report.engine.emitter.pdf;postscript:org.eclipse.birt.report.engine.emitter.postscript;xls:com.actuate.birt.report.engine.emitter.xls;ppt:org.eclipse.birt.report.engine.emitter.ppt;pptx:com.actuate.birt.report.engine.emitter.pptx;doc:org.eclipse.birt.report.engine.emitter.word;docx:com.actuate.birt.report.engine.emitter.docx

CACHE_CONTROL Specifies how a web browser caches information using one of the following values:■ NO-CACHE indicates that the browser does not cache

information and forwards all requests to the server. With NO-CACHE, the back and forward buttons in a browser do not always produce expected results, because choosing these buttons always reloads the page from the server.If multiple users access Visualization Platform client from the same machine, they can view the same cached data. Setting CACHE_CONTROL to NO-CACHE prevents different users viewing data cached by the browser.

■ NO-STORE indicates that information is cached but not archived.

■ PRIVATE indicates that the information is for a single user and that only a private cache can cache this information. A proxy server does not cache a page with this setting.

■ PUBLIC indicates that information may be cached, even if it would normally be non-cacheable or cacheable only within an unshared cache.

■ Unset (no value) is the default value. The browser uses its own default setting when there is no CACHE_CONTROL value.

Caching information reduces the number of server requests that the browser must make and the frequency of expired page messages. Caching increases security risks because of the availability of information in the cache. For additional information about cache control, see the HTTP/1.1 specifications.

CONNECTION_TIMEOUT

Controls how many seconds Visualization Platform client waits for a request to complete before dropping the connection to the application server or BIRT iHub. Set this value to limit wait times. The default value is 0, meaning the connection is never dropped.

Table 2-6 Visualization Platform client web.xml parameters (continued)



COOKIE_DOMAIN Specifies the host name of the server setting the cookie. The cookie is only sent to hosts in the specified domain of that host. The value must be the same domain the client accesses. Visualization Platform client automatically sets this parameter. For example, if the client accesses http://www.actuate.com/iportal/login.do, the domain name is actuate.com.

COOKIE_ENABLED Indicates whether to use cookies to store information between user logins. The default value is True. If False, Visualization Platform client does not use cookies. Without cookies, many Visualization Platform client features are unavailable or do not persist across sessions. For example, without cookies, user name, language, and time zone settings always use their default values when a new browser session begins.

COOKIE_HTTPONLY Sets the HTTPonly property of cookie stored by Visualization Platform client. In supported browsers, this property prevents third-party scripts from accessing cookies generated by Visualization Platform client. The default value is true, which enables the HTTPOnly flag.

COOKIE_SECURE Indicates whether to access and write cookies securely. If true, cookies are only written if a secure connection, such as HTTPS, is established. The default value is false, which enables cookies for all connection types.

DATAFIELDS_DISPLAY_ORDER

Specifies display order of Fields and Folders. Default value is "ascending". Valid values are: "ascending", "descending", "none".

DEFAULT_LOCALE Specifies the default locale. Visualization Platform client sets this parameter value during installation. The locale map is <context root>\WEB-INF\localemap.xml.

DEFAULT_PAGE_BREAK_INTERVAL

Specifies the number of rows to display in one page when viewing a report. If set to 0, there are no page breaks.

DEFAULT_TIMEZONE Specifies the default time zone. Visualization Platform client sets this parameter value during installation. The time zone map is <context root>\WEB-INF\TimeZones.xml.

ENABLE_CLIENT_SIDE_REDIRECT

Specifies whether URL redirection is done on the client side or the server side. Set the value to True for client side redirection. The default value is False. For more information about URL redirection, see “Using proxy servers with Visualization Platform client” in Chapter 1, “Understanding Visualization Platform clients.”

(continues)




ENABLE_DEBUG_LOGGING

Indicates whether to record debugging messages in a log file called Debug.log. Set the value to True to enable debug messages in the log file. The default value is False.

ENABLE_ERROR_LOGGING

Indicates whether to log errors. This parameter’s default value is True, which enables error logging. If you set this parameter to True, Visualization Platform client creates two error log files:■ Admin.log records general errors.■ Soapfault.log records iHub communication errors.

ENABLE_JUL_LOG Indicates whether to log Visualization Platform client activity. This parameter’s default value is TRUE, which enables logging. If you set this parameter to TRUE, Visualization Platform client creates log files named reportService.<Service number>.<System name>.<Visualization Platform client start up time stamp>.<File number>.log.

ERROR_LOG_FILE_ROLLOVER

Specifies the time period to wait before starting a new log file. Options are Daily, Monthly, Weekly, and Yearly. The default value is Monthly.

EXECUTE_DASHBOARD_GADGET_GENERATION_WAIT_TIME

Specifies the time to wait, in seconds, for a gadget to generate when running a dashboard design file. This parameter’s default value is 2 seconds.

EXECUTE_REPORT_WAIT_TIME

Specifies the time to wait, in seconds, for a report to execute. This parameter’s default value is 20 seconds. For more information about the wait time parameter, see Integrating Applications into BIRT iHub.

FORCED_GC_INTERVAL

Indicates the length in seconds of the interval that the Visualization Platform client application waits between forced garbage collections. To disable garbage collection, set this parameter to 0, the default value. Use this parameter to tune application server performance. 600 seconds is the recommended value. If the value is too low, the application server performs garbage collection too frequently, slowing the system. If the value is too high, you waste memory. If disabled, the application server controls garbage collection.

GADGET_GENERATION_WAITING_TIME

Specifies the time to wait, in seconds, for an individual gadget to generate. This parameter’s default value is 10 seconds.




IDAPI_TIMEOUT Specifies the number of seconds to wait for a SOAP message response. This value must be larger than the maximum time necessary to run a report design or Visualization Platform client generates a time-out error for some reports. Its default value is 7200.

INSTALL_MODE Indicates whether Visualization Platform client is installed with iHub. The value is set when Visualization Platform client is installed. Do not change this setting.

JUL_LOG_CONSOLE_LEVEL

The level of Visualization Platform client activity to log to the console. Valid values are OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, in order of the number of messages to log. The default value is OFF.

JUL_LOG_FILE_COUNT

Specifies the number of log files for a particular time stamp, if the value of ENABLE_JUL_LOG is TRUE.

JUL_LOG_FILE_LEVEL

The level of Visualization Platform client activity to log in a file. Valid values are OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, in order of the number of messages to log. The default value is WARNING.

JUL_LOG_FILE_SIZE_KB

The maximum size, in kilobytes, for a Visualization Platform client activity log file. When a log file reaches this size, Visualization Platform client creates a new log file and increments its file number. If the log file number reaches the value of JUL_LOG_FILE_COUNT, Visualization Platform client resets the file number to zero and overwrites the first log file for the time stamp.

LOG_FILE_LOCATION

Indicates which directory contains the log files. If the value is not an absolute directory path name, Visualization Platform client locates the directory in the Visualization Platform client home directory. The default value is logs in the Visualization Platform client home directory.

LOGIN_TIMEOUT Specifies the number of seconds to wait before a session times out. The minimum login time-out is 300 seconds. The maximum value is equivalent to java.lang.Long. Its default value is 1200 seconds.

MAX_BACKUP_ERROR_LOGS

Specifies the maximum number of backup error log files to keep. The default value is 10.

MAX_LIST_SIZE Limits the number of items returned when getting folder items, jobs, job notices, scheduled jobs, and subscriptions to reduce network traffic. The default value is 150.




MOBILE_APP_DOWNLOAD

The URL target of the download button displayed by Visualization Platform client when viewed in mobile/touch device.

(continues)

PROGRESSIVE_REFRESH

Controls the interval in seconds at which an Actuate report refreshes itself when running a progressive report. The report refreshes first after 15 seconds, then after 60 seconds, and then after the PROGRESSIVE_REFRESH interval. If the value is less than 60, Visualization Platform client uses 60 seconds. This parameter’s default value is 1800 seconds.

PROGRESSIVE_VIEWING_ENABLED

Specifies whether a paginated report starts to display in the browser as soon as the first page has been generated. Valid values are true and false. The default value is true.

PROXY_BASEURL Indicates a proxy server’s URL if the network uses one between Visualization Platform client and the client. The default value is blank, which indicates that the network does not use a proxy server.

REDIRECT_TO_OUTSIDE_DOMAIN

Specifies whether an outside domain is a legal value for the targetpage URL parameter. If set to false, targetpage cannot redirect traffic to any outside domain. The default value is false.

SECURITY_ADAPTER_CLASS

Specifies the fully qualified class of the security adapter, which must extend com.actuate.iportal.security.iPortalSecurityAdapter, that controls access to Visualization Platform client functionality. The default value is no name.

SESSION_DEFAULT_PARAMETER_VALUE_ID

Specifies the name of the object that stores the HTTP session-level report parameters. This object is an instance of the com.actuate.parameter.SessionLevelParameter class, which is extensible. The default value is SessionDefaultParameterValue.

sessionTimeout The number of milliseconds the Visualization Platform client Ajax Proxy maintains an idle session. The default value is 5000.

TRANSIENT_STORE_MAX_SIZE_KB

Limits the amount of disk space that Visualization Platform client uses for temporary files. The default value is 102400, which is 100 MB.

TRANSIENT_STORE_PATH

Path to Visualization Platform client transient files. The default value is set when Visualization Platform client is installed. When deploying more than one context root or separate server, set a unique path for each.

TRANSIENT_STORE_TIMEOUT_MIN

Specifies, in minutes, how long to retain Visualization Platform client transient files. The default value is 40, which is 40 minutes.




iHub Visualization Platform client can use a volume profile to access a specific iHub instance and volume when it is not part of the iHub cluster. Because the volume profile conceals the iHub and volume values from the users of iHub Visualization Platform client, the system administrator can change the location of these resources without affecting the URLs accessed by the users. To access iHub resources using a volume profile, add a __vp=ProfileName parameter to the URL.

Configuring locales<context root>\WEB-INF\localemap.xml contains the locales available to Visualization Platform client. Add locales to this file using the same format as the existing locales. To see each locale in the file, search for one of the following strings:

<Locale

or:

<DisplayName>

Searching for <Locale places the cursor on the line having the ID for the locale. Searching for <DisplayName> places the cursor on the line having the descriptive name for the locale.

Typically, the locale names have the following syntax:

<language>_<country>

For example, ar_EG is Arabic (Egypt). A language spoken in multiple countries has multiple locale names for which the language code is the same and the country code has several values. For example, en_US is the locale for English (United States), en_AU is the locale for English (Australia), and en_BZ is the locale for English (Belize). Some countries have several locales, one for each language. For example, Canada has both en_CA for English (Canada) and fr_CA for French (Canada). You specify a default locale for a custom web application in <context root>\WEB-INF\web.xml.

UPLOAD_FILE_TYPE_LIST

Specifies the valid file types, by extension, for upload with Visualization Platform client. The default value is blank, which indicates any file type.

UPLOAD_SECURITY_MANAGER

Specifies the fully qualified class of the security adapter, which must extend com.actuate.iportal.security.IUploadSecurityAdapter, that controls access to the upload functionality. The default value is no name.




Configuring time zones<context root>\WEB-INF\TimeZones.xml contains the time zones available to Visualization Platform client. Add time zones to this file by using the same format as the existing time zones. To see each time zone in the file, search for one of the following strings:

<TimeZone

or:

<DisplayName>

Searching for <TimeZone places the cursor on the line having the ID for the time zone. Searching for <DisplayName> places the cursor on the line having the descriptive name for the time zone.

Some time zone names have short abbreviations for the ID. All time zone names have a full descriptive ID, such as Samoa Standard Time or Greenwich Standard Time. The DisplayName provides the relative time from Greenwich Standard Time and one or more locations that the time zone includes. You specify a default time zone for a custom web application in <context root>\WEB-INF\web.xml.

Customizing messages and text according to localeError messages and text for Visualization Platform client are encoded in resource files compressed in the <context root>/WEB-INF/lib/resources.jar file. The properties files contain entries for the interface text and error codes Visualization Platform client generates.

For reference, the <context root>/WEB-INF/ErrorMessage.txt file lists the default error codes used by Visualization Platform client. The \com\actuate\reportcast\resources\ErrorMessages.properties file within the resources.jar archive contains error messages for the default locale. Visualization Platform client uses messages from this file if no locale-specific message for the error exists. Not all of the codes exist in the default ErrorMessages.properties because iHub directly generates many of them in the SOAP messages sent to Visualization Platform client.

Override iHub and Visualization Platform client messages using a locale-specific error messages file. In addition to the default ErrorMessages.properties file, Visualization Platform client provides several localized error message files, such as ErrorMessages_de_DE.properties. This file contains the German language messages for the Germany locale. To specify error messages to a certain locale, modify the existing error message file for that locale or create a new file for the locale. By convention, the format of a locale-specific error message file name includes the language and locale codes at the end of the file name separated by underscore characters.


For example:

ErrorMessages_de_DE.properties

■ de is the language code for German.

■ DE is the Germany country code.

These values for language and locale codes are defined in localemap.xml.

Because alphabets for different languages are dissimilar and Visualization Platform client uses ASCII encoding for these files, you must convert new or edited files into ASCII format. To convert the files to ASCII, modify the properties file using an editor that saves to the UTF-8 format and convert the file to ASCII using the Java native2ascii utility using the -encoding UTF-8 switch. The native2ascii utility installs with any Java Developer Kit in the <JDK home>/bin directory. Model the format of new messages after those in the ErrorMessage.properties file.

When your modifications are complete, recompress the resources.jar archive using the Java jar utility, retaining the original directory structure for the archive. Copy the new resources.jar file to the <context root>/WEB-INF/lib directory, restart the Actuate 11 Apache Tomcat for Visualization Platform client service, and log in using the locale for the modified messages file. Confirm that the new messages file was loaded by examining the error messages generated by Visualization Platform client using that specific locale.

Error messages appear in pop-up windows when an error is encountered. The window is an operating system window, not an HTML frame. If you use a language-specific version of Windows corresponding to the locale you are viewing, the localized message shows up correctly. If you have not loaded the Windows language pack for a language, the text of a message appears as empty squares instead of text.

Configuring the connection to iHub ServerVisualization Platform client provides the ability to connect to iHub Server, a volume, and manage reports on remote systems. Configure the repository, network, and Message Distribution service for Visualization Platform client using parameters in web.xml. These parameters control Visualization Platform client’s connection to iHub and the volume. Table 2-7 describes the configuration parameters for networking with iHub.

Table 2-7 iHub connection web.xml parameters


AUTO_SAVE_DASHBOARD_DELAY

Controls how long, in seconds, the dashboard engine should wait before sending a save message to persist the personal dashboard file. To disable auto save, set this value to 0.


DASHBOARD_SHARED_RESOURCES

Specifies the path for the shared dashboard and gadget resources on the volume. The gadget gallery displays the contents of this folder under the shared folder and is the default location when sharing dashboards.

MAX_CONNECTIONS_PER_SERVER

Indicates the maximum number of Visualization Platform client connections to BIRT iHub. Actuate pools connections to increase efficiency. Choose a number of connections that satisfies the most requests concurrently without requiring an unreasonable amount of memory. Begin with a value equal to the number of threads available in your application server. The value for this parameter must be greater than 0. The default value is 150.

MDS_ENABLED Indicates whether to enable the Message Distribution service. The default value is True, which enables the Message Distribution service. For more information about the Message Distribution service, see “Visualization Platform client load balancing” in Chapter 1, “Understanding Visualization Platform clients.”

MDS_REFRESH_FREQUENCY_SECONDS

Indicates, in seconds, how quickly Visualization Platform client detects an offline or new node in a cluster. If MDS_ENABLED is True, Visualization Platform client refreshes the list of available nodes from BIRT iHub at the time interval specified. The default value is 300 seconds.

(continues)

REPOSITORY_CACHE_TIMEOUT_SEC

Specifies how long a repository cache remains valid. When the cache becomes invalid, any user actions refresh the cache for the time-out duration. The default value is 900 seconds.

SERVER_QUERY_TIMEOUT

Specifies how long iHub Visualization Platform client waits for a response before the socket times out for the BIRT iHub connection. Its default value is eight seconds.


Specifies the directory Visualization Platform client uses to temporarily store files from a volume if viewing the file requires a location on the web server. If the value is not an absolute directory path name, Visualization Platform client locates the directory in the Visualization Platform client home directory. The default value is temp in the Visualization Platform client home directory. The Visualization Platform client user must have write permission for the directory. When deploying more than one Visualization Platform client application instance or context root on the same machine, you must set a unique path for each.

Table 2-7 iHub connection web.xml parameters (continued)



Restricting access to Actuate Visualization Platform client features using functionality levelsActuate Visualization Platform client provides functionality levels that control which features are available to a user. By default, each user can access all of the functionality level features. To restrict access to features for user groups, the Actuate Visualization Platform client administrator can modify functionality levels and add additional levels by editing the configuration file. The standard location for the Actuate Visualization Platform client configuration file is <context root>\WEB-INF\functionality-level.config.

When configuring security roles, make sure that any roles specified in the configuration file also exist in the volume. Because all users automatically belong to the All security role, all users receive the functionality associated with the Basic or the Open functionality level plus the functionality associated with any other roles they have. When restricting access to features, remove the feature from the Open functionality level or comment out the Open level completely and use the Basic functionality level. Understanding the provided functionality levels.

There are four default functionality levels provided in comments. When the comment tags are removed, the provided functionality levels give the following access.

Users with the Basic level can perform the following tasks:

■ Access Documents and Job history

■ Delete their own files.

Basic level users cannot perform any other modifications.

Users at the Intermediate level have all the Basic level access, and can also perform the following tasks:

■ Search documents.

■ Create their own job notifications with attachments.

■ Upload and download files.

■ Use the interactive viewer, if this option is licensed.

Users at the Advanced level have all the Intermediate level access, plus they can perform the following tasks:

■ Create and delete folders.

VOLUME_PROFILE_LOCATION

Path to the volume profile configuration file from the context root. Default value is /WEB-INF/VolumeProfile.xml.

Table 2-7 iHub connection web.xml parameters (continued)



■ Share files and folders.

■ Set job priority.

Users at the Administrator level can perform all Advanced level tasks.

Use Actuate iHub Visualization Platform client configuration to associate the levels with users in the volume by assigning the appropriate roles to each user.

Customizing functionality levelsCustomize or add functionality levels by modifying or creating a level definition in functionality-level.config. A functionality level definition consists of five parts:

■ Level nameThe level name must be a unique alphanumeric string, enclosed within <Name> and </Name> tags.

■ Matching security roleThe name of the security role that corresponds to the functionality level. Both the security level and the functionality level must exist before the functionality level can be assigned to a user. Enclose the role name with <Role> and </Role> tags.

■ Available featuresTable 2-8 describes the five available features.

Features are specified one per line and are enclosed within <FeatureID> and </FeatureID> tags. When a feature is omitted from a functionality level, the corresponding side menu or banner item is hidden to anyone assigned that functionality level. For example, the Search feature is not provided in the Basic functionality level, so the Search link does not appear for users with the Basic functionality level.

■ Available subfeaturesSubfeatures correspond to actions that you can perform through Actuate Visualization Platform client. Most subfeatures are associated with a feature. A subfeature cannot be included in a functionality level if its corresponding

Table 2-8 Features for functionality levels

Feature Description

Documents Provides access to files and folders

Jobs Allows submitting and accessing jobs

Mobile Provides access to BIRT mobile viewing

Search Provides access to the file search facility


feature is not included. The subfeatures are described in Table 2-9.

Subfeatures are specified one per line, enclosed within <SubfeatureID> and </SubfeatureID> tags.

Table 2-9 Subfeatures for functionality levels

Subfeature Feature Description

AddFile Documents Permits adding files when the user has the appropriate privileges

AdvancedData NA Permits the modifying and synchronizing of data sets in BIRT Studio

CreateFolder Documents Permits creating folders when the user has the appropriate privileges

DashboardBusinessUser

NA Permits use of dashboards

DashboardDeveloper

NA Permits design and administration of dashboards

DeleteFile Documents Permits deleting files when the user has the appropriate privileges

DeleteFolder Documents Permits deleting folders when the user has the appropriate privileges

DownloadFile Documents Permits downloading files when the user has the appropriate privileges

InteractiveViewing NA Permits opening Interactive Viewer

JobPriority Jobs Permits setting job priority, up to the user’s maximum job priority

SelfNotificationWithAttachment

Jobs Activates e-mail notification for successful jobs

ShareDashboard NA Permits sharing dashboards when the user has the appropriate privileges

ShareFile Documents Permits sharing files when the user has the appropriate privileges


The following code shows a sample functionality level entry:

<Level><Name>ViewAndSearch</Name><Role>All</Role><FeatureID>Jobs</FeatureID><FeatureID>Documents</FeatureID><FeatureID>Search</FeatureID><SubfeatureID>ShareFile</SubfeatureID><SubfeatureID>DeleteFile</SubfeatureID>

</Level>

The level is named ViewAndSearch and is available to all security roles. Users with ViewAndSearch functionality can run jobs, access documents, and search for files. In addition, they can share and delete their own files.

Preserving functionality levels and featuresThe functionality-levels.config file is overwritten during upgrade installations. This change ensures that new levels, features, and subfeatures are available to you with your new Actuate Visualization Platform client installation. If you have modified your existing functionality-level.config file, make a backup of the changes before the upgrade. Use the backed-up file to access your changes and merge them into the new functionality-level.config file.

Visualization Platform client JavaScript referenceThis section describes the Visualization Platform client JavaScript files. Visualization Platform client JavaScript files provide functionality and dynamic content to Visualization Platform client web applications. Visualization Platform client JavaScript files reside in <context root>\iportal\js.

Table 2-10 lists and describes the Visualization Platform client JavaScript files.

Table 2-10 Visualization Platform client JavaScript files

Name Description

allscripts.js Defines global variables, resources, and common methods such as deleteFile and viewActiveRequests

array.js Contains functionality for handling arrays and array elements

browsertype.js Determines the web browser in use and provides functionality appropriate to the browser, such as opening a file in a new window and capturing a keystroke event


Using Visualization Platform client Java servletsJava servlets extend web server functionality. Visualization Platform client uses Java servlets to manage binary content and to perform tasks such as uploading and downloading binary files. Actuate provides an abstract framework of servlets that provide common functionality to Visualization Platform client. You cannot modify the Actuate Java servlets.

base servletSome Actuate servlets derive from the base servlet:

com.actuate.reportcast.servlets.AcServlet

The base servlet has no URI parameters. It provides Actuate servlets with the functionality for performing the following tasks:

■ Parse and validate parameters specified in Visualization Platform client URI directives.

converter.js Provides character encoding

cookie.js Provides cookie functionality, including reading, writing, and clearing browser cookies

drift.js Adjusts layers and window display for Visualization Platform client

encoder.js Contains the encode and unencode methods

htmlselect.js Provides methods for manipulating option controls

layer.js Provides layer functionality, such as createLayer, deleteLayer, getWidth, showLayer

popupmenu.js Defines the methods for manipulating pop-up menus

report.js Provides the JavaScript components for report viewing

resize.js Provides the JavaScript component for resizing a page for Visualization Platform client

saveas.js Provides the JavaScript component for saving a file as another file or object

strutscommon.js Provides JavaScript components for using the Struts framework with Visualization Platform client

viewnav.js Displays the Visualization Platform client toolbar

Table 2-10 Visualization Platform client JavaScript files

Name Description


■ Create XML API structures based on Visualization Platform client requests.

■ Submit XML streams to the Actuate SOAP API.

■ Handle responses from the Actuate SOAP API, including detecting errors.

■ Store constant session information, such as the name space and SOAP endpoint.

■ Read from and write to cookies.

■ Stream report data or errors to the web browser.

Invoking a servletInvoke servlets using the following syntax:

http://<application server>:<port>/<context root>/servlet/<servlet alias>

■ application server is the name of the machine hosting the application server.

■ port is the port on which the application server listens for requests.

■ context root is the Visualization Platform client context root.

■ servlet is a keyword indicating that a servlet follows.

■ servlet alias is the name to which the servlet is mapped in the Visualization Platform client installation’s web.xml file. A typical location for web.xml is C:\Program Files (x86)\Actuate\iHub\web\iportal\WEB-INF\web.xml.

Servlet names are case-sensitive. Do not modify the servlets, their names, or their mapping in web.xml.

Java servlets referenceTable 2-11 lists and describes the Visualization Platform client Java servlets.

This section provides the detailed reference for Visualization Platform client servlets.

Table 2-11 Actuate Visualization Platform client servlets

Visualization Platform client servlet Description

DownloadFile servlet Downloads a file from the volume

Interactive Viewer servlet Displays a BIRT report document

IDP User Password servlet Displays a shibboleth-compliant login form


DownloadFile servletDownloads a file from the volume.

Name com.actuate.reportcast.servlets.FileDownloadServlet

Invoke the DownloadFile servlet as:

http://<web server>:<port>/<context root>/servlet/DownloadFile

URIparameters

Table 2-12 lists and describes the URI parameters for the DownloadFile servlet.

Interactive Viewer servletDisplays an Actuate BIRT report document with tools to affect the document and design files. The viewer has two modes, standard and interactive.

The Standard Viewer displays the report with toolbar options to save, print, show the TOC, and launch interactive mode, as shown in Figure 2-3.

Figure 2-3 Standard Viewer

The Interactive Viewer displays the report with toolbar options to navigate the report and provides context menus to edit and format report elements, as shown in Figure 2-4.

Table 2-12 Parameters for DownloadFile URI

URI parameter Description

fileId The unique identifier of an object, usually retrieved with the selectFilesFolders JSP tag.

name The name of the object to download.

showDownloadDialog If true, a download prompt appears before moving a copy of the file. Otherwise, the servlet displays the file in the browser.

version If name is specified, the version number of the object to view. If version is not specified, the latest version is retrieved.


-Figure 2-4 Interactive Viewer

Name com.actuate.iv.servlet.IVServlet

Invoke the Interactive Viewer servlet as:

http://<web server>:<port>/<context root>/iv

URIparameters

Table 2-13 lists and describes the URI parameters for the Interactive Viewer servlet.

Table 2-13 Parameters for IV URI


__bookmark Name of the element of a report to display instead of the whole report file

__floatingfooter Boolean value to add a margin under the footer

__format A format for the displayed report: ■ pdf: Adobe PDF■ xls: MS Excel■ doc: MS Word■ ppt: MS PowerPoint■ ps: PostScript■ html: HTML■ flashchartsxml, flashgadgetsxml: used to display a fusion chart■ reportlet: used together with __bookmark to show a particular

part/element of the report

__from_page_range The page range of a report to display

__from_page_style The page style to use for a report in pdf or ps formats:■ auto: The page size and content size remains the same.■ actuateSize: Change the page size to fit the content.■ fitToWholePage: Change the content size to fit the page size.Used with the __format parameter

__imageid Name of the report file to display

__instanceid Name of the report file to display

__launchiv Boolean value that enables interactivity


IDP User Password servletDisplays a Shibboleth compliant login form used to log in to iHub 3, as shown in Figure 2-3.

Figure 2-1 IDP Login form

Name edu.internet2.middleware.shibboleth.idp.authn.provider.UsernamePasswordLoginServlet

__locale Code for a locale

__page A number for a page to render

__report Name of the report file to display

__rtl Name of the report file to display

repositoryType The name of the object to download

serverURL Contains the URL that accesses iHub, such as http://ESL02835:8000

userid The user’s identifier, required to log in to BIRT iHub

volume Contains a string value specifying the volume for this report

Table 2-13 Parameters for IV URI



Invoke the IDP User Password servlet as:

http://<web server>:<port>/idp/Authn/UserPassword

URIparameters

Table 2-13 lists and describes the URI parameters for the Interactive Viewer servlet.

Visualization Platform client JavaBeans overviewThis section describes the Visualization Platform client JavaBeans. Visualization Platform client JavaBeans provide functionality, business logic, and dynamic content to Visualization Platform client web applications. Visualization Platform client JavaBeans are in aciportal.jar, which resides in <context root>\WEB-INF\lib.

The Javadoc is provided for the JavaBeans in <Actuate product root>\iHub3\modules\BIRTiHub\iHub\web\mgmtconsole\help\api Refer to the Javadoc for a list of JavaBean methods and their arguments.

Visualization Platform client JavaBeans package referenceTable 2-15 lists and describes the Actuate packages used in Visualization Platform client.

Table 2-14 Parameters for IDP Login URI


j_password Name of the element of a report to display instead of the whole report file

j_username The user’s identifier, required to log in to BIRT iHub

Table 2-15 Visualization Platform client packages

Package Contents

com.actuate.activeportal.beans

JavaBeans that maintain information used by the Action classes.

com.actuate.activeportal.forms

JavaBeans derived from the Jakarta Struts org.apache.struts.action.ActionForm object. These JavaBeans store and validate the request parameters in HTTP requests.

com.actuate.activeportal.list

An interface, IContentList, that defines the behavior of lists of items such as files and folders. Several classes in com.actuate.activeportal.forms use this interface.


Visualization Platform client JavaBeans class referenceThis section lists and describes the Visualization Platform client JavaBean classes by topic.

DocumentsTable 2-16 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support the Document pages.

Table 2-16 Document classes

Class Description

BrowseFileActionForm Supports browsing through the available files, including using filters to search.

CreateFolderActionForm Supports creating a folder in the volume.

FileFoldersPrivilegeActionForm

Stores information about file and folder access rights, the available users and roles, and so forth. Visualization Platform client uses this information to set up file and folder privileges.

FileListActionForm Retrieves a list of folders or files. This ActionForm supports setting filters specifying characteristics of objects. Stores the most recent list of items returned from iHub.

GeneralFilterActionForm The base ActionForm for several other ActionForms. Provides methods that handle filters to select which items the iHub returns. For example, you can request all folders and only the most recent version of all executable files.

GetFileDetailsActionForm Stores the details of a file or folder. AcGetFileDetailsAction gets the details and stores them in this JavaBean.

SearchFilesActionForm Stores information about the filter set by the user in the Search page. Jakarta Struts uses the filter to retrieve the list of files from the iHub and store them in this form.


GeneralTable 2-17 describes the Visualization Platform client com.actuate.activeportal.beans class that supports general functionality.

Table 2-18 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support general functionality.

JobsTable 2-19 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support jobs.

Table 2-17 General bean class

Class Description

LinkBean Generates an HTML link tag using the link, linkAttributes, and text properties. By default, the link class is hyperlink. After setting these properties, use the toString() method to generate an HTML link tag in the following format:<A HREF="link" linkAttributes>text</A>

Table 2-18 General forms classes

Class Description

BaseActionForm The base ActionForm for all other Visualization Platform client ActionForms. Provides methods related to postback.

PingActionForm Stores information used by the ping action. Ping detects the status of Visualization Platform client and iHub communication.

Table 2-19 Job classes

Class Description

GeneralFilterActionForm Serves as a base ActionForm for several other ActionForms. Provides methods that handle filters to select which items the iHub returns. For example, you can request all folders and only the most recent version of all executable files.

GetJobDetailsActionForm Stores detail information on jobs. AcGetJobDetailsAction uses this class to store and retrieve the job detail information for display.

JobActionForm The base ActionForm for SubmitJobActionForm. Stores values used in submitting a job, such as the document, parameters, and schedule.


UsersTable 2-20 lists and describes Visualization Platform client com.actuate.activeportal.beans classes that support handling users.

Table 2-21 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support handling users.

SelectJobsActionForm Contains the list of job properties for a scheduled, running, pending, or completed job.

SubmitJobActionForm Contains the information for submitting a job from the requester page. This class extends JobActionForm.

Table 2-19 Job classes

Class Description

Table 2-20 User bean classes

Class Description

FeatureOptionsBean Stores the features available to the current user. It contains Visualization Platform client functionality levels and reporting features on the iHub the user is using. Access this class using UserInfoBean.getFeatureBean().

ProfileBean Stores the user profile settings obtained from the iHub. Access this class by using UserInfoBean.getProfile().

UserAgentBean Detects what kind of browser the user is using from the HTTP header user-agent. After instantiating this JavaBean, you must call setRequest(HttpServletRequest request). Get the browser type by calling isIE(), isNS4(), and isNS6() methods.

UserInfoBean Contains information about the user, such as the user’s volume name, iHub URL, and authentication ID assigned by the iHub. Several methods also affect the display and highlighting of features.

Table 2-21 User form classes

Class Description

LoginForm Stores information about the user ID, server URL, volume, and other information specified during login.

UserOptionsActionForm Stores the selected choices on the options page, including the view, experience level, and e-mail ID. This form supports changing these options.


Visualization Platform client UserInfoBean class referenceTable 2-22 lists and describes the methods other than set methods available in the Visualization Platform client com.actuate.activeportal.beans.UserInfoBean class.

Table 2-22 UserInfoBean methods

Method Description

getAcLocale() Gets the AcLocale object specifying the Actuate locale for the current user.

getAdminRights() Gets the administrator rights of the current user. If the user is not an administrator or operator, this method returns null. An administrator or application sets these rights when creating a user.

getAuthid() Gets a String containing the authentication ID returned by the iHub for this user during login. Use this authentication ID in IDAPI calls.

getCurrentfolder() Gets a string containing the name of the most recent folder accessed by the user.

getDefaultServerURL() Gets a string for the URL to use for the default server for the user.

getDefaultVolume() Gets the volume name from the VOLUME_DEFAULT tag in <context root>\WEB-INF\web.xml.

getFeatureOptionsBean() Gets a JavaBean that stores the features and iHub options that are available to the current user.

getFeatures() Gets a list of all features defined in the functionality-level.config file.

getFilter() Gets a string containing the filter the user most recently typed into the search field of the Documents page. If the user has not typed a filter, this method returns null.

getHomefolder() Gets a string specifying the user’s home folder. An administrator or application sets this value when creating a user.

getIportalid() Gets a string specifying the Visualization Platform client session id.

getLocale() Gets the current login user’s java.util.Locale object.

getMaxJobPriority() Gets the maximum job priority permitted for this user. An administrator or application sets this value when creating a user.

(continues)


getOnlylatest() Gets the string “true” if the filter on the Documents page specifies showing only the most recent version of each file.

getPassword() Gets a string containing the user’s password.

getProfile() Gets the ProfileBean. This JavaBean stores information about the user’s settings on the Visualization Platform client options page. This information includes current view, experience level, and so on.

getProperty(java.lang.String name)

Gets a string containing the value of a custom property having the name passed as a parameter. Create custom properties and set their values using setProperty().

getRepositoryType() Gets a string specifying the type of repository that the user is accessing as:workgroup: local file systementerprise: a volume

getRoleNames() Gets an array of strings containing a list of the user’s feature roles.

getServerurl() Gets the URL of the server to which the current user is logged in. This URL includes the protocol and the port. For example: http://localhost:9000.

getShowdocuments() Gets the string “true” if the filter on the Documents page specifies including documents.

getShowexecutables() Gets the string “true” if the filter on the Documents page specifies including executable files.

getShowfolders() Gets the string “true” if the filter on the Documents page specifies including folders.

getSideBarFeatures() Gets the list of features available to this user on the side menu, tabs, the tree, or equivalent structure. Some features, such as customization, are not part of this set.

getSidebarSelected() Gets the URL for the feature selected on the side menu, tab, tree, or equivalent structure. This method is used to highlight a feature in the sidebar.

getSubfeatures() Gets a collection containing a list of all subFeatures defined in <context root>\WEB-INF\functionality-level.config.

getSystemname() Gets a string containing the name of the iHub machine.

getTimezone() Gets the AcTimeZone object specifying the time zone for the current user.

getUserAgent() Gets the UserAgentBean object for the user. UserAgentBean detects the user’s browser type.

Table 2-22 UserInfoBean methods (continued)

Method Description


UserInfoBean calls set methods when the user logs in to set the values that the get methods return. Typically, your application should not call the set methods as the bean would then be inconsistent with the information stored in the repository or external security application. These set methods only change the values in the bean, so the results of the calls are not deterministic.

Table 2-23 lists and describes set methods that are available in the Visualization Platform client com.actuate.activeportal.beans.UserInfoBean class.

getUserid() Gets the userID of the current user.

getView() Gets the string specifying the current view for this user.

getVolume() Gets the string specifying the volume that the user is accessing.

init() Initializes the UserInfoBean members.

isAlwaysGetFolderList() Returns True if the Documents page should always show the folder list, even if it is not selected on the filter.

isHomeFolderSet() Returns True if the user has a home folder specified in the volume.

(continues)

isShowFilters() Returns True if the filter panel is shown for all lists of documents, jobs, and subscriptions.

isViewInNewBrowserWindow()

Returns True if the report viewer is specified to launch in a new browser window.

toString() Returns a string representation of the object.

Table 2-22 UserInfoBean methods (continued)

Method Description

Table 2-23 UserInfoBean set methods

Method Description

setAcLocale(com.actuate.reportcast.utils.AcLocale acLocale)

Sets the Actuate locale for the current user with the specified AcLocale object. Also changes the Java locale.

setAlwaysGetFolderList(boolean b)

Set to True if the Documents page should always show the folder list, even if it is not selected on the filter.

setAuthid(java.lang.String authid)

Sets the authentication ID to the string passed in as a parameter. The authentication ID is returned by the BIRT iHub and set for the user during login. Use getAuthid() to use this authentication ID in IDAPI calls.

setCurrentfolder(java.lang.String currentfolder)

Sets the string specifying the most recent folder name accessed by the user.


setDefaultServerURL(java.lang.String defaultServerURL)

Sets the URL to use as a default value for users.

setDefaultVolume(java.lang.String defaultVolume)

Sets the volume to use if no volume name is specified by the URL in the request. By default, Visualization Platform client sets the default volume to the value in the VOLUME_DEFAULT tag in <context root>\WEB-INF\web.xml.

setFeatureOptions(FeatureOptionsBean featureOptionsBean)

Sets a list of all Visualization Platform client features and iHub options that are available to the current user.

setFilter(java.lang.String filter)

Sets the string specifying the filter to use as a default value in the Documents page. Visualization Platform client sets this String to the filter that the user most recently typed into the search field of the Documents page.

setHomefolder(java.lang.String string)

Sets the string specifying the user’s home folder. An administrator or application sets this value when creating a user.

setMaxJobPriority(int priority)

Sets the maximum job priority permitted for this user. An administrator sets this value for a user.

setOnlylatest(java.lang.String onlylatest)

Sets value to indicate if only latest version of the documents are to be displayed in the file folder list. “true” sets Visualization Platform client to show only the most recent version of each file.

setPassword(java.lang.String password)

Sets the password to the value of the string passed as a parameter.

setProfile() Sets the ProfileBean. This JavaBean stores information about the user’s settings on the Visualization Platform client options page. This information includes current view, experience level, and so on.

setProperty(java.lang.String name, java.lang.String value)

Sets the value of a custom property. Create custom properties and set their values using this method. The parameters are the name of the custom property and the value to set.

setRoleNames(java.lang.String[] strings[])

Sets a list of the user’s feature roles, such as Administrator.

setServerurl(java.lang.String surl)

Sets the server URL currently used by the user. This URL includes the protocol and the port, for example: http://localhost:9000.

Table 2-23 UserInfoBean set methods (continued)

Method Description


setShowdocuments(java.lang.String showdocuments)

Sets the value to indicate if documents are to be displayed in the file folder list. “true” sets Visualization Platform client to display documents.

setShowexecutables(java.lang.String showexecutables)

Sets the value to indicate if executables are to be displayed in the file folder list. “true” sets Visualization Platform client to display executables.

setShowFilters(boolean showFilters)

Set to True to specify that Visualization Platform client display the filter panel for all pages showing lists of files, jobs, or subscriptions.

(continues)

setShowfolders(java.lang.String showfolders)

Sets the value to indicate if folders are to be displayed in the file folder list. “true” sets Visualization Platform client to display folders.

setSideBarFeatures(com.actuate.activeportal.functionality.config.Feature[] feature)

Sets the list of features available to this user on the side menu, tabs, the tree, or equivalent structure. This list is a subset of the features available to the user.

setSidebarSelected(java.lang.String sideBarSelected)

Sets the feature highlighted on the side menu, tab, tree, or equivalent structure. To highlight a feature, pass a string containing the URI invoked by the feature. To not highlight any features, pass a string, such as “No highlighting”, that does not match the URI for any feature in the side menu. By default, Visualization Platform client highlights the Documents feature.

setSystemname(java.lang.String systemName)

Sets the iHub system name to the value of the string parameter.

setTimezone(com.actuate.reportcast.utils.AcTimeZone timezone)

Sets the AcTimeZone object specifying the user’s time zone.

setUserAgent(UserAgentBean userAgent)

Sets the UserAgentBean for this user. The UserAgentBean specifies the user’s browser type.

setUserid(java.lang.String userid)

Sets the user ID for the user.


Method Description


setView(java.lang.String string)

Sets the current view for the user. The string contains the name of the constant for the desired view. The available constants are:■ AcConstants.VIEW_CATEGORY■ AcConstants.VIEW_LIST■ AcConstants.VIEW_DETAIL■ AcConstants.VIEW_ICON

setViewInNewBrowserWindow(boolean _newWindow)

Set to True to specify that the report viewer launch in a new browser window.

setVolume(java.lang.String volume)

Sets the value of the string specifying the name of the volume the user is accessing.


Method Description

C h a p t e r 4 , C o n f i g u r i n g R e p o r t S t u d i o 69

C h a p t e r

4Chapter 4Configuring Report StudioThis chapter contains the following topics:

■ Assigning license options to a user

■ Enabling or disabling functionality

■ Configuring the application environment


Assigning license options to a userIf you have named user licensing, Actuate BIRT iHub requires the assignment of license options to each user to support the user accessing, running, and viewing BIRT reports in an Encyclopedia volume. Use iHub Administration to create a user and a home folder, and assign license options in an Encyclopedia volume. A user uses the home folder to access, run, and view BIRT reports using a web browser.

How to create a user and a home folder, and assign license options

In this task, create a new user, and specify a home folder for the user, using System Console.

1 Start Visualization Platform client by opening a browser window and typing the following URL in the address bar:

http://127.0.0.1:8700/iportal/login.jsp

The Visualization Platform client login page appears, as shown in Figure 2-1.

Figure 2-1 Logging in to Visualization Platform client

2 In User name, type Administrator. Choose Log In. Visualization Platform Dashboard appears, as shown in Figure 2-2.


Figure 2-2 Visualization Platform client Dashboard

3 In the banner menu, choose iHub Administration. Administration—Users appears.

4 To create a new user, complete the following tasks:

1 Choose Add User, as shown in Figure 2-3.

Figure 2-3 Adding a User in iHub Administration

2 In Create New User—General, as shown in Figure 2-4, in Name, type the new user’s name, for example:

pcastillo

3 In Password and Confirm Password, type the same password.

4 In Email, type the user’s email address.

5 In Home folder, type the path to the home folder, for example:

/Home/pcastillo

Choose to add a user


Figure 2-4 Creating a new user

6 To provide the new user access to the Actuate products, choose Assign Licenses.

7 In Assign Licenses, in Available Licenses, press Ctrl and select:

❏ BIRT Option

❏ Report Studio Option

Choose the right arrow. The options appear in Selected, as shown in Figure 2-5.


Figure 2-5 Selecting licensed options

Choose Save. In Confirmation, choose OK. Users displays the new user, and the path to the user’s email address, as shown in Figure 2-6.

Figure 2-6 iHub Administration, displaying the new user

5 To log out of Visualization Platform client, in the banner menu, choose Log Out.


Enabling or disabling functionalityReport Studio provides a full range of tools to support the report design process. Administrators can limit Report Studio functionality by user roles. For example, if the Report Studio users you support have little experience designing reports, you can simplify the design process by disabling more advanced functionality, such as creating calculated columns, aggregating data, and joining multiple information objects. Alternatively, if you want users to format report content only by selecting a corporate-designed theme, you can disable the formatting functionality.

Configuring toolbar and context menu itemsYou configure the toolbar and context menu functionality that is available to users by editing attributes in the Report Studio configuration file, erni_config.xml. This file is located in:

<context root>\WEB-INF

Customizations you make to erni_config.xml apply at the application level. If you want different sets of functionality available to different groups of users, you need to create multiple instances of the web application, then customize the functionality of each Report Studio instance.

In erni_config.xml, the <actionSets> element defines all the user actions that can be enabled or disabled. The actions are organized by category, for example, file operations, calculations, and formatting. The <actionSet> element defines the category, and the <action> element defines a specific action. Listing 2-1 shows the hierarchy of elements.

Listing 2-1 An example of an <actionSet> element in erni_config.xml

<actionSets><actionSet>

<name>FileOperations</name><visible>true</visible><action>

<name>New</name><enabled>true</enabled>

</action><action>

<name>Open</name><enabled>true</enabled>

</action><action>

<name>Save</name><enabled>true</enabled>

</action>


<action><name>SaveAs</name><enabled>true</enabled>

</action></actionSet>

By default, all actions are enabled. You can disable actions in the following ways:

■ To disable a particular action, change the action’s <enabled> attribute from true to false.

■ To disable all actions within a category in one step, change the action set’s <visible> attribute from true to false.

For the changes to take effect, restart the appropriate Windows service. When you relaunch Report Studio, the toolbar displays different buttons and the context menus display different items, depending on which action or actions you disabled.

Configurable actionsTable 2-1 lists toolbar and context menu actions that you can enable or disable. Some of the actions appear in both the toolbar and context menus, and some appear in context menus only. While you can disable any of the actions defined in erni_config.xml, it does not make sense to disable all the actions. For example, disabling both the New and Open actions under file operations prevents a user from creating or opening reports.

Table 2-1 User actions that you can enable or disable through erni_config.xml

Action set Action Description

Calculations Aggregation Performs a calculation over a specified set of data rows.

Calculation Creates a calculated column, based on a specified expression.

ChangeSubtotal Changes the subtotal function, applied to a column in a summary table.

Chart Inserts a chart.

DataFields Shows the data fields in the report, and supports adding or deleting fields in the report.

EditCalculation Changes a calculated column.

Filter Filters table rows, based on a specified condition.


ColumnHeaderOperations

DeleteRow Deletes the row of the selected column header.

InsertRow Inserts a row above or below the selected column header.

Merge Merges the selected column header with the header on the right, left, or above.

Split Splits the selected merged columns.

ColumnOperations ColumnWidth Changes the width of the selected column.

HideColumn Hides the selected column.

MergeColumns Merges the selected columns.

MoveToDetail Moves the selected item in the group header row to the table’s detail row.

MoveToGroup Moves the selected item in the table’s detail row to the group header row.

NoRepeat If duplicate data values appear in the selected column, displays only the first instance.

ReorderColumns Changes the order of the columns in the table.

RepeatValues Displays duplicate data values in the selected column.

ShowColumns Shows the selected columns.

(continues)

CrosstabOperations Analyze Opens Data Analzyer.

Delete Deletes a cross tab.

Edit Opens the cross tab builder.

SwitchView Switches the cross tab view.

ManageData ManageData Opens the Manage Data dialog.

DeleteColumn DeleteColumn Deletes a column from a table in the report.

EditText EditText Enables editing of the selected static text.

FileOperations New Creates a new report design file.

Open Opens an existing report design.

Save Saves the current report design.

SaveAs Saves the current report design file under a different name or in a new location.

Table 2-1 User actions that you can enable or disable through erni_config.xml (continued)



Formatting AlignCenter Centers the text in the selected column.

AlignLeft Aligns the left sides of text in the selected column.

AlignRight Aligns the right sides of text in the selected column.

Border Draws a border around the selected column.

ConditionalFormat

Formats data in a selected column, based on a specified condition.

Data Formats the display of data in the selected column.

Font Formats the font of data in the selected column.

GeneralOperations Parameter Displays the parameters, if any, for the current report.

SwitchSummaryMode

Switches between summary table mode and detail table mode for the selected table.

TableBuilder Enables the table builder wizard.

Grouping CreateSection Adds a report section, which provides an additional level of data grouping.

DeleteSection Removes the selected report section.

Grouping(continued)

GroupBy Groups table rows by values in the selected column.

HideDetail Hides the detail rows in a report section.

PageBreak Adds page breaks before or after a report section.

ShowDetail Shows the detail rows in a report section.

UngroupBy Removes groups in the selected column.

Help Help Shows help information.

PageLayout PageLayoutInToolbar

Displays page layout toggle under toolbar. Disabled by default.

Preview PreviewHTML Shows a preview of the report in HTML format.

ReportItemOperations Bookmark Assigns a bookmark to a report item.




Configuration examplesThis section provides examples of editing attributes in erni_config.xml, and the resulting changes to the Report Studio page.

Hyperlink Assigns a hyperlink to a report item.

SectionOperations SectionHeading Shows the data fields in the report, and supports adding fields to the selected section heading.

Sorting AdvancedSort Sorts the table rows by the values of multiple columns.

SortAscending Sorts, in ascending order, the table rows by the values of the selected column.

SortDescending Sorts, in descending order, the table rows by the values of the selected column.

TemplateTableOperations

AutoSummarizeOn If set to true, creates a summary table by default. If set to false, creates a detail table by default.

UndoRedo Redo Redo the last action.

Undo Undo the last action.




Figure 2-7 shows the default Report Studio page with all actions enabled. The formatting actions on the toolbar and context menu are called out, so that you can see the difference in the toolbar and context menu when these actions are disabled.

Figure 2-7 Default BIRT Studio page

Listing 2-2 shows a change to the Formatting action set. Its <visible> attribute, shown in bold, is set to false. Note, however, that all the actions under the Formatting action set are still enabled.

Listing 2-2 Visibility of the Formatting action set, changed to false

<actionSet><name>Formatting</name><visible>false</visible><action>

<name>AlignLeft</name><enabled>true</enabled>

</action><action>

<name>AlignCenter</name><enabled>true</enabled>

</action>

Formatting actions

FormatActions


<action><name>AlignRight</name><enabled>true</enabled>

</action><action>

<name>Font</name><enabled>true</enabled>

</action><action>

<name>Border</name><enabled>true</enabled>

</action><action>

<name>ConditionalFormat</name><enabled>true</enabled>

</action><action>

<name>Data</name><enabled>true</enabled>


Figure 2-8 shows the updated Report Studio page. None of the formatting actions appear in the toolbar or the context menu. Setting the <visible> attribute of an action set to false disables all actions within the action set.

Figure 2-8 Updated toolbar and context menu, without any formatting functions


Listing 2-3 shows changes to the Font and Data actions within the Formatting action set. The Formatting action set’s <visible> attribute is set to true. The Font and Data actions are disabled. The other actions in the action set are still enabled.

Listing 2-3 Font and Data (formatting) actions disabled

<actionSet><name>Formatting</name><visible>true</visible><action>

<name>AlignLeft</name><enabled>true</enabled>

</action><action>

<name>AlignCenter</name><enabled>true</enabled>

</action><action>

<name>AlignRight</name><enabled>true</enabled>

</action><action>

<name>Font</name><enabled>false</enabled>

</action><action>

<name>Border</name><enabled>true</enabled>

</action><action>

<name>ConditionalFormat</name><enabled>true</enabled>

</action><action>

<name>Data</name><enabled>false</enabled>


Figure 2-9 shows the updated Report Studio page. The alignment actions are available on the toolbar and on the context menu, but not the Font and Data formatting actions.


Figure 2-9 Updated toolbar and context menu, without the Font and Data formatting actions

Specifying the default position of aggregate valuesThe default location of aggregate values is in a group’s header. To place aggregate values in a group’s footer, set EnableNewAggregationStyle to false in erni_config.xml:

<featureConfigs><featureConfig>

<name>EnableNewAggregationStyle</name><value>false</value>

</featureConfig>...</featureConfigs>

Using sample data in a previewActual data is used to generate a preview by default. To improve preview performance, you can configure BIRT Studio to use sample data instead, which uses dummy values. To enable sample data in a preview, set EnableSampleDataInPreview to true in erni_config.xml:

Alignment actions


<featureConfigs>...

<featureConfig><name>EnableSampleDataInPreview/name><value>true</value>

</featureConfig>...</featureConfigs>

Configuring advanced data operationsYou can enable or disable the following advanced data options in Available Data in the report design area of Report Studio:

■ Modify enables the user to change the data set by joining it with one or more information objects.

■ Synchronize Data Sets enables the user to update the data set in the report design with the current data in the information object on the volume.

Figure 2-10 shows the data options in Available Data.

Figure 2-10 Advanced data options

By default, these data options are disabled by default and they are in effect only when the data sources are information objects. The Modify and Synchronize Data Sets buttons do not appear unless enabled by configuration.

You can enable these options by editing attributes in one of Visualization Platform client’s configuration files, functionality-level.config. For information about all the functionality options listed in functionality-level.config, see Chapter 3, “Configuring Actuate Visualization Platform client.”

Listing 2-4 highlights in bold the advanced data option that can enable the advanced data option user interface buttons.

Synchronize Data Sets option

Modify option


Listing 2-4 Intermediate and Advanced levels in functionality-level.config

<Level><Name>All</Name>...<SubfeatureID>InteractiveViewing</SubfeatureID><SubfeatureID>AdvancedData</SubfeatureID><SubfeatureID>DashboardDeveloper</SubfeatureID>

</Level>

Unlike the functionality options you set in erni_config.xml, the options you set in functionality-level.config apply at when a user logs in, not at the application level. The Information Object integration service must be enabled for the buttons to function.

Configuring the application environmentYou can change the values of the configuration parameters in the following file:

<context root>\WEB-INF\web.xml

Report Studio parameters control how Report Studio operates a web application and how it interoperates with Visualization Platform client. Table 2-2 describes the configuration parameters for Report Studio.

Table 2-2 Report Studio web.xml parameters


BIRT_REPORT_DESIGN_CACHE_TIMEOUT

Specifies the amount of time, in seconds, before a cached BIRT report design is purged if it has not been used. The default value is 1800, which is 30 minutes.

BIRT_REPORT_DESIGN_CACHE_TOTAL_NUMBER_OF_ENTRIES

Specifies the maximum number of BIRT report designs to cache. The default value is 50.

BIRT_REPORT_DOCUMENT_CACHE_ENABLED

Specifies whether to cache BIRT report documents when they are previewed or generated. The default value is true.

BIRT_REPORT_PAGE_COUNT_CACHE_ENABLED

Specifies whether to cache the number of pages in transient or persistent BIRT report documents when they are previewed or generated. The default value is true.

BIRT_RESOURCE_PATH Path to Actuate BIRT shared resources, including libraries and templates for Actuate BIRT report designs and Report Studio. The default value is <context root>\resources.

BIRT_SCRIPT_LIB_PATH Path to script libraries. The default value is <context root>\scriptlib.


DEFAULT_DATA_CACHE_ROW_COUNT

The number of data rows to display in Report Studio when designing a report. The default value is 100.

DEFAULT_LOCALE The default locale. The default locale is en_US. Users can select a locale when they log in.


The number of rows to display on one page when viewing a report. A value of 0 indicates no page breaks.

DEFAULT_REPORT_TEMPLATE_CATEGORY_NAME

The default BIRT report template category to load when a user opens BIRT Studio. The default value is Standard.

DEFAULT_TIMEZONE The default time zone. The default time zone is Pacific Standard Time (PST).

MAX_BRSTUDIO_DESIGN_SESSION

The maximum number of designs a user can edit concurrently in Report Studio. The default is 10.

MAX_BRSTUDIO_USER_SESSION

The maximum number of concurrent Report Studio sessions on the server. The default is 256.

MAX_DATA_CACHE_ROW_COUNT

Limits the number of data rows that a user can choose to display in Report Studio when designing a report. The default value is 200.

MAX_NUMBER_OF_VALUES_FOR_DYNAMIC_PARAMETER

The number of values shown in the parameter dialog box for a dynamic value parameter in Report Studio:■ A positive number value N means only the first N values

appear the parameter dialog box. ■ A value of 0 means all values from the data source appear in

the parameter dialog box. The default value is 0.■ A value of -1 means only the first N values appear where

N is the current data cache row count setting for the current design session.

MAX_NUMBER_OF_VALUES_FOR_DYNAMIC_PARAMETER only applies to a dynamic value parameter. All the values appear for a static value parameter no matter how many values it has. For a static value parameter, the full list appears in the parameter dialog box when the user chooses Save and View.

MEMORY_DATA_CACHE_ROW_COUNT

Specifies the number of data rows to cache in memory. The default value is 50.

(continues)

Table 2-2 Report Studio web.xml parameters (continued)



MORE_VALUE_ROW_COUNT

Specifies the number of rows to fetch when a user chooses to filter a report on a column in Report Studio. The default value is 200.

PERSISTENT_ARCHIVEFILECACHE_TIMEOUT_SECONDS

Specifies the amount of time, in seconds, before a cached file that was created from a repository file is purged if it has not been used. The default value is 7200, which is 120 minutes.

SEARCH_ENABLE_COLUMN_HEADERS

Indicates whether to include column headings in report search results when the output format is CSV or TSV. Set this parameter to true, the default value, to include column headings.

SEARCH_USE_QUOTE_DELIMITER

Indicates whether to enclose search results in quotation marks when the output format is CSV or TSV. The default value is true, which encloses the results in quotation marks.

TRANSIENTARCHIVEFILECACHE_TIMEOUT_SECONDS

Specifies the amount of time, in seconds, before a cached file generated without saving it to the repository is archived if it has not been used. The default value is 1200, which is 30 minutes.

Table 2-2 Report Studio web.xml parameters (continued)


C h a p t e r 5 , C u s t o m i z i n g a n d i n t e g r a t i n g R e p o r t S t u d i o 87

Chapter

5Chapter 5Customizing and

integrating Report StudioThis chapter contains the following topics:

■ About report templates

■ Design considerations

■ Creating a report template

■ Providing data with a report template

■ Creating themes for a report template

■ Publishing a template

■ Setting the default template category

■ Publishing resources associated with a template

■ Types of data sources

■ Using data objects as a data source

■ Creating data objects

■ Creating a custom data source


About report templatesA report template defines a basic report structure on which new reports are based. The Report Studio user always creates a new report by selecting a template first.

Report Studio includes several predefined templates. Often, however, users request custom templates that better suit the data they want to present. In addition, an organization typically requires reports with a particular look and feel. You create templates using the Report Design perspective in Actuate BIRT Designer Professional, an Eclipse-based application for creating reports.

Design considerationsA template typically contains visual elements, such as tables, charts, and labels. It can, however, also contain defined data sets, which specify the data to display in a report. A template can even be a complete report that presents professionally formatted data.

Before you begin creating templates, gather the following basic information:

■ What data will the Report Studio user use in a report?

■ How does the user want to present the data?

■ What does the user need as a starting point for a report?

The rest of this section provides tips for creating effective templates.

Separating or combining visual and data elementsWhen designing a template, one of the key decisions you make is whether to include both visual and data elements in the template or keep them separated. Good design typically dictates that templates contain only visual elements, and that data objects or data objects contain the data. You might decide, however, to create templates that include data, because some users, particularly inexperienced users, prefer to view a report without having to do anything other than select the template.

Templates that contain only visual elements are more versatile. A single template can be used for different reports that present different data. The user can mix and match data objects or data objects with templates. From a development and administrative perspective, separating presentation from data can be efficient and optimal, because template design and data retrieval can be accomplished by developers with design expertise and data-retrieval expertise, respectively. This strategy, however, requires that the template designer and the data architect coordinate to ensure that the templates and data are suitable for use together.


Designing themesReport Studio provides several options for formatting the contents of a report. The standard toolbar provides the user with formatting options to modify the font, color, style, text alignment, and other properties of individual report items. The report design area on the left side of Report Studio displays themes, if any are provided, that the user can select to apply a set of styles to the entire report.

A theme is a collection of styles. The concept and functionality of styles are similar to styles in Microsoft Word and cascading style sheets (CSS). Designers create a theme to apply a consistent style, or look and feel, to a report. A theme, for example, can specify the colors used in a report, the font used for different text, label, or data items, the spacing or alignment of items, border styles, and so on.

Report Studio provides four themes with the default templates, as shown in Figure 3-1.

Figure 3-1 Themes provided with the default templates

When you create a template, consider creating different themes, so that the user can choose from multiple styles. While the creation of a theme is optional, it is standard practice among designers, similar to the use of cascading style sheets with web pages. Themes are stored in a BIRT library file, separate from the template file.

Defining all the styles in a theme within a library, rather than applying formats to individual report items in the template, makes it easier to maintain and update the appearance of a template. When a user requests new or modified styles to use with a particular template, all you do is update the theme in the library, then publish the latest version of the library. You do not need to modify the template file.


Improving usabilityA template should be intuitive to use. The user should be able to quickly determine how to use the elements in a template, and be able to freely edit most elements. The following are some guidelines for improving the usability of a template:

■ Set the general properties of the template file:

■ The display name of the template

■ A brief description of the template

■ The image to use as the thumbnail image of the template

These properties are not required. However, if you do not specify a display name, the name of the template file is used. If you do not supply a description, the word “null” appears, and if you do not specify an image, the user sees a gray box with the x icon. Figure 3-2 shows what the user sees on the Report Template page when a template’s properties are set and when the properties are not set.

Figure 3-2 Displaying two templates: one with properties set, one without properties set

■ Decide which report elements in the template are editable. Examples of editable elements include label elements for displaying report titles, section titles, or column headings, and empty tables into which users insert data. Examples of non-editable elements include company logos and standard copyright statements.

■ Provide meaningful names for each report element, so the Report Studio user can easily identify the type and purpose of the element. If you do not specify a name, Report Studio displays the name of the element type, such as Text or Label. If your template contains three labels, and you do not specify a name for any of the labels, Report Studio displays Label three times in the View menu. The View menu lists all the elements in the template, so users can


choose whether to display the elements in the report. Figure 3-3 shows one of the default templates with several elements listed in the View menu. The elements have descriptive names.

■ Provide instructions for using each editable element. For example, a table can display a message, such as “To insert data in this report, drag the columns you want from Available Data and drop them in this table.” Figure 3-3 shows a table with detailed instructions.

Creating a report templateYou use Actuate BIRT Designer Professional to create report templates. You design a template in the same way that you design a BIRT report. In fact, you can create a report design then save it as a template. The file-name extension for a template file is .rpttemplate. If you are creating templates for users worldwide, you can localize the text in the templates the same way you localize text in a BIRT report. The templates that ship with Report Studio are localized, and the text in each template appears in the language specified by the locale the user chooses when logging in to Actuate Visualization Platform client.

This section describes the key steps for creating a template but does not provide information about the report elements you can use in a template.

Figure 3-3 Report Items listing all the template elements

List of elements in the template


How to create a report template

1 In the Report Design perspective, create a new template using the following procedure:

1 Choose File➛New➛Template.

2 In New Template—Template, select the folder in which to create the template file, specify a file name, then choose Next.

3 In New Template—Set Template Property:

1 In Display Name, specify a display name for the template. This name identifies the template when the template is displayed on the Report Template page in Report Studio.

2 In Description, provide a description of the template. This description appears as a tooltip when the user hovers the mouse pointer over the template in Report Studio.

3 In Template Image, browse to the thumbnail image of the template. This step assumes that you have already created the image you want to use as the thumbnail image and placed it in Shared Resources.

4 Choose Finish. A blank report page appears in the layout editor.

2 Drag elements from the palette, and drop them in the layout editor.

3 For elements that you want Report Studio users to edit for their report designs, identify those elements as template report items. Only labels and tables can be edited in Report Studio:

1 Right-click the element, then choose Create Template Report Item.

2 Specify a descriptive name for the element, so the Report Studio user can easily identify the purpose of the element.

3 Provide instructions for using the element.

Figure 3-4 shows an example of an element name and instructions for using the element.

Figure 3-4 Specifying name and instructions for an editable element


4 For elements that you do not want the Report Studio user to edit, you should also specify a descriptive name, so that the Report Studio user can easily identify the purpose of the element and decide whether to include the element in the report. In Property Editor, type a name for the Name property. Figure 3-5 shows setting a label’s name as Copyright.

Figure 3-5 Specifying a name for a label element that users cannot edit

Providing data with a report templateIf you are creating a template that you want the Report Studio user to use with an data object or a data object, add an editable table element to the template. When a template contains an editable table element, Report Studio prompts the user to select what type of data source they choose, data objects or information objects. Then the report wizard displays a list of the objects from the selected type, published on the server and available to you. You can choose a data object or an information object to use in your report.

If you are creating a template that includes data, create a data source and data set that specifies the data that the Report Studio user can display in the report. You can define multiple data sources and multiple data sets in a template. When the user selects a template with multiple data sets, Report Studio prompts the user to select one of the data sets to use for the report. In addition to the standard data source types, you can use information objects and data objects as data sources as well.

Using a CSV file as a data sourceA Report Studio report design can use a comma-separated values (CSV) file as a data source if the CSV file is a predefined data set in a report template. To use the


file as a data source, you must copy the CSV file to the appropriate directory. To determine which directory to use, download the .rptdesign file to a local directory as an XML file. In the XML code, locate the <data-sources> element, shown in the following example:

<data-sources><oda-data-sourceextensionID="org.eclipse.datatools.connectivity.oda.flatfile"name="Data Source" id="266"><text-property name="displayName">Data Source</text-property><property name="HOME">C:\</property><property name="CHARSET">UTF-8</property><property name="INCLTYPELINE">YES</property></oda-data-source></data-sources>

The HOME property shows the directory in which to place the CSV file.

Excluding a data setYou can exclude a data set in a template from the Select Data dialog in Report Studio. For example, you want to display stock quote data from a web service in the report, but you do not want the user to manipulate the data. To exclude a data set from the Select Data dialog, set the data set’s UsageInBRS property to excluded in the template’s XML representation. For example, the following code excludes the Orders data set:

<oda-data-set extensionID="org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet" name="Orders" id="8"><list-property name="userProperties">

<structure><property name="name">UsageInBRS</property><property name="type">string</property><property name="isVisible">true</property>

</structure></list-property><property name="UsageInBRS">excluded</property>

Creating themes for a report templateAs described earlier in this chapter, you create themes to provide the user with different sets of styles to apply to a report. You use Actuate BIRT Designer Professional to create the themes in a library. After you create the library, you associate the library with the template.


A library can contain any number of themes, and a theme can contain any number of styles. Actuate BIRT Designer Professional provides support for two types of styles. You are able to do the following:

■ Create a custom style, and apply it to a report element. For example, you can create a style named Report Title, then apply the style to a label that displays the report title.

■ Apply style properties to predefined style names, or selectors. These predefined style names correspond to the different types of report elements. For example, you can apply style properties to a predefined style named table-header, and all table headers in the report are formatted accordingly. This technique is similar to defining styles in CSS where you associate styles with HTML elements, such as <H1> or <P>.

How to create a theme

1 Create a library:

1 Choose File➛New➛Library.

2 In New Library, specify the folder in which to create the library, specify a file name, then choose Finish. If a message box appears, choose OK.

2 Choose Outline view. Outline view, shown in Figure 3-6, displays the types of report elements you can add to a library.

Figure 3-6 Outline view

3 In Outline view, expand Themes.

4 Right-click defaultTheme, and choose Rename to change the name of the theme.

5 Right-click the theme, and choose New Style to create a style for the theme.

6 On New Style, select one of the following options:

■ To apply style properties to a specific type of report element, select Predefined Style, and select a style from the drop-down list.


■ To create a user-named style, select Custom Style, and specify a unique descriptive name, such as Report Title or Copyright.

7 Set the desired properties for the style by selecting a property category on the left and specifying property values.

8 When you finish setting style properties, choose OK to save the style.

9 Repeat steps 5 to 8 to create additional styles for the theme.

10 To create a new theme, right-click Themes, and choose New Theme.

How to associate a library with a template

1 If the BIRT resource folder is not the current project folder, place the library in the BIRT resource folder, so that it is available to the template. To specify a folder as the resource folder:

1 Choose Window➛Preferences.

2 In Preferences, expand Actuate BIRT, then choose Resource, as shown in Figure 3-7.

Figure 3-7 Specifying the location of the resource folder in Preferences

3 Choose File System to select a folder to use as the resource folder.

4 On Directory Selection, navigate to a folder on your computer or on the network, or choose Make New Folder to create a new folder.

5 Choose OK to confirm your folder selection. Preferences displays the path to the resource folder.

6 Choose OK to save the resource folder location information, and close the Preferences window.


7 In the layout editor or Navigator, select the library, then choose File➛Copy Library to Shared Resource Folder. Share Library displays the library name and the location of the resource folder.

8 Choose Finish to confirm placing a copy of the library in the resource folder.

2 Open the template file, and choose Outline view.

3 In Outline view, right-click Libraries, and choose Use Library, as shown in Figure 3-8.

Figure 3-8 Choosing Use Library in the template file’s outline view

4 In Use Library, expand Shared Resources to display the libraries in the BIRT resource folder. Figure 3-9 shows an example of Use Library.

Figure 3-9 Displaying libraries in the resource folder

5 Select the library that contains the themes you want to use with the template, then choose OK.

Publishing a templateTemplates must be published in specific locations. Otherwise, Report Studio cannot display the templates. Report Studio displays templates by categories. The default user interface has only one category named Standard. When you publish


a template, you can create a new category or select an existing category in which to display your template.

If you create and publish a wide variety of templates, you can organize the templates into different categories. You can, for example, organize templates by report types (budget reports, expense reports, stock purchase plan reports) or by departments in your organization (Human Resources, Sales, Customer Support).

Figure 3-10 shows an example of Report Studio customized to display three template categories by report types.

Figure 3-10 Displaying template categories on Report Template

The Standard category appears at the top of the list because it is the default category supplied with Report Studio. All other categories that you create are listed in alphabetical order. You can designate a different template category as the default category. This task is described later in this section.

Templates must be published to the \<Server resource folder>\BizRDRptTemplates folder on the Actuate BIRT iHub Encyclopedia volume. The general steps are:

1 Use the default resource folder, named Resources, at the root level of the Encyclopedia volume.


2 Publish the template, using Actuate BIRT Designer Professional. The first time you publish a template, the BizRDRptTemplates folder is created within the Encyclopedia volume’s resource folder. Do not change the name of the BizRDRptTemplates folder. Report Studio looks for templates in this folder, and the folder name is not configurable.

Each of these steps is described in detail in this section.

How to create a resource folder on an Encyclopedia volume

1 Log in to Visualization Platform client as Administrator.

2 Create a new folder that you can designate as the resource folder.

3 Choose Manage Volume, as shown in Figure 3-11.

Figure 3-11 Specifying the Encyclopedia volume’s resource folder

4 On the General Properties page, in Resource folder, specify a resource folder name. The default resource folder name, Resources, appears in Figure 3-11.

How to publish a report template

1 In Actuate BIRT Designer Professional, in Navigator, right-click the template file, then choose Publish Templates to Server. Publish Templates appears with the template file selected, as shown in Figure 3-12.


Figure 3-12 Publish Templates

2 On Publish Templates, select a server profile from the drop-down list. A server profile specifies the connection properties to connect to a specific Encyclopedia volume. If there is no appropriate profile, create a new profile:

1 Choose Add.

2 Specify the connection information in New Server Profile:

1 In Profile name, type a unique name that identifies the new profile.

2 In Server, type the name or IP address of the computer on which Actuate BIRT iHub is installed.

3 In Port number, type the number of the port to access Actuate BIRT iHub.

4 In Volume, select the Actuate BIRT iHub Encyclopedia volume.

5 In User name, type the user name for accessing the volume.

6 In Password, type the password for accessing the volume.

3 Choose Finish to save the Server profile.

3 On Publish Templates, in Template Category, select an existing category from the drop-down list in which to publish the template. Alternatively, create a new category by choosing Browse, then specifying the name of the new category.

4 In Version, select the desired versioning option. To copy the privileges from the last published version of the template, select Copy permissions from last version.

5 Choose Publish Files, then choose Close after the file is published.


The first time you publish a template to an Encyclopedia volume, you must grant users access to the appropriate template folders and files. For more information about assigning privileges for folders and files on an Actuate BIRT iHub Encyclopedia volume, see Managing Groups and Volumes.

Setting the default template categoryBy default, the Report Template dialog displays the templates in the predefined category, Standard, as shown earlier in Figure 3-10. To view and select a template in another category, the user has to select a different category from the Category drop-down list. Typically, you want to make your custom templates more visible. You can configure Report Studio so that the Report Template dialog displays a different category of templates by default.

How to set the default template category

1 Open web.xml for editing. This file is in:


2 Change the value of the DEFAULT_REPORT_TEMPLATE_CATEGORY_NAME parameter from Standard to the name of the category whose templates you want the Report Template dialog to display by default. The following example shows the Sales category set as the default template category:

<param-name>DEFAULT_REPORT_TEMPLATE_CATEGORY_NAME</param-name>

<param-value>Sales</param-value>

3 Restart the appropriate Windows service for the change to take effect.

Publishing resources associated with a templateTypically, each template uses the following external resources that you must also publish to specific locations:

■ An image file that provides the user with a thumbnail image of the template

■ A library file that contains the themes the user can select to apply to the report

If a template contains localized text and you have created resource files that translate text into different languages, you must also publish these resource (.properties) files. You publish resources used by a template to the resource folder in the Actuate BIRT iHub Encyclopedia volume. The process to create and designate an Encyclopedia volume resource folder is described earlier in this section.


How to publish resources associated with a template

1 Using the file system, copy the files to the BIRT resource folder (a different location from the Actuate BIRT iHub Encyclopedia volume resource folder). The location of the BIRT resource folder is specified in the Preferences page, which you access by choosing Window➛Preferences, then choosing Actuate BIRT➛Resource.

2 Choose File➛Publish➛Publish Files.

3 On Publish Files, in Publish Files, type the resources folder path in the Destination dialog box, and then select the files to publish as resources.

4 Select the check box next to Publish Resources and select the resources to publish as resources. Publish Files displays the files to publish as resources, as shown in Figure 3-13.

pFigure 3-13 Selecting files for publishing to a specified iHub volume

5 Select the files to publish.


6 In Server profile, select the profile that specifies the connection properties to the Encyclopedia volume where you want to publish the files. Publish location displays the name of the Actuate BIRT iHub Encyclopedia volume’s resource folder. All BIRT resource files are published to the volume’s resource folder. You cannot change the location. Figure 3-13 shows an example of selections made in Publish Resources.

7 Choose Publish Files, then choose Close after the files are published.

Types of data sourcesTo create a new report, the first step the Report Studio user performs is to select a template on which to base the report. The second step is selecting the data to display. You provide Report Studio users access to data in any of the following ways:

■ Create and publish BIRT data objects.

■ Create and publish report templates that include defined data sets. Use this method if you want to provide templates that combine both presentation and data elements.

■ Create a custom data source and integrate it with Report Studio. Use this method if the data is stored in a proprietary system or if you want to design a custom user interface for selecting data.

This chapter describes all of these methods except creating and publishing report templates that include defined data sets. This method is described in “Providing data with a report template.”

Using data objects as a data sourceA data object can include any number of data sources, data sets, data cubes, and report parameters. The data objects can be used as predefined data sources in BIRT Studio. Business users can select already published data objects as data sources, or templates that are designed to use data objects as data sources.

The data objects created for business reports should be designed with the business report requirements in mind. They should provide the data in a structure that is appropriate for business users and for the report elements that users can add to a report.

When you design data objects for business reports always consider the following:

■ Report parameters in a data object do not link to parameters created in Report Studio, so you typically do not include report parameters in a data object that you create for Report Studio users.


■ In Report Studio, a chart uses data from a table in a report. The chart does not use data directly from a data set or a cube.

■ Report Studio cross tab reports require specialized cross tab templates and the data sources used in the templates must be data objects.

Deploying data objectsThere are two types of data objects, and either one can be a data source:

■ Data object designA data object design specifies a data source and a data set and data cubes. A report developer or data modeler creates the data object design in BIRT Designer Professional. A data object design has a .datadesign extension.

■ Data object storeA data object store contains the materialized data generated by a data object design. A volume administrator creates the data object store in iHub Visualization Platform client configuration. A data object store has a .data extension.

If the user uses a data object design as a data source, the report retrieves data from databases and other data sources when it runs. The advantage of this approach is that the report retrieves current data. The disadvantage is that it increases the load on production databases.

If the user uses a data object store as a data source, the report retrieves materialized data from the data object store when it runs. The advantage of this approach is that it does not increase the load on production databases. The disadvantage is that the report may not retrieve current data.

A volume administrator controls which users have access to data objects by assigning privileges on the .datadesign and .data files. If the volume administrator does not want to increase the load on production databases, they can give users access to .data files but not .datadesign files.

To deploy a data object, a report developer, data modeler, and volume administrator cooperate in performing the following tasks:

■ A report developer or data modeler creates a data object design in BIRT Designer Professional.

■ The report developer or data modeler places the .datadesign file in the BIRT Resource folder.

■ The report developer or data modeler publishes the .datadesign file to the iHub /Resources folder.

■ A volume administrator schedules a job for the .datadesign file that generates a .data file.


■ A volume administrator assigns privileges for the appropriate users on the .datadesign and .data files. To give a user access to a .datadesign file, assign read and execute privileges. To give a user access to a .data file, assign read privilege.

Deploying cross tab templatesWhen a user creates a cross tab report, they must use a template that contains a cross tab element. The cross tab template that installs with iHub resides in <iHub install directory>\modules\BIRTiHub\iHub\Jar\BIRT\platform\plugins\org.eclipse.birt.resources_4.2.3.v20131216-0430\templates\crosstab.rpttemplate. A template developer can modify this template or create their own.

Creating data objectsA data object is a BIRT object that contains all the information necessary to connect to an external data source, retrieve data from that data source, and structure the data in a way that supports business analysis. A data object is a collection of the following BIRT objects:

■ Data sources

■ Data sets

■ Data cubes

A data object can include any number of data sources, data sets, and data cubes. Data objects enable Report Studio users to focus on the data to present in a report, rather than focusing on how to obtain the data. Building a data object entails creating a data object file, then adding data sources, data sets, and cubes to the data object.

Building a data objectBuilding a data object entails creating a data object file, then adding data sources, data sets, and cubes to the data object.

How to create a data object

1 In the Report Design perspective, choose File➛New➛Data Object.

2 In New Data Object, do the following:

1 Select the folder in which to store the data object and choose next.


2 Edit the default file name to specify a new name. The extension must be .datadesign and the file name must not contain the following characters:

[ ] * / \ : & ?

Use a descriptive name that enables users to determine the contents of the data object. A descriptive name is particularly important if users have access to multiple data objects.

3 Choose Finish. The report editor displays a blank data object design, as shown in Figure 3-14.

Figure 3-14 Displaying a blank data object design

3 Add data sources, data sets, and cubes to the data object.

Deploying data objectsData object files must reside in a project’s Shared Resources folder. By default, a project’s Shared Resources folder is the project folder. If the Shared Resources folder is not the project folder, you must copy data object files to the Shared Resources folder before publishing. To check the location of the Shared Resources folder, in BIRT Designer Professional, choose Window➛Preferences and then Actuate BIRT➛Resource.

When you publish data object files to an Encyclopedia volume, the files are published to the IO Designs folder in the Encyclopedia volume’s resource folder. The resource folder’s default location is /Resources. You must have write privilege on the resource folder.


How to copy data object files to the shared resources folder

1 In Navigator, select the appropriate .datadesign or .data file.

2 Choose File➛Copy to Resources➛Copy Information Objects to Shared Resources Folder.

3 In Share Data Object, shown in Figure 3-15, type the name of the destination file and select any subfolder of the resource directory by choosing Browse.

Figure 3-15 Copying a data object file to Shared Resources

4 Choose Finish.

How to publish data object files as resources

1 Choose File➛Publish➛Publish Files.

2 In Publish Files, in Server profile, choose an server profile from the drop-down list.

3 In Project, select the appropriate project from the drop-down list.

4 Select Publish Resources.

5 Select the appropriate files and folders, as shown in Figure 3-16.

Figure 3-16 Publishing data object files as resources

6 In Version:

1 Select Replace the latest version to replace the latest version of each file, or Create a new version to create a new version of each file.

2 To copy permissions from the last version of each file, select Copy permissions from last version. If you do not select Copy permissions from


last version, you must set the permissions for each file using Visualization Platform.

7 Choose Publish Files.

A confirmation dialog, shown in Figure 3-17, appears.

8 In Publishing, choose OK.

9 In Publish Files, choose Close.

Figure 3-17 Publishing confirmation dialog

Creating a custom data sourceAnother way to provide users access to data is to create a custom user interface to a data source and integrate the user interface with Report Studio. BIRT Studio supports the usage of BIRT and custom data sources. There are three supported scenarios you can implement:

■ You use a BIRT JDBC data source, and the out-of-box functionality to configure the user interface for selecting the data.

■ You use a BIRT driver to connect to your data source. You create your own user interface for selecting the data. This scenario is appropriate in all cases when your data source is not a BIRT JDBC data source, but it is still supported by BIRT, such as XML, Web Services, etc.

■ You use your own custom ODA driver to connect to your data source and you build your own user interface for selecting the data.

Actuate provides two examples that reference the supported scenarios:

■ Sample ODA data source. The example demonstrates how to configure a user interface for selecting data when using the BIRT JDBC driver.

■ Extended sample ODA data source. The example creates a custom user interface for selecting data and uses a BIRT driver to connect to the data source.

Sample ODA data sourceCreating a custom user interface to connect to a BIRT JDBC data source does not require additional coding. You must configure the data source and data set and describe the data set columns in the erni_config.xml file, as shown in Listing 3-5.

Listing 3-5 Configuring the sample data source in erni_config.xml

<odaconfig><name>OdaSample</name><displayName>Sample ODA data source</displayName><description>A sample ODA data source</description>

<datasourceExtensionId>org.eclipse.birt.report.data.oda.jdbc</datasourceExtensionId><datasourceDisplayName>CLASSICMODELS</datasourceDisplayName>

<datasetExtensionId>org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet</datasetExtensionId><datasetDisplayName>CLASSICMODELS.PAYMENTS</datasetDisplayName>

<odaDriverClass>org.eclipse.birt.report.data.oda.sampledb.Driver</odaDriverClass><odaURL>jdbc:classicmodels:sampledb</odaURL><odaUser>ClassicModels</odaUser>



<odaColumns><odaColumn><name>CUSTOMERNUMBER</name><dataType>INTEGER</dataType></odaColumn><odaColumn><name>PAYMENTDATE</name><dataType>DATE</dataType></odaColumn><odaColumn><name>CHECKNUMBER</name><dataType>STRING</dataType></odaColumn><odaColumn><name>AMOUNT</name><dataType>FLOAT</dataType></odaColumn>

</odaColumns><dataObject>CLASSICMODELS.PAYMENTS</dataObject><enabledInWorkgroupMode>true</enabledInWorkgroupMode>


<enabledInEnterpriseMode>false</enabledInEnterpriseMode><entryPoint></entryPoint>

</odaconfig>

To test the sample ODA data source with Report Studio, you must first enable the data source, named OdaSample, by setting the data source’s <enabledInEnterpriseMode> attribute in erni_config.xml to true. The erni_config.xml file is stored in the following location:


Typically, in standard installations the <context root> is as follows:

<ACTUATE_HOME>\BIRTiHubVisualization\modules\BIRTiHub\iHub\web\iportal

After you enable the sample data source, restart the appropriate Windows service for iHub or Visualization Platform client, and open Report Studio. When prompted, select one of the standard report templates. The Data Source dialog box, as shown in Figure 3-18, prompts you to select a data source. Select Sample ODA data source.

Figure 3-18 Selecting a data source

Based on the XML definition in erni_config.xml, the product displays a sample ODA editor with a table, containing the configured database columns, as shown in Figure 3-19.

Figure 3-19 Selecting data in the sample ODA editor


The check boxes appearing next to the column names allow the user to select the data for the report. The editor gives the user ability to create a parameter for filtering the data in the last column.

Table 3-1 lists all the configuration attributes and their descriptions.

Table 3-1 Attributes of a sample ODA data source

Attribute Description

<name> The unique name of the data source. This name follows certain naming conventions. There can be no spaces, for example.

<displayName> The data source name that appears in the Data Source dialog box, as shown in Figure 3-18.

<description> The data source description that appears in the Available Data pane.

<datasetExtensionId> Identifies the ID of the data set extension of the data driver.

<datasourceDisplayName> The display name of the data source.

<datasourceExtensionId> Identifies the ID of the data source extension of the data driver.

<datasetDisplayName> The display name of the data set.

<odaURL> The database URL to use to connect to the data source.

<odaUser> The user name, used to connect to the database.

<odaPassword> The database password.

<odaColumn><name> The name of the database column to be included in the user interface.

<odaColumn><dataType> The type of the database column. Can be one of the following:DECIMAL(3), INTEGER(4), FLOAT(6),

DATE-TIME(93),DATE(91), TIME(92), BOOLEAN(16), STRING(12)

<dataObject> The name of the database table if single table is used.

<queryText> The text of the query if the columns are from different tables.

<enabledInWorkgroupMode> Not used.

<enabledInEnterpriseMode> Indicates whether this data source is available to users.

<entryPoint> A URL or servlet that points to the first web page of your custom query builder.


Configuring the ODA data source requires knowledge about your JDBC data source and data set. If you do not know this information, you can obtain the database connection properties from your database administrator. It is a good practice to create first a sample report in BIRT Designer Professional and validate the connection and the database query. You use the XML source of the created report to identify the correct values for the sample ODA configuration. Look for the attribute values in the <data-sources> and <data-sets> tags at the beginning of the report XML.

Listing 3-6 shows portions of the report XML that contain the configuration attributes and their values.

Listing 3-6 Report XML source

<data-sources><oda-data-source extensionID="org.eclipse.birt.report.data.oda.jdbc" name="Data Source" id="7">…<property name="odaDriverClass">org.eclipse.birt.report.data.oda.sampledb.Driver</property><property name="odaURL">jdbc:classicmodels:sampledb</property><property name="odaUser">ClassicModels</property></oda-data-source>

</data-sources><data-sets> <oda-data-set extensionID=

"org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet" name="Data Set" id="8">…<xml-property name="queryText"><![CDATA[select *from CLASSICMODELS.PAYMENTS]]></xml-property>

Extended sample ODA exampleTo implement an extended custom data source, you perform the following programming and configuration tasks:

■ Develop an open data access (ODA) data driver to connect to and retrieve data from a data source.

■ Develop a query builder that prompts the user to select data, processes the user’s selection, and creates the query to get the data.

■ Configure the custom data source for use with Report Studio.

An example of an extended ODA data source installs with Report Studio. The data source accesses data from an integrated sample database named ClassicModels. To test this custom data source with Report Studio, you must first


enable the data source, named OdaSampleExt, by setting the data source’s <enabledInEnterpriseMode> attribute in erni_config.xml to true. The erni_config.xml file is stored in the following locations:

<ACTUATE_HOME>\BIRTiHubVisualization\modules\BIRTiHub\iHub\web\iportal\WEB-INF

Listing 3-7 shows in bold the <enabledInEnterpriseMode> attribute whose value you change from false to true. Look for the ODA data source named OdaSampleExt.

Listing 3-7 Configuring the extended sample data source in erni_config.xml

<odaconfig><name>OdaSampleExt</name><displayName>Extended sample ODA data source</displayName><description>An extended sample ODA data source</description><datasourceExtensionId>org.eclipse.birt.report.data.oda.jdbc</datasourceExtensionId><datasetExtensionId>org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet</datasetExtensionId><enabledInWorkgroupMode>true</enabledInWorkgroupMode><enabledInEnterpriseMode>true</enabledInEnterpriseMode><entryPoint>/OdaSample</entryPoint>

</odaconfig>

After you enable the extended sample data source, restart the appropriate Windows service, and open Report Studio. When prompted, select one of the standard report templates. The Data Source dialog box, as shown in Figure 3-20, prompts you to select a data source. Select Extended sample ODA data source.

Figure 3-20 Selecting a data source

A query builder page, as shown in Figure 3-21, prompts you to select the data to use in the report.


Figure 3-21 Building a query

After you select the data and choose OK, the query builder closes, and the data you selected appears under Available Data, as shown in Figure 3-22.

Figure 3-22 Selected data appears under Available Data

Developing an open data access (ODA) data driverYou develop an ODA data driver by implementing run-time interfaces that the ODA framework defines. The ODA framework is an Eclipse Data Tools Platform (DTP) project component that provides a way for an application to access data from standard and proprietary data sources. For information about ODA and developing data drivers, go to the following site:

http://www.eclipse.org/datatools/project_connectivity/connectivity_doc/OdaOverview.htm

Another resource is Addison-Wesley’s Integrating and Extending BIRT book. Actuate also provides an example about how to develop a flat file ODA driver. You can find the source code for this example in:

<ACTUATE_HOME>\oda\examples\FlatFileExample

The extended data source example uses a predefined ODA JDBC driver to connect to the ClassicModels sample database. The source code for this driver


(org.eclipse.birt.report.data.oda.jdbc) is available in the Eclipse DTP CVS repository.

After you develop a custom ODA driver, you must copy the driver to the following folders, depending on the deployment environment:

In iHub:

<ACTUATE_HOME>\iHub2\MyClasses\eclipse\plugins

In Visualization Platform client:

<ACTUATE_HOME>\MyClasses\eclipse\plugins

Developing a custom query builderYou develop a query builder using standard web application components, JavaServer Pages (JSPs) and servlets. After creating the necessary components, you perform a series of tasks to integrate the components with Visualization Platform client. This section describes the sample query builder, on which you can base your own query builder. This section also describes the procedures for compiling and deploying your own query builder components.

The sample query builder consists of the following components:

■ ClassicModelQueryBuilder.jsp. This JSP displays the page in Figure 3-21. It also contains JavaScript functions to build the string that contains information about the data that the user selected and to send the request to a servlet. To view the code, see ClassicModelQueryBuilder.jsp in the following location:

<context root>\bizRD\oda\sample

■ SampleServlet.java. This servlet communicates with ClassicModelQueryBuilder.jsp, creates a design session, and creates the query using information from the JSP. To view the code, see SampleServlet.java in the following location:

<context root>\iportal\examples\oda\classes\com\actuate\erni\oda\ClassicModels

Creating the servletA servlet performs the main tasks for getting and managing data for Report Studio users, and it is the key piece of any custom query builder. The example servlet, SampleServlet.java, extends the HTTPServlet class, and performs the following tasks:

■ Manages design sessions for concurrent Report Studio users

■ Uses ODA API to define the basic methods for constructing a query, result set, and column objects


■ Processes the information sent by ClassicModelQueryBuilder.jsp, and creates a query

■ Returns dynamic content that appears in Available Data, as shown in Figure 3-22

The servlet contains declarations of the ODA data driver’s data source and data set extensions:

private final static String Datasource_Extension_Id = "org.eclipse.birt.report.data.oda.jdbc";

private final static String Dataset_Extension_Id = "org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet";

These extension IDs are used to construct the definitions of the data source connection and data set query in the report design.

The servlet supports the GET method only. Its doGet method retrieves request parameters, creates a unique ODA design session, and stores a session ID in the ODA session, so that other requests in the same session can access the same ODA session object. In any given session, the servlet can receive multiple requests with different parameter values. Table 3-2 describes the supported parameters.

The servlet executes a different action, depending on the parameter values. Table 3-3 describes the actions taken with the different inedit and state values.

Table 3-2 Session request parameters

Parameter Description

inedit Indicates whether the user has started editing the values on the query builder page. Values are null or true.

state Shows the editing status. Values are null, ok, or cancel.

selection Contains information about the selected data fields.

sessionId Contains the session ID.

Table 3-3 Actions corresponding to inedit and state values

inedit value state value Action

null any Generates a new session ID. Stores the ID and the callback URL in the session map. Changes the inedit parameter to true and sends a response to the calling page.

not null null Redirects the response to ClassicModelQueryBuilder.jsp.

(continues)


Compiling the servletAfter you develop your servlet, you must compile the class. You can use a javac compiler from the command prompt or any Java IDE, such as Eclipse. To compile a servlet class, the following JAR files must be in your Java classpath:

■ com.actuate.iportal.jar

■ org.eclipse.emf.common.jar

■ org.eclipse.emf.ecore.jar

■ org.eclipse.datatools.connectivity.oda.design.jar

These files are in the following location:

<context root>\WEB-INF\lib

■ servlet.jar

You can find this file in different places, depending on the Actuate products installed on your computer. For example, servlet.jar can be found in the following location:

<ACTUATE_HOME>\iHub\servletcontainer\webapps\acrsse\WEB_INF\lib

Deploying the servletAfter you compile the servlet class, deploy the servlet to your application. You can deploy your servlet as a class file, or packaged as a JAR file. The SampleServlet.class servlet is deployed to your application packaged in iportal.jar.

If you deploy the servlet using a JAR file, copy the JAR file to the following location:

<context root>\WEB-INF\lib

not null ok The user has finished selecting data fields. The servlet deletes the session ID, and parses the value in the selection parameter to build the query. The response is redirected to a Report Studio page.

not null cancel The user cancelled out of the query builder page. The servlet deletes the session ID.

Table 3-3 Actions corresponding to inedit and state values (continued)

inedit value state value Action


If you deploy the servlet as a class file, copy the servlet class to the following location:

<context root>\WEB-INF\classes

Registering the servletAfter you compile your servlet, you also need to register the servlet with the web application. To register the servlet, you add two entries to web.xml, which is stored in the following location:


The first entry, under the <servlet> element, defines a name for the servlet and specifies the compiled class that executes the servlet. The following example shows the <servlet> entry for the sample servlet:

<servlet><servlet-name>OdaSampleServlet</servlet-name><servlet-class>com.actuate.erni.oda.ClassicModels.SampleServlet</servlet-class>

</servlet>

The second entry, under the <servlet-mapping> element, defines the URL pattern that calls this servlet. The following example shows the <servlet-mapping> entry for the sample servlet:

<servlet-mapping><servlet-name>OdaSampleServlet</servlet-name><url-pattern>/OdaSample</url-pattern>

</servlet-mapping>

Configuring the extended custom data sourceAfter you finish developing all the components of a custom data source, you configure the data source for use with Report Studio. Data sources available to Report Studio are defined in the following configuration file:

<context root>\WEB-INF\erni_config.xml

Listing 3-7 shows the definition of the extended sample data source. To add your custom data source, create a new <odaconfig> element in erni_config.xml. Table 3-4 describes each attribute, within the <odaconfig> element, that you configure.


Table 3-4 Attributes of an extended custom data source

Attribute Description

<name> The unique name of the data source. This name follows specific naming conventions. There can be no spaces, for example.

<displayName> The data source name that appears in the Data Source dialog box, as shown in Figure 3-18.

<description> The data source description that appears in the user interface.

<datasetExtensionId> Identifies the ID of the data set extension that was created in the ODA data driver. The value should match the data set extension ID that is specified in the servlet.

<datasourceExtensionId> Identifies the ID of the data source extension that was created in the ODA data driver. The value should match the data source extension ID that is specified in the servlet.

<enabledInWorkgroupMode> Not used.

<enabledInEnterpriseMode> Indicates whether this data source is available to users.

<entryPoint> A URL or servlet that points to the first web page of your custom query builder.

C h a p t e r 6 , C o n f i g u r i n g B I R T V i e w e r 121

C h a p t e r

6Chapter 6Configuring BIRT Viewer

This chapter contains the following topics:

■ Configuring the Actuate BIRT Viewer toolbar using iv_config.xml

■ Configuring Actuate BIRT Viewer using web.xml

■ Configuring default export formats

■ Configuring a BIRT Viewer Java extension


Configuring the Actuate BIRT Viewer toolbar using iv_config.xml

Actuate BIRT Viewer provides a toolbar and context menus that support many of the formatting, sorting, and grouping tasks you perform on data. The toolbar and menus also support adding or deleting columns or groups, and working with fonts and text alignment. You also can print reports and export content or data. Enable or disable each of these features using the configuration file iv_config.xml. Its location is:

<context root>\WEB-INF\iv_config.xml

The iv_config.xml file contains lists of features that are enabled or disabled. The following section of iv_config.xml shows the default feature control for all users

<FeatureControl><Role>All/Role><Features>

<Feature><FeatureName>SaveDesign</FeatureName><Availablity>true</Availablity>

</Feature><Feature>

<FeatureName>SaveDocument</FeatureName><Availablity>true</Availablity>

</Feature>…

</Features></FeatureControl>

All <FeatureControl> tags are placed within the <FeatureConfiguration> element. Each feature is described by the <Feature> tag, and its availability is described with the <Availability> tag. If a particular feature is available, availability is set to true. If the feature is not available, it is set to false. The parameter value in the <Role> tag corresponds to a user group and role configured in the functionality-level.config file. Interactive Viewer checks whether a role is specified in functionality-level.config before applying an iv_config.xml configuration to a user group, and custom roles must exist in both files for iv_config.xml configuration to apply. For more information on setting up user group configurations using functionality-level.config, see “Restricting access to Actuate Visualization Platform client features using functionality levels.”

Exception stack trace display is also controlled in the iv_config.xml file. When an exception occurs, the viewer can display a stack trace can be displayed in the exception dialog. The trace is used for support purposes, and is set to false by default. This value is not associated with user roles and is placed outside the

<FeatureControl> tag. The format of the iv_config.xml file appears as shown in the following code:

<IVConfig> <RunningMode>Iportal</RunningMode>  <ExportNameConfig>

com.actuate.iv.utility.filename.DefaultFileNameGenerator</ExportNameConfig><FeatureConfiguration>

<FeatureControl>

…</FeatureControl><FeatureControl>

…</FeatureControl>…

</FeatureConfiguration></IVConfig>

Table 3-1 lists the features that can be set, and how the availability tag affects them.

Table 3-1 Actuate BIRT Viewer feature set

Feature Availability tag description

AdvancedSort Shows or hides the Advanced Sort item in the context menu

Aggregation Shows or hides the Aggregation item in the context menu

Analyze Enables or disables the Analyze item in the cross tab toolbar and context menu

AutoEnableIV Enables or disables interactivity by default

CalculatedColumn Shows or hides the New Computed Column and Edit Computed Column items in the context menu

ChartSubType Shows or hides the Chart Subtype item in the context menu

ChartProperty Shows or hides the Chart Property item in the context menu

(continues)


ColumnEdit Shows or hides the Hide Column, Show Column, and Delete Column items in the context menu

CollapseExpand Shows or hides the Hide Detail and Show Detail items in the context menu

ColumnResize Shows or hides the Column Width item in the context menu

ConditionalFormat Shows or hides the Conditional Formatting item in the context menu

EditReport Shows or hides the Enable Interactivity item in the toolbar main menu

ExportData Shows or hides the Export Data menu item in the toolbar main menu

ExportElement Shows or hides the Export Content menu item in the context menu

ExportElementData Shows or hides the Export Data menu item in the context menu

ExportReport Shows or hides the Export Content menu item in the toolbar main menu

FacebookComments Shows or hides the Facebook Comment menu item in the toolbar main menu

FlashGadgetFormat Shows or hides the Format Flash Gadget item from the gadget context menu

FlashGadgetType Shows or hides the Change Type from the gadget context menu

Filter Shows or hides the Filter item in the context menu

Format Shows or hides the Format, Change Font, and Alignment items in the context menu

GrandTotal Enables or disables the Grand Total option in the aggregation dialog

GroupEdit Shows or hides the Move To Group, Add Group, and Delete Group items in the context menu

HideShowItems Shows or hides the Hide/Show Item menu item in the toolbar main menu

Highlight Shows or hides highlighting

HoverHighlight Shows or hides the mouse over rectangles on page elements

Table 3-1 Actuate BIRT Viewer feature set (continued)



LinkToThisPage Shows or hides the Link To This Page item in the main menu

MainMenu Enables or disables the toolbar’s main menu

MoveColumn Shows or hides the Move to Left and Move to Right items in the context menu

PageBreak Shows or hides the Page Break item in the context menu

PageNavigation Shows or hides the page navigation icons in the navigation bar

Parameter Shows or hides the Parameter item in the toolbar

Print Shows or hides the Print menu item in the toolbar main menu

Resize Enables or disables the Resize feature

ReorderColumns Shows or hides the Reorder Columns item in the context menu

SaveDesign Shows or hides the Save Design menu item in the toolbar main menu

SaveDocument Shows or hides the Save Document menu item in the toolbar main menu

ScrollControl Shows or hides the scroll control panel in page content

ServerPrint Shows or hides the Server Print menu item in the toolbar main menu

ShareFormat Shows or hides the Copy Format menu item in the context menu

ShareStyle Shows or hides the Copy Style menu item from the context menu

ShowTooltip Shows or hides tooltips

Sort Shows or hides the Sort Ascending and Sort Descending items in the context menu

SubTotal Enables or disables the SubTotal option in the aggregation dialog

SuppressDuplicate Shows or hides the Repeat Values and Do Not Repeat Values items in the context menu

SwitchView Shows or hides the Switch View item in the context menu

(continues)




Configuring Actuate BIRT Viewer using web.xmlActuate BIRT Interactive Viewer (IV) parameters in web.xml affect how BIRT reports are run and viewed. Table 3-2 describes these configuration parameters for BIRT reports, BIRT Viewer, and Interactive Viewer.

Toc Shows or hides the TOC menu item in the toolbar main menu

TextEdit Shows or hides the edit text icon on text elements

Toolbar Shows or hides the toolbar

ToolbarHelp Shows or hides the toolbar Help menu item

TopBottomNFilter Shows or hides the Top/BottomN item in the context menu



Table 3-2 Actuate BIRT Viewer web.xml parameters


ALLOW_EXPORT_PAGE_LIMIT

Indicates the maximum number of pages that can be exported or printed at a time from Actuate BIRT Viewer. For example, if the value of this parameter is 200, no more than 200 pages will be exported or printed from a report using the viewer.

ALLOW_IV_PAGE_LIMIT Specifies whether Visualization Platform client checks for a page limit before triggering an operation.

AUTOSUGGEST_DELAY Configure the delay before the parameters page opens an automatic suggestion for a parameter. The value is measured in milliseconds, and the default value is 500.

AUTOSUGGEST_FETCH_SIZE

The number of autosuggest parameter values to load on the parameters page. The default value is -1, which loads all values.

AUTOSUGGEST_LIST_SIZE

The number of autosuggest parameter values to display on the Parameters page when active. If more values exist than are displayed, the user can scroll through the other values. The default value is 10.

BIRT_ARCHIVE_ MEMORY_TOTALSIZE

The total memory available for BIRT report document files, in kilobytes. The default value is 50 megabytes.

BIRT_CHART_CONVERT_TO_IMAGE_TIME_OUT

Sets the time out for conversion from chart to image in a BIRT report. The default value is 6.


BIRT_CHART_MAX_ROW The maximum number of rows bound to a chart in a BIRT report. The default value is 10000 rows.

BIRT_CHART_MAX_VARIABLE_SIZE

The maximum size for a variable used in a Flash chart, measured in bytes. The default value is 0, which allows a variable to be of any size.

BIRT_CUBE_FETCH_LIMIT_COLUMN_EDGE

The maximum column limit for accessing a data cube. The value must be a non-negative integer; 0 indicates no limit.

BIRT_CUBE_FETCH_LIMIT_ROW_EDGE

The maximum row limit for accessing a data cube. The value must be a non-negative integer; 0 indicates no limit.

BIRT_DATA_RESULTSET_MAX_BUFFER_SIZE

The result set buffer size, in megabytes, for a data set in a BIRT report. The default value is 10 megabytes.

BIRT_HTMLRENDEROPTION_ENGCASSTYLE

Enables the agentStyleEngine property for the HTML render option for a BIRT report. This setting is related to using a browser’s internal CSS capabilities when rendering reports in HTML. It provides better column alignment and faster rendering, especially in a browser other than Microsoft Internet Explorer. The default value is true.

BIRT_JDBC_CONNECTION_POOL_SIZE

Specifies the number of idle connections cached by BIRT JDBC connection pool. The default value is 10.

BIRT_JDBC_CONNECTION_POOL_TIMEOUT

Specifies how long an idle connection will remain in the BIRT JDBC connection pool in seconds. The default value is 3600.

BIRT_LINKED_DATA_MODEL_DATA_MODEL_SIZE

Sets an upper limit on data loaded into memory by a data model at runtime, measured in megabytes. The default value is 0.

BIRT_RESOURCE_PATH The path to Actuate BIRT shared resources, including libraries and templates for the BIRT report designs and BIRT Studio. The default value is <context root>\resources.

BIRT_SCRIPT_LIB_PATH Path for the BIRT script libraries (JARs). The default value is <context root>\scriptlib.

BIRT_VIEWER_LOCALE Locale that determines formatting for numbers and dates on BIRT reports. The default value is the locale of the machine on which Visualization Platform client is installed.

(continues)

Table 3-2 Actuate BIRT Viewer web.xml parameters (continued)



CACHE_CONTROL Specifies how a web browser caches information using one of the following values:■ NO-CACHE indicates that the browser does not cache

information and forwards all requests to the server. With NO-CACHE, the back and forward buttons in a browser do not always produce expected results, because choosing these buttons always reloads the page from the server.If multiple users access Visualization Platform client from the same machine, they can view the same cached data. Setting CACHE_CONTROL to NO-CACHE prevents different users viewing data cached by the browser.

■ NO-STORE indicates that information is cached but not archived.

■ PRIVATE indicates that the information is for a single user and that only a private cache can cache this information. A proxy server does not cache a page with this setting.

■ PUBLIC indicates that information may be cached, even if it would normally be non-cacheable or cacheable only within an unshared cache.

■ UNSET (no value) is the default value. The browser uses its own default setting when there is no CACHE_CONTROL value.

Caching information reduces the number of server requests that the browser must make and the frequency of expired page messages. Caching increases security risks because of the availability of information in the cache. For additional information about cache control, see the HTTP/1.1 specifications.

DEFAULT_LOCALE The default locale. The default locale is en_US. Users can select a locale when they log in.

DEFAULT_TIMEZONE The default time zone. The default time zone is Pacific Standard Time (PST).

DISPLAY_ATTRIBUTE_ITEM

Sets whether to collapse attribute nodes in the dimension tree. False sets nodes to collapse; True sets nodes to expand. The default value is false.




EXPORT_AS_ATTACHMENT

Determines whether a Microsoft Excel, PowerPoint, or Word report for BIRT Viewer is opened in the Microsoft Internet Explorer browser or a separate application.■ When the value is true, the exported report opens in a

separate Microsoft Word, Microsoft PowerPoint, or Microsoft Excel application.

■ When the value is false, the exported report opens in the browser window with Microsoft Word, Microsoft PowerPoint, or Microsoft Excel embedded inside the browser.

The Firefox browser always opens these report formats in a separate application.

IV_ENABLE_IV Determines whether the Enable Interactivity option is usable in the BIRT Viewer control menu. If false, the Enable Interactivity option is disabled.

JAVA_REPORT_API_IMAGE_CACHE_EXPIRATION

Specifies how long in seconds to cache images for Actuate BIRT reports and business reports. The default value is 86,400, which is one day.

JREM_TASK_QUEUE_SIZE Specifies the maximum queue length for the Java Report Engine thread pool. The default value is 1000.

JREM_THREAD_POOL_SIZE

Specifies the maximum number of threads in the Java Report Engine thread pool. The default value is 10.

JREM_THREADPOOL_MAXSYNC_TASKRUNTIME

Specifies the maximum time a synchronous report generation is allowed to run. The default value is 600.

JREM_THREADPOOL_MONITORTHREAD_POLLINGINTERVAL

Controls the interval in seconds at which the Java Report Engine thread pool checks for Java report execution time-out or queue time-out. The default value is 30.

JREM_THREADPOOL_SYNC_TASKQUEUE_TIMEOUT

Specifies the maximum time, in seconds, that a Java synchronous request stays in the Java Report Engine task queue before timing out, in seconds. The default value is 300.

NUMBER_OF_FILTER_VALUES

Specifies the number of distinct values to display when a user chooses to filter a report on a column in BIRT Viewer. The default value is 200.

DEFAULT_COLUMN_PAGE_BREAK_INTERVAL

Specifies the number of columns to display on one page when viewing a cross tab. Must be a non-negative number. Default value is 10.

(continues)




Configuring default export formatsYou can export a BIRT report to various formats from the BIRT viewer. These formats include doc, docx, pptx, pdf, postscript, ppt, pptx, xls, and xlsx. BIRT iHub and BIRT Designer Professional provide a sample .xml file for each format, which you can use to configure the default export options for that format. For example, you can configure the sample .xml file for the XLSX format to set Enable pivot table if it fits on one page to false by default in Export Content, the dialog that appears when you choose to export a BIRT report to XLSX format, as shown in Figure 3-23.

On BIRT iHub, the location of the folder containing the sample .xml files is:

<BIRT iHub installation folder>\Jar\BIRT\platform\plugins\com.actuate.birt.report.engine.emitter.config_<RELEASE_NUMBER>.v<date_stamp>

On BIRT Designer Professional, the location of the folder containing the sample .xml files is:

<BDPro installation folder>\eclipse\plugins\com.actuate.birt.report.engine.emitter.config_<RELEASE_NUMBER>.v<date_stamp>

Each XML file has the following name:

org.eclipse.birt.report.engine.emitter.<FORMAT_TYPE>.xml


Specifies the number of rows to display in one page when viewing a report. If set to 0, there are no page breaks.

DEFAULT_ROW_PAGE_BREAK_INTERVAL

Specifies the number of rows to display on one page when viewing a cross tab. Must be a non-negative number. Default value is 40.

PROXY_BASEURL Indicates a proxy server’s URL if the network uses one between the BIRT Viewer web application and the client. The default value is blank, which indicates that the network does not use a proxy server.

REPOSITORY_CACHE_TIMEOUT_SEC

Specifies, in seconds, how long to retain temporary files that BIRT Viewer creates when a user modifies the appearance of a report. The default value is 900, which is 15 minutes.


Path to the folder where temporary files are created.



For example, Listing 3-8 shows the XML you can modify in org.eclipse.birt.report.engine.emitter.xlsx.xml, to configure the export options for the XLSX output format.

Figure 3-23 Viewing default export property values on Export Content

Listing 3-8 Sample .xml file content

<RenderOptions><!--

<option name="excelRenderOption.wrappingText" default="true" enabled="true"/>

<option name="ChartDpi" default="192" enabled="true"/><option name="excelRenderOption.ExportChartsAsImages"

default="false" enabled="true"/><option name="excelRenderOption.EnableLiveFormula"

default="true" enabled="true"/><option name="excelRenderOption.hideGridlines" default="false"

enabled="true"/><option name="excelRenderOption.multipleSheet" default="true"

enabled="true"/>


<option name="excelRenderOption.AutoFitPivotTable" default="true" enabled="true"/>

<option name="excelRenderOption.EnablePivotTable" default="true" enabled="true"/>

--></RenderOptions>

The <RenderOptions> element contains the following child elements:

■ <emitter>Specifies whether the output format is a selectable option in Export Content—Export Format. Possible values are true or false. If this element is commented out in the .xml file, the value of <emitter> is true.

■ <option>Represents an export option in Export Content. Contains the following attributes, which support configuring the export option:

■ nameName of the export option. Required.

■ defaultDefault value of the export option. The value of the export option if the user does not change it or if the export option on Export Content is hidden. Required.

■ enableDetermines whether the export option appears on Export Content. If set to true, the option appears. If set to false, the option is hidden. Optional. The value of <enable> is true if this attribute is omitted in the <option> element.

How to configure default document export options

1 Stop the Actuate iHub Service.

2 Modify the .xml file for the export format for which you want to configure default output export options. Table 3-3 lists the default settings parameters for each output format.

3 Start the Actuate iHub Service.

Table 3-3 Configurable default settings for exporting content

Format Option name Permissible values

All formats

ChartDpi Sets the chart resolution. Value can be any integer greater than 0.

DOCX EmbedHtml Permissible values are true or false.


PDF, PostScript

pdfRenderOption.bidiProcessing

Enables bidirectional text support. Permissible values are true or false.

PDF, PostScript

pdfRenderOption.textWrapping

Enables text wrapping. Permissible values are true or false.

PDF pdfRenderOption.hyphenation

Enables splitting words with a hyphen at line breaks. Permissible values are true or false.

PDF, PostScript

pdfRenderOption.fontSubstitution

Enables font substitution for unknown fonts. Permissible values are true or false.

PDF, PostScript

pdfRenderOption.pageOverflow

Controls rendering content when the content exceeds the page size. Integer values indicate the following options:■ 1: clips the content■ 2: scales the content to fit the page■ 4: (default) divides the content into

multiple pages■ 8: expands the page to fit content

PDF pdfRenderOption.embeddedFonts

Embeds fonts in the output document. Permissible values are true or false.

PDF RenderChartInSVG Renders charts as vector graphics. Permissible values are true or false.

PDF repaginateForPDF Permissible values are true or false.

PPT/PPTX BIDIProcessing Enables bidirectional text support. Permissible values are true or false..

PPT/PPTX TextWrapping Enables text wrapping. Permissible values are true or false.

PPT/PPTX FontSubstitution Sets font substitution for unknown fonts. Permissible values are true or false.

XLS/XLSX excelRenderOption.wrappingText

Enables text wrapping. Permissible values are true or false.

XLS/XLSX excelRenderOption.EnablePivotTable

Enables pivot tables. Permissible values are true or false.

(continues)

Table 3-3 Configurable default settings for exporting content (continued)



In BIRT iServer Release 11 Service Pack 4 and BIRT iHub 2, you configured default export options for a particular output format by creating a RenderDefaults.cfg file, and placing it in the JAR file for that output format emitter. The main advantage of configuring export options using an XML file as described in this section is that you do not need to work with a JAR file.

For backward compatibility, Hub 3 supports configuring default export options using a RenderDefaults.cfg file. iHub uses this file if the XML file this section describes does not exist. If neither file exists, iHub uses the default export options specified in the RenderOptions.xml file the format emitter JAR file contains.

Configuring a BIRT Viewer Java extensionThe Actuate BIRT API provides the IBirtViewerExtension, IBirtViewerContext, IBirtViewerOp, and IBirtViewer Session Java interfaces to extend the functionality of BIRT Viewer. These interfaces are part of the com.actuate.birtviewer.extension package. This package is provided in javaserver.jar, which is located in the following folder:

<iHub installation folder>\modules\BIRTiHub\iHub\jar

Classes implementing these interfaces are associated with the BIRT Viewer web application when they are added in the birtviewer-extension.xml configuration file, which is located in the following folder:

<iHub installation folder>\modules\BIRTiHub\iHub\etc

For example, to enable myIVExtension.jar to operate on BIRT Viewer, add an entry to birtviewer-extension.xml as follows:

XLS/XLSX excelRenderOption.AutoFitPivotTable

Enables BIRT Viewer to automatically adjust content for display in pivot tables. Permissible values are true or false.

XLS/XLSX excelRenderOption.ExportChartsAsImages

Renders charts as images only. Permissible values are true or false.

XLS/XLSX excelRenderOption.EnableLiveFormula

Enables formulas for derived values. Permissible values are true or false.

XLS/XLSX excelRenderOption.hideGridlines

Hides grid lines. Permissible values are true or false.

XLS/XLSX excelRenderOption.multipleSheet

Enables multiple worksheet output. Permissible values are true or false.

Table 3-3 Configurable default settings for exporting content (continued)


<?xml version="1.0" encoding="UTF-8" ?> <BirtWebViewerExtension>

 <InteractiveViewer>com.actuate.sample.MyIvExtension</InteractiveViewer>

</BirtWebViewerExtension>

For an Information Console application deployed to an application server, save the compiled code archive to the <context root>\WEB-INF\lib folder for the application. Then, restart the application to enable the custom interface.

For Information Console deployed as a component of a typical BIRT iHub, save the compiled code archive to the following location:

<iHub installation folder>\modules\BIRTiHub\iHub\jar

The IBirtViewerExtension interface defines the event handler methods that activate implemented code, as follows:

package com.actuate.birtviewer.extension;

public interface IBirtViewerExtension{

// Event handler that runs when a design changesvoid afterDesignChange( IBirtViewerContext context,

IBirtViewerOp operation, ReportDesignHandle designHandle );

// Event handler after design get opened.void afterDesignOpen( IBirtViewerContext context,

ReportDesignHandle designHandle );

// Event handler that runs when a design is savedvoid afterDesignSave( IBirtViewerContext context, IBirtViewerOp

operation, ReportDesignHandle designHandle, String path );

//Event handler that runs when viewer creates a new session object

void afterViewerSessionStart( IBirtViewerContext context );

// Event handler that runs before a design change occursvoid beforeDesignChange( IBirtViewerContext context,

IBirtViewerOp operation, ReportDesignHandle designHandle );

// Event handler that runs before a design opensvoid beforeDesignOpen( IBirtViewerContext context, String path

);

// Event handler that runs before a design is savedboolean beforeDesignSave( IBirtViewerContext context,

IBirtViewerOp operation, ReportDesignHandle designHandle, String path );


// Event handler before soap response get sent back.void beforeResponse( IBirtViewerContext context, IBirtViewerOp

operation, GetUpdatedObjectsResponse response );

// Triggered when session object gets destroyed.void beforeViewerSessionClose( IBirtViewerSession session );

}

The IBirtViewerContext interface defines methods that retrieve information from the HTTP session, as follows:


public interface IBirtViewerContext {

// Gets the base URL for the viewerString getAppBaseUrl( );

// Gets reportlet id/bookmark if user is working on a reportlet.

String getReportletId( );

// Gets the extended session objectIBirtViewerSession getSession( );

// Gets the current user nameString getUserName( );

// Gets the volume profile nameString getVolumeProfile( );

// Gets the resource folder nameString getVolumeResourceFolder( );

}

The IBirtViewerOp interface defines methods that retrieve information from the extended session for BIRT Viewer, as follows:


public interface IBirtViewerOp {

// Gets column ids if target element is a tableString[] getColumnIIds( );

// Gets the operation nameString getName( );

// Gets the target element instance idsString[] getTargetIIds( );

// Get target element typeString getTargetType( );

}


The IBirtViewerSession interface defines methods that retrieve and set a session from the extended session for BIRT Viewer, as follows:


public interface IBirtViewerSession {

// Check whether key exists.boolean containsKey( String key );

//Get attribute from session.Object getAttribute( String key );

//Set attribute into session.void setAttribute( String key, Object attribute );

}

I n d e x 137

IndexAac.acceptlicense property 18ac.downloadonly property 18ac.homedir property 18ac.login property 18ac.password property 18access permissions. See privilegesaccessing

BIRT Studio functionality 74dashboards 27data 103, 108data objects 104Encyclopedia volumes 48, 68external data sources 105iHub Visualization Platform client

functionality 40, 54, 59Interactive Viewer 52JSPs 29report files 60reports 70repository items 27resources 22, 35, 46sample data source configurations 110shared resources 84, 97, 106

accounts 70, 71, 73creating dedicated iHub System 16installing on Linux systems and 16

AcGetFileDetailsAction class 60AcGetJobDetailsAction class 61AcServlet class 54Action class 59action element 74action forms 59, 61action paths 26action sets 75ActionForm class 59actions 26, 52

custom query builder 116enabling or disabling 74, 75, 78, 83

actionServlet component 26actionSet element 74actionSets element 74

activePortal directory 30activity logs 22, 43, 44Add Group command 124AddFile subfeature 52adding

aggregate data 82bookmarks 77data items to data objects 105data objects 103dedicated iHub accounts 16features 53folders 52, 60functionality categories 74functionality levels 50, 51, 53, 84home folders 71hyperlinks 61iHub profiles 100locales 46page breaks 77, 85, 129report elements to libraries 95report elements to templates 88, 90, 92resource folders 96, 99styles 95text file data sources 93themes 89, 94–97time zones 47tooltips 92user actions 74user roles 83users 71volume profiles 34–36, 46–??web pages 27

administration console applications 11administrator accounts 16Administrator functionality level 51administrator privileges 11administrators 74, 104

deploying distribution packages and 17Advanced functionality level 51Advanced Sort command 123AdvancedData subfeature 52advancedSort action 78AdvancedSort feature 123


agentStyleEngine property 127aggregate data

adding to tables 82disabling user actions for 75

aggregation action 75Aggregation command 123Aggregation feature 123alignCenter action 77alignLeft action 77Alignment command 124alignRight action 77ALLOW_EXPORT_PAGE_LIMIT parameter

126ALLOW_IV_PAGE_LIMIT parameter 126allscripts.js 53analytics gadgets 40analyze action 76Analyze button 123Analyze command 123Analyze feature 123Apache Tomcat servers 12

deploying to 20application context root 110application context roots 28application programming interfaces 130application server cache 24application server configurations 20application servers 3, 5, 10, 12, 19, 20, 21, 23applications 129

accessing data sources and 114changing 37configuring 40configuring BIRT Studio environment for

84deploying web 23designing custom reporting 5, 26, 31, 37developing 115enabling or disabling BIRT functionality

for 74, 75, 78, 83registering servlets with 118setting default locale for 42, 46setting default time zone for 42setting global styles for 37–38

archiving 126area charts

See also chartsarray elements 53

array.js 53arrays 53ascending sort order 78ASCII formats 48attachments 52authentication IDs 63, 65authentication information 5AutoEnableIV feature 123AUTO_SAVE_DASHBOARD_DELAY

parameter 48AUTOSUGGEST_DELAY parameter 126AUTOSUGGEST_FETCH_SIZE parameter

126AUTOSUGGEST_LIST_SIZE parameter 126autoSummarizeOn action 78Availability tag 122Available Data options 83axes values

See also charts

Bbanner

hiding features in 51bar charts

See also chartsBaseActionForm class 61Basic functionality level 50BEA WebLogic servers 20beans 59, 65beans package 59, 63binary files 54BIRT 360 web resources 40BIRT Design Engine API 130BIRT Designer Professional 95, 105BIRT iHub. See iHub SystemBIRT objects 105BIRT report documents 57BIRT reports

See also reportsBIRT repository. See Encyclopedia volumesBIRT Studio 22, 40, 127

configuring 84creating text file data sources for 93customizing 74data sources supported 108, 118disabling actions for 75, 78, 80, 83

I n d e x 139

enabling ODA drivers for 115limiting functionality of 74, 84predefined data sources in 103predefined themes in 89report parameters and 103report template categories in 97, 100setting up sample data sources for 109, 113unavailable features and 83

BIRT Viewer 40displaying reports and 126extending functionality of 130opening Interactive Viewer from 129

BIRT viewer 22BIRT Viewer interface 122BIRT Viewer Toolkit

deploying 20BIRT360PLUS_URL parameter 40BIRT_ARCHIVE_ MEMORY_TOTALSIZE

parameter 126BIRT_CHART_MAX_ROW parameter 126BIRT_CHART_MAX_VARIABLE_SIZE

parameter 126BIRT_CUBE_FETCH_LIMIT_

COLUMN_EDGE parameter 127BIRT_CUBE_FETCH_LIMIT_ROW_EDGE

parameter 127BIRT_DATA_RESULTSET_MAX_BUFFER_

SIZE parameter 127BIRT_HTMLRENDEROPTION_

ENGCASSTYLE parameter 127BIRT_JDBC_CONNECTION_POOL_

TIMEOUT parameter 127BIRT_JDBC_CONNECTION_POOL_SIZE

parameter 127BIRT_RENDER_FORMAT_

EMITTER_ID_MAPPING parameter 41BIRT_REPORT_ DOCUMENT_

CACHE_ENABLED parameter 84BIRT_REPORT_ PAGE_COUNT_

CACHE_ENABLED parameter 84BIRT_REPORT_DESIGN_ CACHE_TOTAL_

NUMBER_OF_ENTRIES parameter 84BIRT_REPORT_DESIGN_CACHE_TIMEOU

T parameter 84BIRT_RESOURCE_PATH parameter 22, 84,

127BIRT_SCRIPT_LIB_PATH parameter 84, 127

birtviewer-extension.xml 130BIRT_VIEWER_LOCALE parameter 127BIRT_VIEWER_LOG_DIR parameter 22BizRDRptTemplates folder 98bookmark action 77bookmark parameter 57bookmarks

adding 77border action 77borders 77branding 74, 89browsefile action 60BrowseFileActionForm class 60browsers. See web browsersbrowsertype.js 53browsing 60buffer size parameter 127

CC++ libraries 17cache 84, 85, 128, 129cache (web pages) 23CACHE_CONTROL parameter 41, 128caching web pages 41, 49CalculatedColumn feature 123calculation action 75Calculations action set 75cascading style sheets 127case sensitivity 26, 55categories (templates) 97, 100, 101Change Font command 124Change Type command 124changes, undoing or redoing 78changeSubtotal action 75changing

actions 75configurations 32folder names 99functionality levels 53images 38–40locales 22, 32reporting applications 37reports 85servlets 54, 55styles 89table type 77


time zones 22, 32user interface elements 40user roles 83

character encoding 48, 54character strings. See stringscharacters

data object design file names 106chart action 75chart DPI settings 134Chart Property command 123Chart Subtype command 123ChartProperty feature 123charts

binding to rows 126disabling user actions for 75selecting data for 104

ChartSubType feature 123class files 117class reference (JavaBeans) 60, 63classes 115, 117, 118, 130ClassicModelQueryBuilder.jsp 115ClassicModels sample database 112, 114clearing web browser cache 24ClearType text 10client applications 11cluster nodes 49clusters 2, 3, 4, 5, 11

deploying iHub Visualization Platform client and 23

code 114, 115CollapseExpand feature 123column headers

disabling user actions for 76searching 86

column names 111column types 111Column Width command 124ColumnEdit feature 123ColumnHeaderOperations action set 76ColumnOperations action set 76ColumnResize feature 124columns

See also fieldsdisabling user actions for 76setting page breaks for 129

columnWidth action 76comma-separated values files 86, 93

comments (templates) 91compilers 117compiling JSPs 26compiling servlet classes 117computed columns

disabling user actions for 75concurrent sessions 85conditional formats 77Conditional Formatting command 124conditionalFormat action 77ConditionalFormat feature 124configuration files 40, 122, 126, 130configuration parameters 84, 126, 134

changing 32iHub connections 48iHub Visualization Platform client 31, 40Visualization Platform 32

configurationsaccessing iHub Visualization Platform

client functionality and 40accessing text file data and 94changing messages and 47changing user actions and 74, 75, 78, 83connecting to iHub and 34, 46, 48creating custom applications and 31–40customizing BIRT Studio and 74customizing data sources and 118defining features and 51defining functionality levels and 50, 51, 53defining subfeatures and 52deploying iHub Visualization Platform

client and 20disabling load balancing and 5generating locale-specific sites and 46, 47invoking servlets and 55redirecting web pages and 6registering query builder servlet and 118running BIRT Studio and 84running multiple applications and 5running sample data sources and 109, 111,

113setting application server ports and 12setting up firewalls and 6, 7specifying default template category and

101specifying time zones and 47

configuring

I n d e x 141

application servers 20ClearType text 10iHub distribution setup script 18Visualization Platform 22, 23

connecting toClassicModels database 114Encyclopedia volumes 100ODA data sources 111, 116

connection parameters 26connection pool 127connection pools 49connection properties 100, 112connection timeout intervals 127connections

accessing data and 105accessing Encyclopedia and 26dropping 41establishing iHub 48running Visualization Platform and 24setting maximum number of 49timing out 44

CONNECTION_TIMEOUT parameter 41console applications 11context menus 122

limiting functionality 74, 75context paths 20context root 110context roots 28converter.js 54cookie.js 54COOKIE_DOMAIN parameter 42COOKIE_ENABLED parameter 42cookies 42, 54COOKIE_SECURE parameter 42Copy Format command 125Copy Information Objects to Shared

Resources Folder command 107Copy Library to Shared Resource Folder

command 97Copy Style command 125copyright statements 93country codes 46, 47CPUs

running Visualization Platform and 20Create Template Report Item command 92createfolder action 60CreateFolder subfeature 52

CreateFolderActionForm class 60createSection action 77creating

custom data sources 108–119custom query builders 115–118data objects 103, 105dedicated iHub accounts 16features 53folders 52, 60functionality categories 74functionality levels 50, 51, 53home folders 71hyperlinks 61iHub profiles 100information objects 105libraries 95ODA drivers 114report templates 88, 91–93reports 88resource folders 96, 99styles 95template categories 100text file data sources 93themes 89, 94–97tooltips 92users 71web applications 5, 26web pages 27

cross tab elements 105cross tab reports 104cross tab templates 104, 105cross tabs

disabling user actions for 76setting page breaks for 129

Crosstab Builder 76CrosstabOperations action set 76CSV files 86, 93cubes 127customizing

BIRT Studio 74data sources 108–119functionality levels 51–53messages 47query builder 115–118reporting applications 5, 26styles 95, 96user interfaces 109


Visualization Platform 19, 31, 32Visualization Platform WAR files 22

DDashboardBusinessUser subfeature 52DashboardDeveloper subfeature 52dashboards 27, 48, 52dashboards servlet 27DASHBOARD_SHARED_RESOURCES

parameter 49data

See also valuesaccessing 103, 108disabling user actions for 77displaying 26filtering 60, 61, 67hiding 94including in templates 88, 93previewing 82retrieving 104, 105synchronizing 52updating 83viewing restrictions for 128

data action 77Data Analyzer 76data buffer 127data cache 85data cubes 127data fields

disabling user actions for 75.data files 104data filters

disabling user actions for 75specifying number of rows to retrieve 86

data filters. See filtersdata items

adding to data objects 105data models 26data object data sources 103, 104data object design file names 106data object designs 104data object store data sources 104data object stores 104data objects

adding data items to 105building reports and 103

controlling access to 104creating 103, 105deploying 104designing 105–??retrieving data from 93, 104

data pointsSee also charts

data repositorySee also Encyclopedia volumes

data rowscaching 85disabling user actions for 76displaying 85retrieving 86setting maximum number of 85

data rows. See rowsdata series

See also chartsdata set extensions 111, 116, 119data sets 127

configuring custom data sources for 109hiding 94including in templates 88, 93joining 83retrieving 93selecting 93

Data Source dialog box 111, 119data source extensions 111, 116, 119data sources

accessing data in 103, 108accessing external 105configuring 118connecting to ODA 111, 114, 116creating templates and 93customizing 108–119naming 111, 119retrieving data from 104, 105selecting 103setting up CSV flies as 93setting up data objects as 103testing custom 110, 112

data stores 22Data Tools Platform projects (Eclipse) 114database connection properties 112database servers 5databases 104, 111.datadesign files 104

I n d e x 143

dataFields action 75dataObject element 111datasetDisplayName element 111datasetExtensionId element 111, 119datasourceExtensionId element 111, 119data-sources element 94date-and-time formats 127debugging messages 43decompressing WAR files 23default context root 28default Encyclopedia volume 66default error codes 47default locale 22, 32, 42, 46, 65, 85, 128default settings 32, 33default template category 98default templates 89default time zone 22, 42, 85, 128DEFAULT_COLUMN_PAGE_BREAK_

INTERVAL parameter 129DEFAULT_DATA_CACHE_ROW_COUNT

parameter 85DEFAULT_LOCALE parameter 22, 32, 42, 85,

128DEFAULT_PAGE_BREAK_ INTERVAL

parameter 85DEFAULT_PAGE_BREAK_INTERVAL

parameter 42, 129DEFAULT_REPORT_TEMPLATE_

CATEGORY_NAME parameter 85, 101DEFAULT_ROW_PAGE_BREAK_

INTERVAL parameter 130DEFAULT_TIMEZONE parameter 22, 32, 42,

85, 128delete action 76Delete Column command 123Delete Group command 124deleteColumn action 76DeleteColumn action set 76DeleteFile subfeature 52DeleteFolder subfeature 52deleteRow action 76deleteSection action 77deleting

folders 52report files 52

deployingcross tab templates 105

data objects 104iHub distribution package 17information objects 107query builder servlet 117reports 3, 10Visualization Platform 2, 12, 19–23WAR files 19

deploying BIRT Viewer Toolkit 20deployment tools 20descending sort order 78description element 111, 119Description property 92design cache 84Design Engine API 130design files 76design tools 74designing

data objects 103, 105–??report templates 88, 91reports 74

designing custom web applications 5, 26, 31, 37

designs 127editing 85limiting functionality 74, 76purging 84saving 91

detail rows 77detail table mode 77developing

custom query builders 115–118ODA data drivers 114web applications 115

directories 28, 29deploying Visualization Platform and 22extracting product files to 11

directory names 26directory paths

cross tab templates 105flat file ODA drivers 114home folders 73sample query builder 115sample query builder servlet 117script libraries 84shared resources 84template files 98text file data sources 94


disk space 45Display Name property 92display names 46, 47, 90, 92, 111, 119displaying

data 26data rows 85distinct values 129files and folders list 42folders 67libraries 97locales 46page layouts 77report elements 95report executables 67report templates 90, 97reports 27, 29, 45, 54, 57table of contents 125

displayName element 111, 119DisplayName tag 46, 47distinct values 129.do file name extensions 26Do Not Repeat Values command 125doc format value 57document cache 84document classes 60document files 67documentation v

Visualization Platform deployments and 19

documents 84See also reportsexporting specific pages 126

Documents attribute (features) 51Documents page 60domains 42DownloadFile servlet 56DownloadFile subfeature 52downloading

binary files 54product files 11reports 56

DPI settingschart resolution 134

drift.js 54drivers 108, 111, 114DTP project components (Eclipse) 114dynamic data 53

dynamic value parameters 85

EEAR deployments 21Eclipse DTP project components 114edit action 76Edit Computed Column command 123edit text icon 125editable report elements 90, 92, 93editCalculation action 75EditReport feature 124editText action 76EditText action set 76emitters 41, 133Enable Interactivity command 124, 129ENABLE_CLIENT_SIDE_REDIRECT

parameter 6, 42enabled attribute 75ENABLE_DEBUG_LOGGING parameter 43enabledInEnterpriseMode element 110, 111,

113, 119enabledInWorkgroupMode element 111, 119ENABLE_ERROR_LOGGING parameter 43ENABLE_JUL_LOG parameter 43EnableNewAggregationStyle attribute 82EnableSampleDataInPreview attribute 82encode method 54encoder.js 54encoding 48, 54Encyclopedia volumes

accessing 48, 68adding objects to 52connecting to 26, 100creating folders for 60creating resource folders for 99creating user accounts for 70deleting objects in 52downloading from 52, 56publishing information objects to 106, 107publishing template resources to 101publishing templates to 98, 99running Visualization Platform and 2specifying default 66

entryPoint element 111, 119erni_config.xml 74, 118error codes 47

I n d e x 145

error log files 43, 44error messages

localizing 47–48ERROR_LOG_FILE_ROLLOVER parameter

43errors 43, 122errors (console applications) 23event handler methods 131Excel emitters 133Excel formats

configuring default settings for 135Excel spreadsheets 129exceptions 122executable files

displaying 67EXECUTE_DASHBOARD_GADGET_

GENERATION_ WAIT_TIME parameter 43EXECUTE_REPORT_WAIT_TIME parameter

43executing

Java servlets 55jobs 27

Export Content command 124Export Data command 124export options 129EXPORT_AS_ATTACHMENT parameter 129ExportData feature 124ExportElement feature 124ExportElementData feature 124exporting

report content 126, 133specific report pages 126

ExportReport feature 124extended sample ODA data source 108, 112,

114, 118extension IDs 111, 116, 119external data sources 105extracting

iHub product files 11web archives 23

FFacebook Comment command 124FacebookComments feature 124failover 5feature definitions 51

feature lists 63, 66, 67Feature tag 122FeatureConfiguration tag 122FeatureControl tag 122FeatureID tag 51FeatureOptionsBean class 62features 51, ??–53, 62, 67, 74, 83, 122, 123fields

See also columnsdisabling user actions for 75

file cache 86file IDs 56file lists 42, 60, 66file name extensions 106file names 26, 106file numbers 44file paths 127, 130filefoldersprivilege action 60FileFoldersPrivilegeActionForm class 60fileId parameter 56FileListActionForm class 60FileOperations action set 76files

accessing 27, 60archiving 126converting to ASCII 48deleting 52disabling user actions for 76downloading 56downloading iHub 11getting information about 60purging 84, 86saving 54sharing 52

Files and Folders page (Management Console) 70

filesfolders JSPs 27filter action 75filter action forms 60, 61Filter command 124Filter feature 124filtering

data 60, 61, 67filters 66

disabling user actions for 75retrieving distinct values and 129specifying number of rows to retrieve 86


Firefox browser 129firewalls 6, 7, 12flashchartsxml format value 57FlashGadgetFormat feature 124FlashGadgetType feature 124flat file ODA drivers 114floatingfooter parameter 57folder lists 42, 60, 65, 66folder names 65, 99folders

accessing 27accessing reports and 70copying ODA driver files to 115creating 52, 60creating home 71creating resource 96, 99creating temporary files and 130deleting 52deploying query builder class files to 118displaying 67getting home 63navigating through 29publishing information objects and 106publishing resource files to 102publishing templates to 98specifying resource 22specifying type 66viewing information about 60viewing library files in 97

font action 77footers 57, 82FORCED_GC_INTERVAL parameter 43Format command 124format emitters 133, 134Format feature 124Format Flash Gadget command 124format parameter (Interactive Viewer) 57formats

displaying reports and 57limiting functionality 74, 77

formattingreports 89

Formatting action set 77formatting options 89forms package 59from_page_range parameter 57from_page_style parameter 57

ftp distributionsiHub System 11

functionality categories 74functionality levels 83

adding 50, 51, 53associating with users 50, 51changing 53customizing 51–53naming 51preserving 53specifying features for 51specifying subfeatures for 52

functionality options 84functionality-level.config 83functions 115

See also methods

Ggadget gallery 49GADGET_ GENERATION_ WAITING_TIME

parameter 43gadgets 43gadgets interface 27garbage collection 43GeneralFilterActionForm class 60, 61GeneralOperations action set 77generating

web pages 6–11, 26, 27generating reports 129getAcLocale method 63getAdminRights method 63getAuthid method 63getCurrentfolder method 63getDefaultServerURL method 63getDefaultVolume method 63getFeatureBean method 62getFeatureOptionsBean method 63getFeatures method 63getfiledetails action 60GetFileDetailsActionForm class 60getFilter method 63getHomefolder method 63getIportalid method 63getjobdetails action 61GetJobDetailsActionForm class 61getLocale method 63

I n d e x 147

getMaxJobPriority method 63getOnlylatest method 64getPassword method 64getProfile method 62, 64getProperty method 64getRepositoryType method 64getRoleNames method 64getServerurl method 64getShowdocuments method 64getShowexecutables method 64getShowfolders method 64getSideBarFeatures method 64getSidebarSelected method 64getSubfeatures method 64getSystemname method 64getTimezone method 64getUserAgent method 64getUserid method 65getView method 65getVolume method 65global style elements 37–38global variables 53Grand Total option 124GrandTotal feature 124graphical window manager 17graphs. See chartsgrid lines 133group footers 82group headers 82groupBy action 77GroupEdit feature 124Grouping action set 77groups

aggregating data and 82disabling user actions for 77

Hheap size 21help 77, 91, 92help action 77Help action set 77Help menu 126Hide Column command 123Hide Detail command 123Hide/Show Item command 124hideColumn action 76

hideDetail action 77HideShowItems feature 124hiding

data 94grid lines 133toolbars 125

Highlight feature 124highlighting 124home directory 28home folders 63, 66, 70, 71HOME property 94hosts 42HoverHighlight feature 124HTML code 37html format value 57HTML formats 77

rendering to 127htmlselect.js 54HTTP requests 6, 45, 62HTTP sessions 132HTTPServlet class 115hyperlink action 78hyperlinks

creating 61disabling user actions for 78

IIBirtViewerContext interface 132IBirtViewerExtension interface 131IBirtViewerOp interface 132IBirtViewerSession interface 132IBM WebSphere servers 20IContentList interface 59IDAPI_TIMEOUT parameter 44idle connections 127iHub

balancing workload on 4, 5, 33connecting to 34, 46, 48, 66copying ODA driver files to 115creating profiles for 100creating user accounts for 70deploying Visualization Platform and 2installing Visualization Platform with 3, 11,

44publishing information objects to 106, 107publishing template resources to 101


publishing templates to 98, 99running BIRT Studio and 85sending requests over 6, 29

iHub distribution package 17iHub distribution setup script

configuring 18running 19

iHub licensing options 70iHub profile property 100iHub System 3, 10, 26

creating dedicated account for 16downloading files for 11firewalls and 12integrating application servers with 20required libraries for 17

iHub system names 67image cache 129image files 101imageid parameter 57images 90, 92, 101

changing 38–40inedit parameter 116information 65Information Console

accessing functionality 40, 54, 59adding web pages to 27adjusting layers for 54assigning CPUs to 20caching web pages for 23changing default settings for 32, 33configuring 22, 23configuring as web applications 31–40configuring BIRT Studio for 84configuring proxy servers for 6, 7copying ODA driver files for 115creating custom applications for 5, 26customizing 19defining user actions and 83deploying 2, 12, 19–23installing 3, 10, 11, 19, 44integrating custom query builder with 115integrating with application servers 23localizing messages for 47–48logging in to 24missing functionality for 23overview 5resizing pages for 54

running multiple instances of 5setting application server port for 12setting connection parameters for 24setting context paths for 24setting log file location for 22setting port number for 24starting 6, 24testing installations for 24viewing available locales for 46

Information Delivery API 6information object files 107information object projects

selecting 107information objects

creating 105deploying 107enabling or disabling BIRT functionality

for 83, 84publishing 106, 107

informational text 91init method 65insertRow action 76installation

C++ libraries 17Java Runtime Environment 12Java Software Development Kit 12missing files and 11testing 24Visualization Platform 3, 10, 11, 19

installation wizard 12installing Visualization Platform 3, 11, 44INSTALL_MODE parameter 44instanceid parameter 57interactive features 123Interactive Viewer 52, 56

displaying reports and 126starting 129

Interactive Viewer servlet 56InteractiveViewing subfeature 52Intermediate functionality level 50Internet Explorer 129IO Design perspective 105iportal context root 24, 28iportal directory 30iportal.jar 117isAlwaysGetFolderList method 65isHomeFolderSet method 65

I n d e x 149

isIE method 62isNS4 method 62isNS6 method 62isShowFilters method 65isViewInNewBrowserWindow method 65iv_config.xml 122IV_ENABLE_IV parameter 129

JJ2EE installations 20Jakarta Struts Framework 54JAR files 130, 133JAR files (query builder servlet) 117Java classes 130Java heap size 21Java programming interfaces 130Java Runtime Environment 12Java Server Pages 23Java Software Development Kit 12JavaBean methods 59JavaBeans 59, 65JavaBeans class reference 60JavaBeans package reference 59javac compiler 117Javadoc 59JAVA_REPORT_API_IMAGE_CACHE_

EXPIRATION parameter 129JavaScript API 30JavaScript code 26JavaScript components 54JavaScript files

developing web applications and 53JavaScript functions 115JavaScript reference 53JavaServer Pages (JSPs) 115JBoss servers 20JDBC connection pool 127JDBC data sources 108, 109, 111JDBC database connections 112JDBC drivers 114JDK files 12job action forms 61job classes 61JobActionForm class 61JobPriority subfeature 52jobs

executing 27getting information about 61sending notifications for 52setting priorities for 52, 66setting properties for 62submitting 27, 62

Jobs attribute (features) 51joins 83JRE files 12JREM_TASK_QUEUE_SIZE parameter 129JREM_THREADPOOL_MAXSYNC_

TASKRUNTIME parameter 129JREM_THREADPOOL_MONITORTHREAD

_ POLLINGINTERVAL parameter 129JREM_THREAD_POOL_SIZE parameter 129JREM_THREADPOOL_SYNC_TASKQUEUE

_TIMEOUT parameter 129JSP engine 3, 6, 10JSPs 23

accessing 29compiling 26generating web pages and 11–27implementing URIs and 28implementing URLs and 26selecting templates for 29

JUL_LOG_CONSOLE_LEVEL parameter 44JUL_LOG_FILE_COUNT parameter 44JUL_LOG_FILE_LEVEL parameter 44JUL_LOG_FILE_SIZE_KB parameter 44

Llabels 47landing page 29language codes 46, 47languages 40launchiv parameter 57layer functionality 54layer.js 54Level tag 53libraries 17, 84, 89, 95, 96, 127library files 96, 101licenses 72licensing options 70line charts

See also chartsLink tag 61


Link To This Page command 124LinkBean class 61links 6LinkToThisPage feature 124Linux servers

installing Openmotif bundle for 17setting run level for 17setting up user accounts for 16

Linux systems 4, 10, 28list package 59lists 42, 44, 59load balancing 4, 5, 33locale codes 46, 47locale IDs 46locale names 46locale parameter 58Locale tag 46locales

accessing repository for 26adding 46configuring 46, 47creating error messages for 47–48selecting templates for 91, 101setting default 22, 32, 42, 46, 65, 85, 128specifying 127

localizing messages 47–48log file numbers 44log files 22, 43, 44LOG_FILE_LOCATION parameter 22, 44logging in to

Visualization Platform 24logging levels 44login action 7login forms 62login information 42, 62LoginForm class 62logins

getting user information for 62redirecting 6

LOGIN_TIMEOUT parameter 44

Mmachine names 12MainMenu feature 124Manage Data dialog box 76manageData action 76

ManageData action set 76Management Console 3, 10, 51, 54

adding resource folders and 99creating user accounts and 71, 73

manuals. See documentationMAX_BACKUP_ERROR_LOGS parameter

44MAX_BRSTUDIO_DESIGN_SESSION

parameter 85MAX_BRSTUDIO_USER_SESSION

parameter 85MAX_CONNECTIONS_PER_SERVER

parameter 49MAX_DATA_CACHE_ROW_COUNT

parameter 85MAX_LIST_SIZE parameter 44MAX_NUMBER_OF_VALUES_FOR_

DYNAMIC_PARAMETER parameter 85MDS_ENABLED parameter 5, 33, 49MDS_REFRESH_FREQUENCY_SECONDS

parameter 33, 49memory 43, 49MEMORY_DATA_CACHE_ROW_COUNT

parameter 85menus 51, 54, 122

limiting functionality 74, 75merge action 76mergeColumns action 76Message Distribution Service 4, 33, 49messages (templates) 91method calls 65methods 53, 59, 116

See also functionsmissing product files 11Mobile attribute (features) 51MOBILE_APP_DOWNLOAD parameter 45Model-View-Controller architecture 26Modify button 83MORE_VALUE_ROW_COUNT parameter 86Move To Group command 124Move to Left command 125Move to Right command 125MoveColumn feature 125moveToDetail action 76moveToGroup action 76multi-user mode 17

I n d e x 151

Nname element 111, 119name parameter

DownloadFile servlet 56named user licenses 70names

changing folder 99predefined styles and 95report elements 90servlets 118

namingdata object design files 106data sources 111, 119editable report items 92functionality levels 51non-editable report items 93report elements 90report templates 92resource folders 99users 71

naming restrictions 26, 55native2ascii utility 48networked environments 11, 130

configuring run levels for 17networks 2, 4, 45new action 76New Computed Column command 123New Data Object dialog 105New iHub Profile wizard 100New Library wizard 95New Style command 95New Style wizard 95New Template wizard 92New Theme wizard 96New User page (Management Console) 71non-editable report elements 90, 93noRepeat action 76notifications

sending 52NUMBER_OF_FILTER_VALUES parameter

129numeric formats 127

Oobjects 105ODA data set extensions 111, 116, 119

ODA data source configurations 112ODA data source extensions 111, 116, 119ODA data sources 109, 112, 118ODA design sessions 116ODA drivers 108, 114ODA framework 114ODA session IDs 116odaColumn dataType element 111odaColumn name element 111odaconfig element 118odaPassword element 111OdaSample data source 110OdaSampleExt data source 112odaURL element 111odaUser element 111online documentation vopen action 76opening

Interactive Viewer 52, 129reports 129Visualization Platform 24web browser windows 68

Openmotif bundle 17operating systems 70option controls 54options JSPs 27options page 62Outline view 95output format emitters 133, 134

Ppackages 59Page Break command 125page breaks 42, 77, 85, 129page engine 6page layout toggle 77page layouts

displaying 77page navigation icons 125page parameter 58page ranges 57page styles 57pageBreak action 77PageBreak feature 125PageLayout action set 77pageLayoutInToolbar action 77


PageNavigation feature 125parameter action 77Parameter button 125parameter definitions 32Parameter feature 125parameters

adding custom query builder and 116adding data objects and 103changing 32configuring BIRT Studio and 84configuring report viewers and 126configuring Visualization Platform and 40connecting to Encyclopedia and 26, 48customizing reporting applications and 31,

32deploying Visualization Platform and 22,

24disabling user actions for 77formatting output and 134loading JSPs and 26loading web pages and 27prompting for 126setting number of values displayed 85

Parameters dialog box 85parameters page 126passwords

creating users and 71getting 64setting 66

paths 127, 130cross tab templates 105dashboard resources 49flat file ODA drivers 114home folders 73log files 44sample query builder 115sample query builder servlet 117script libraries 84shared resources 84template files 98temporary files 45, 49text file data sources 94

pdf format value 57PDF formats

configuring default settings for 134performance 43, 127

previewing data and 82

retrieving data and 104performance analytics gadgets 40permissions. See privilegesPERSISTENT_ ARCHIVEFILECACHE_

TIMEOUT_SECONDS parameter 86ping action 61PingActionForm class 61pivot tables 133plug-ins 133poling intervals 129pop-up menus 54popupmenu.js 54ports 6

Apache Tomcat service 12Visualization Platform 24

PostgreSQL databasesinstalling iHub and 16

PostScript formatsconfiguring default settings for 135

PowerPoint documents 129PowerPoint formats

configuring default settings for 135ppt format value 57predefined data sources 103predefined styles 95predefined themes 89presentation models 26presentations 88Preview action set 77previewHTML action 77previewing

data 82Print command 125Print feature 125printing

reports 126prioritizing jobs 52, 66private cache 41privileges 4, 10, 60

accessing data objects and 105installing Visualization Platform and 11publishing information objects and 106,

107publishing templates and 100

process redirect page 6product files 11ProfileBean class 62

I n d e x 153

ProfileName parameter 35, 46profiles 34, 46, 50, 62, 66

selecting iHub 100progressive viewing 45PROGRESSIVE_REFRESH parameter 45PROGRESSIVE_VIEWING_ENABLED

parameter 45projects

selecting 107properties 66

Encyclopedia connection 100JDBC database connection 112report template 90, 92setting iHub distribution script 18styles 95, 96

.properties files 101properties files 22protecting data. See securityproxy servers 5, 6, 7, 45, 128, 130PROXY_BASEURL parameter 45, 130ps format value 57Publish Resources dialog box 102Publish Resources to iHub command 102Publish Templates dialog box 99Publish Templates to iHub command 99Publish to iHub command 107publishing

information objects 106, 107resources 101–103templates 97–101

purging cached files 84, 86

Qqueries 111, 116

See also SQL statementsquery builder

developing custom 115–118setting entry point for 111, 119

query builder page 113query builder servlet 115–118queryText element 111queue 129

Rrecords. See rowsredirect attribute 7

redirection 6, 42redo action 78refresh intervals 34, 49refreshes (web pages) 24registering query builder servlet 118relational databases

See also databasesremote servers 11renaming themes 95rendering reports 127Reorder Columns command 125reorderColumns action 76ReorderColumns feature 125Repeat Values command 125repeatValues action 76report design cache 84report design files 76Report Design perspective 88, 92report design tools 74report designs 127

editing 85limiting functionality 74, 76purging 84saving 91

report document cache 84report document files 67report documents 84

See also reportsexporting specific pages 126

report elementsadding to libraries 95adding to templates 88, 90, 92applying styles to 95naming 90, 92

report emitters 41, 133Report Encyclopedia. See Encyclopedia

volumesreport executable files 67report files

accessing 27, 60archiving 126deleting 52downloading 56getting information about 60saving 54sharing 52

report items


assigning bookmarks to 77assigning hyperlinks to 78formatting 89including in templates 92

__report parameter 58report parameters 103report section headings

adding fields to 78report sections

disabling user actions for 78report template categories 97, 100, 101Report Template dialog box 90, 101report template files 91, 92, 98report templates 22, 127

accessing resources for 101adding report elements to 88, 90, 92adding themes to 89, 94–97associating libraries with 96building cross tabs and 104, 105changing styles in 89creating 88, 91–93designing reports and 88, 90disabling user actions for 78displaying 90, 97excluding data sets in 94localizing 91, 101naming 92providing data with 93providing descriptions for 90, 92providing images for 90, 92publishing 97–101setting properties for 90, 92specifying default category for 85, 101specifying editable report elements for 92specifying non-editable report elements

for 93report viewer activity logs 22report viewers 56report.js 54reporting system. See iHub Systemreporting tasks 122ReportItemOperations action set 77reportlet format value 57reports

accessing 70changing 85controlling user actions for 74, 75, 78, 83

creating 88deploying 3, 10designing 74displaying 27, 29, 45, 54, 57downloading 56exporting content 126, 133formatting 89generating 129including in templates 88opening 129printing 126refreshing 45rendering HTML 127running 43selecting data for 108selecting data sources for 103setting page breaks for 77, 85, 129standardizing 89structuring 88, 90submitting requests for 6

repositoriesaccessing items in 27downloading from 58

repositorySee also Encyclopedia volumes

REPOSITORY_CACHE_TIMEOUT_SEC parameter 49, 130

repositoryType parameter 58request parameters 116requests 116, 128, 129

limiting number of items returned 44loading web pages and 27running multiple applications and 5sending 4, 26, 29submitting 6timing out 41

Resize feature 125resize.js 54resource files 47, 103Resource folder property 99resource folders 22, 96, 99, 102resources 26, 27, 35, 46, 53, 127

accessing 22accessing shared 84, 97, 106deploying data objects and 104publishing information objects and 107publishing template 98, 101–103

I n d e x 155

thumbnail images and 92result set buffer 127reverse proxies 6Role tag 51roles 74, 83

creating 50, 66defining functionality levels and 50, 51

rowsbinding to charts 126caching 85disabling user actions for 76displaying 85retrieving 86setting maximum number of 85setting page breaks for 130

.rpttemplate files 91rtl parameter 58run levels (Linux) 17running

iHub distribution setup script 19Java servlets 55jobs 27reports 43

Ssample data 82sample database 112, 114sample ODA configurations 109, 111, 113sample ODA data source 109sample query builder 115sample query builder servlet 115, 117SampleServlet.class servlet 117SampleServlet.java 115save action 76Save Design command 125Save Document command 125saveAs action 76saveas.js 54SaveDesign feature 125SaveDocument feature 125saving

dashboards 48report designs as templates 91report files 54

scatter chartsSee also charts

script libraries 84, 127scroll control panel 125ScrollControl feature 125Search attribute (features) 51Search page 60search results 86SEARCH_ENABLE_COLUMN_HEADERS

parameter 86searchfiles action 60SearchFilesActionForm class 60SEARCH_USE_QUOTE_DELIMITER

parameter 86section headings

adding fields to 78sectionHeading action 78SectionOperations action set 78sections

disabling user actions for 78security 16, 41, 128security roles 74, 83SECURITY_ADAPTER_CLASS parameter 45Select Data dialog box 94selection parameter 116selectjobs action 62SelectJobsActionForm class 62SelfNotificationWithAttachment subfeature

52sending notifications 52sending requests 26, 29series

See also chartsServer Print command 125server URLs 66ServerPrint feature 125servers 20, 128, 130

See also iHub serversbalancing workload among 4, 5, 33deploying Information Console to 20deploying Visualization Platform over 2deploying Visualization Platform to 12, 20dropping connections to 41extending functionality of 54installing Visualization Platform on 3, 11integrating Visualization Platform with 23maintaining session states for 5optimizing performance for 43preventing cache conflicts for 24


running multiple applications and 5sending requests over 6, 27setting context roots for 20setting port numbers for 12setting up firewalls and 6, 7

serverURL parameterInteractive Viewer servlet 58

servlet element 118servlet engine 3, 6, 10servlet names 55, 118servlet.jar 117servlet-mapping element 118servlets 26, 27, 54–55

creating query builder and 115, 115–118servlets reference 55session IDs 116session state 5SESSION_DEFAULT_PARAMETER_

VALUE_ID parameter 45sessionId parameter 116sessions 5, 42, 44, 45, 85, 116sessionTimeout parameter 45Set Template Property page 92setAcLocale method 65setAlwaysGetFolderList method 65setAuthid method 65setCurrentfolder method 65setDefaultServerURL method 66setDefaultVolume method 66setFeatureOptions method 66setFilter method 66setHomefolder method 66setMaxJobPriority method 66setOnlylatest method 66setPassword method 66setProfile method 66setProperty method 66setRequest method 62setRoleNames method 66setServerurl method 66setShowdocuments method 67setShowexecutables method 67setShowFilters method 67setShowfolders method 67setSideBarFeatures method 67setSidebarSelected method 67setSystemname method 67

setTimezone method 67setUserAgent method 67setUserid method 67setView method 68setViewInNewBrowserWindow method 68setVolume method 68Share Information Objects dialog box 107shared resources 84, 97, 106ShareFile subfeature 52ShareFormat feature 125ShareStyle feature 125Show Column command 123Show Detail command 123showColumns action 76showDetail action 77ShowTooltip feature 125side menu 51Sort Ascending command 125Sort Descending command 125Sort feature 125sort order 78sortAscending action 78sortDescending action 78Sorting action set 78source code 114, 115split action 76spreadsheets 129SQL statements

See also queriesstack trace (exceptions) 122Standard Viewer 56starting

Interactive Viewer 129Visualization Platform 24

starting Visualization Platform 6state parameter 116static text 76static value parameters 85strutscommon.js 54style definitions 37style sheets 127styles 37–38, 89, 95SubfeatureID tag 52subfeatures 52submitjob action 62SubmitJobActionForm class 61, 62submitting jobs 27, 62

I n d e x 157

SubTotal feature 125subtotal functions 75SubTotal option 125summary table mode 77summary tables

converting to detail tables 77disabling user actions for 75

summary valuesSee also aggregate data

SuppressDuplicate feature 125Switch View command 125switchSummaryMode action 77switchView action 76SwitchView feature 125symbolic links 17Synchronize Data Sets button 83synchronizing data 52system names 67

TTable Builder

enabling or disabling 77table elements 93table of contents 125table type conversions 77tableBuilder action 77tables

disabling user actions in 78displaying aggregate data in 82setting number of rows in 85

tab-separated values files 86tags

adding locales and 46adding time zones and 47defining functionality levels and 51defining subfeatures and 52

temp directory 49TEMP_FOLDER_LOCATION parameter 22,

49, 130template categories 97, 100, 101Template Category property 100template files 91, 92, 98Template Image property 92Template page 92templates 22, 127

accessing resources for 101

adding report elements to 88, 90, 92adding themes to 89, 94–97associating libraries with 96building cross tabs and 104, 105building JSPs and 29changing styles in 89creating 88, 91–93designing reports and 88, 90disabling user actions for 78displaying 90, 97excluding data sets in 94localizing 91, 101naming 92providing data with 93providing descriptions for 90, 92providing images for 90, 92publishing 97–101setting properties for 90, 92specifying default category for 85, 101specifying editable report elements for 92specifying non-editable report elements

for 93TemplateTableOperations action set 78temporary files 22, 45, 49, 84, 86, 130temporary server profiles 36testing

sample ODA data sources 110, 112Visualization Platform installations 24

text 47disabling user actions for 76localizing 91, 101providing informational 91

text file data sources 93text files 48text strings. See stringsTextEdit feature 125themes

creating 89, 94–97renaming 95selecting 74, 89updating 89

Themes list 95third-party applications 4thread pool 129threads 21thumbnail images 92, 101time formats 127


time zone IDs 47time zones 22, 32, 40, 42, 47, 67, 85, 128time-out values 41, 44, 45TimeZone tag 47TOC command 125Toc feature 125Tomcat servers 12Toolbar feature 125ToolbarHelp feature 126toolbars 54, 74, 75, 89, 122, 125tooltips 92, 125Top/BottomN command 126TopBottomNFilter feature 126toString method 61, 65trace (exception stack) 122TRANSIENT ARCHIVEFILECACHE_

TIMEOUT_SECONDS parameter 86transient files 22, 45, 49, 84, 86, 130TRANSIENT_STORE_MAX_SIZE_KB

parameter 45TRANSIENT_STORE_PATH parameter 22, 45TRANSIENT_STORE_TIMEOUT_SEC

parameter 45TSV files 86types. See data types

Uunavailable features 83undo action 78UndoRedo action set 78unencode method 54ungroupBy action 77Uniform Resource Locators. See URLsUNIX systems 4, 10, 28unprivileged user IDs 16updating

actions 75data 52, 83themes 89

upgrades 53UPLOAD_FILE_TYPE_LIST parameter 46uploading binary files 54UPLOAD_SECURITY_MANAGER

parameter 46URIs

implementing 28

loading servlets and 54redirecting web pages and 6submitting requests and 6, 29

URLs 130connecting to iHub System and 26, 34, 46,

66custom query builder 119ODA data drivers 114ODA data source connections 111query builder 111query builder servlet 118redirecting web pages and 6, 42setting up firewalls and 6specifying default 66transmitting actions and 26Visualization Platform 24

UsageInBRS property 94Use Library command 97Use Library dialog box 97user accounts 70, 71, 73

adding dedicated iHub System 16installing on Linux systems and 16

user classes 62user IDs 16, 58, 59, 67user interfaces 108, 109

changing elements in 37–40enabling features for 50, 51enabling subfeatures for 52submitting requests and 6

user names 71user option settings 27user profiles 62, 66user-agent header 62UserAgentBean class 62UserAgentBean objects 67userid parameter 58, 59UserInfoBean class 62, 63–68UserOptionsActionForm class 62users

assigning licensing options 70changing roles for 83creating 71getting passwords for 64limiting BIRT Studio functionality for 74,

75, 78, 83providing tooltips for 92returning information about 62, 63

I n d e x 159

selecting functionality levels 62setting features for 67setting functionality levels for 50, 51setting passwords for 66, 71specifying home folders for 71

Users page (Management Console) 71

Vvalue parameters 85values

See also datacreating tooltips for 92

variables 126version parameter

DownloadFile servlet 56Version property 100versioning options 100view constants 68viewer activity logs 22viewer servlet 56viewers 56viewing

data 26data rows 85distinct values 129files and folders list 42folders 67libraries 97locales 46page layouts 77report elements 95report executables 67report templates 90, 97reports 27, 29, 45, 54, 57table of contents 125

viewing restrictions 128viewnav.js 54views 68visible attribute 75, 80visual report elements 88Visualization Platform 126, 127Visualization Platform technology 2volume administrators 104volume names

accessing Visualization Platform and 12volume parameter

Interactive Viewer servlet 58volume profiles 34–36, 46–??, 50VOLUME_PROFILE_LOCATION parameter

50VolumeProfiles tag 35volumes. See Encyclopedia volumes

Wwait values 41, 43WAR deployments 21WAR files 12, 19, 21, 22web administrator privileges 11web applications 5, 23, 84, 115, 118web browsers 23, 70

detecting 53, 62displaying reports and 128, 129loading web pages for 27maintaining session state for 5opening new windows for 68preserving login information for 42redirecting 6, 42rendering reports and 127setting cache for 41, 128specifying 67

web pages 23adding 27caching 41, 49generating 6–11, 26, 27loading 27resizing 54submitting requests and 6

web resources 26, 27web servers 3, 11, 21web sites 3, 10web.xml 40, 84, 118, 126WEB-INF directory 40WebLogic servers 20WebSphere servers 20window displays 54Windows language pack 48Windows systems 4, 10, 28

configuring firewalls for 12installing JDK files for 12installing JRE files for 12installing Visualization Platform for 11, 19

Word documents 129


Xx-axis values

See also chartsXLS emitter 133xls format value 57XML files 94

Yy-axis values

See also charts