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 Contents

About Installing Visualization Platform...... v Chapter 1 Understanding Visualization Platform clients ...... 1 About Actuate Visualization Platform client ...... 2 Planning Visualization Platform client installations ...... 3 Setting up Visualization Platform client ...... 3 Understanding Visualization Platform client load balancing ...... 4 Deploying a load balancer for an BIRT iHub cluster ...... 5 Using a cluster of application servers ...... 5 Visualization Platform client architecture ...... 5 Using proxy servers with Visualization Platform client ...... 6 Disabling administrative capabilities ...... 8 Chapter 2 Installing Visualization Platform stand-alone client ...... 9 Preparing to install Actuate Visualization Platform client ...... 10 Setting ClearType text properties ...... 10 Setting up Visualization Platform client ...... 11 Installing using electronic distribution ...... 11 Performing a full iHub installation ...... 11 Installing Visualization Platform client on Windows ...... 11 Installing Visualization Platform client on Linux ...... 16 Configuring a Linux user account for the Visualization Platform ...... 16 Setting up libstdc++ ...... 17 Using run level 5 ...... 17 About Openmotif ...... 17 Using the installation scripts for Linux ...... 17 Using the WAR file to install ...... 19 About deployment formats ...... 20 Avoiding cache conflicts after installing ...... 23 Testing the installation ...... 24 Chapter 3 Configuring Actuate Visualization Platform client ...... 25 Visualization Platform client web application structure and contents ...... 26 Visualization Platform client pages ...... 27 Visualization Platform client directory structure ...... 28 Configuring a custom Visualization Platform client web application ...... 31

i Setting the default locale ...... 32 Controlling the Message Distribution service load balancing ...... 33 Setting the JavaScript MIME types for Apache Tomcat ...... 34 Configuring connections to iHub using volumeProfile.xml ...... 34 Modifying global style elements ...... 37 Visualization Platform client configuration ...... 40 Configuring Visualization Platform client using web.xml ...... 40 Configuring locales ...... 46 Configuring time zones ...... 47 Customizing messages and text according to locale ...... 47 Configuring the connection to iHub Server ...... 48 Restricting access to Actuate Visualization Platform client features using functionality levels 50 Visualization Platform client JavaScript reference ...... 53 Using Visualization Platform client Java servlets ...... 54 base servlet ...... 54 Invoking a servlet ...... 55 Java servlets reference ...... 55 Visualization Platform client JavaBeans overview ...... 59 Visualization Platform client JavaBeans package reference ...... 59 Visualization Platform client JavaBeans class reference ...... 60 Visualization Platform client UserInfoBean class reference ...... 63 Chapter 4 Configuring Report Studio ...... 69 Assigning license options to a user ...... 70 Enabling or disabling functionality ...... 74 Configuring toolbar and context menu items ...... 74 Specifying the default position of aggregate values ...... 82 Using sample data in a preview ...... 82 Configuring advanced data operations ...... 83 Configuring the application environment ...... 84 Chapter 5 Customizing and integrating Report Studio ...... 87 About report templates ...... 88 Design considerations ...... 88 Separating or combining visual and data elements ...... 88 Designing themes ...... 89 Improving usability ...... 90 Creating a report template ...... 91 Providing data with a report template ...... 93 Using a CSV file as a data source ...... 93

ii Excluding a data set ...... 94 Creating themes for a report template ...... 94 Publishing a template ...... 97 Setting the default template category ...... 101 Publishing resources associated with a template ...... 101 Types of data sources ...... 103 Using data objects as a data source ...... 103 Deploying data objects ...... 104 Deploying cross tab templates ...... 105 Creating data objects ...... 105 Building a data object ...... 105 Deploying data objects ...... 106 Creating a custom data source ...... 108 Sample ODA data source ...... 109 Extended sample ODA example ...... 112 Developing an open data access (ODA) data driver ...... 114 Developing a custom query builder ...... 115 Configuring the extended custom data source ...... 118 Chapter 6 Configuring BIRT Viewer ...... 121 Configuring the Actuate BIRT Viewer toolbar using iv_config.xml ...... 122 Configuring Actuate BIRT Viewer using web.xml ...... 126 Configuring a BIRT Viewer Java extension ...... 130 Configuring default export formats ...... 133 Index ...... 137

iii iv About Installing Visualization Platform

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.

About Installing Visualization Platform v vi Installing Visualization Platform Chapter 1

Chapter 1Understanding Visualization Platform clients

This chapter contains the following topics: ■ About Actuate Visualization Platform client ■ Planning Visualization Platform client installations

Chapter 1, Understanding Visualization Platform clients 1 About Actuate Visualization Platform client Users 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 Administration An 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 Suite A 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 Viewer A web viewer for BIRT report content which also supports printing and saving reports to many formats.

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

■ Report Studio A 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.

2 Installing Visualization Platform 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 \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 installations Before 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 client You can install Visualization Platform client in several ways:

■ As a separate web application packaged in a WAR or EAR This 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 service This 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 iHub This 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.

Chapter 1, Understanding Visualization Platform clients 3 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 balancing Visualization 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:

Application Web server browser Visualization Volume Platform

Third-party Application Actuate Web application server BIRT iHub browser server load Visualization balancer Platform Volume

Application Actuate server Web BIRT iHub browser System Console Volume

StateServer or SqlServer 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.

4 Installing Visualization Platform 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 cluster To 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 servers If 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.

Chapter 1, Understanding Visualization Platform clients 5 Visualization Platform client architecture The general Visualization Platform client network architecture is illustrated in Figure 1-2. Firewall Firewall

Web or Application server Database Server Servlet or Page engine Visualization Platform client Actuate BIRT Web iHub System browser IDAPI Proxy SOAP port Actuate load balancing

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 client When 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

6 Installing Visualization Platform configuration parameter in the /WEB-INF/web.xml file to True and modify the redirect attributes in the /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: 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:

Chapter 1, Understanding Visualization Platform clients 7 validate="false"> This change needs to be made for all the actions in struts-config.xml that send a redirect to the browser. Disabling administrative capabilities For 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 \modules\BIRTiHub\iHub\web\iportal directory. Once the /admin directory is removed, restart the Actuate iHub 3 service.

8 Installing Visualization Platform Chapter 2

Chapter 2Installing Visualization Platform stand-alone client

This chapter contains the following topics: ■ Preparing to install Actuate Visualization Platform client ■ Using the WAR or EAR file to install

Chapter 2, Installing Visualization Platform stand-alone client 9 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 properties Using 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.

10 Installing Visualization Platform Setting up Visualization Platform client You 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 installation BIRT 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

Chapter 2, Installing Visualization Platform stand-alone client 11 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 \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: The SP ID for SAML SSO SAMLEntityID http://server1:8700/iportal 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.

12 Installing Visualization Platform 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 install If 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 formats Actuate 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

Chapter 2, Installing Visualization Platform stand-alone client 13 Table 2-1 BIRT Visualization platform deployment formats File Application server JBOSS_ActuateInformationConsole.ear JBoss WAS_ActuateInformationConsole.ear IBM WebSphere

The Apache Tomcat and WebLogic servers do not support EAR deployment. Only the JBoss and WebSphere application servers support EAR deployment. General deployment tasks You 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 server Actuate 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 file You can use a WAR file to deploy Visualization Platform client to many supported servers. To enable shindig 2.0 support for a deployable Visualization

14 Installing Visualization Platform Platform client’s WAR or EAR file, modify the host name, port, and context root in the following configuration files: /WEB-INF/web.xml /WEB-INF/classes/shindig.properties /WEB-INF/classes/containers/default/container.js In web.xml, update the following parameters: system.properties shindig.host= shindig.port=

■ is the name of the web server hosting the Visualization Platform client web application. ■ 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://:/ /gadgets/oauthcallback

■ is the name of the web server hosting the Visualization Platform client web application. ■ is the TCP port assigned to the Visualization Platform client web application. ■ is the context root of the Visualization Platform client web application. In container.js update the following parameters: "gadgets.jsUriTemplate" : "http://%host%//gadgets/js/ %js%" "gadgets.oauthGadgetCallbackTemplate" : "//%host%// gadgets/oauthcallback" "gadgets.osDataUri" : "http://%host%//social/rpc" "proxyUrl" : "//%host%//gadgets/ proxy?refresh=%refresh%&url=%url%", "jsonProxyUrl" : "//%host%//gadgets/makeRequest" "path" : "http://%host%//social" "endPoints" : [ "http://%host%//social/rpc", "http:// %host%//gadgets/api/rpc" ]

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

Chapter 2, Installing Visualization Platform stand-alone client 15 Table 2-1 describes the Visualization Platform client configuration parameters to review and update before deployment. Table 2-1 Visualization Platform client configuration parameters Parameter name Description Action BIRT The location of the standard If you specify a location on disk, _RESOURCE templates and properties files that copy the contents of the _PATH BIRT Studio uses. This location can Visualization Platform client be in a WAR file or on a disk. resources folder to this physical location on the file system. DEFAULT The default locale is en_US. You can If you change the locale, select the _LOCALE leave this value unchanged. A user new locale from the locales in can select a locale at login. /WEB-INF/Localemap.xml. DEFAULT The default time zone is Pacific If you change the time zone, select _TIMEZONE Standard Time (PST). You can leave the new time zone from the time this value unchanged. A user can zones in the TimeZones.xml file, select a time zone at login. in the WEB-INF directory. BIRT_VIEWER The location of the files that log You must create this physical _LOG_DIR Actuate BIRT viewer activity. location on the file system. LOG_FILE The location of the files that log You must create this physical _LOCATION Visualization Platform client activity. location on the file system. TEMP_FOLDER The location where Visualization You must create this physical _LOCATION Platform client creates temporary location on the file system. files. TRANSIENT The location where Visualization You must create this physical _STORE_PATH Platform client creates temporary location on the file system. files.

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:

16 Installing Visualization Platform 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/ic copy 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.war For deploying Visualization Platform client to the IBM WebSphere application server. WAS_ActuateBIRTJavaComponent.ear contains WAS_ActuateBIRTJavaComponent.war.

■ WL_ActuateBIRTJavaComponent.war For 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.

Chapter 2, Installing Visualization Platform stand-alone client 17 About clusters of servers If 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 installing Visualization 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 installation Complete 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.

18 Installing Visualization Platform Chapter 3

Chapter 3Configuring Actuate Visualization Platform client

This 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

Chapter 3, Configuring Actuate Visualization Platform client 25 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 \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

26 Installing Visualization Platform Visualization Platform client pages Visualization 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 \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 \iportal \activePortal\private\filesfolders. The submit request JSPs and custom tags support submitting new jobs. The submit request JSPs reside in \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 \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.

Chapter 3, Configuring Actuate Visualization Platform client 27 Visualization Platform client directory structure The 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 \iHub\servletcontainer\ iportal and on UNIX and Linux systems is /iHub/ servletcontainer/iportal. The default context root for a separate Visualization Platform client installation on Windows systems is \iHub3\ modules\BIRTiHub\iHub\web\iportal and on UNIX and Linux systems is /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.

admin \web birtAdapter

iportal bizRD default common jslib common fonts da img dashboard

downloads

dtd common common filesfolders diagnosis dtd iportal activePortal filesfolders iv errors common jobs js images examples myfiles mobile private jsapi newrequest newrequest viewer options portlets options requests

temp parameters viewer sample WEB-INF Figure 2-1 Visualization Platform client directory structure

28 Installing Visualization Platform Visualization Platform client URIs convey user requests to Actuate BIRT iHub. Pages supporting folder navigation and document viewing reside in the \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 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)

Chapter 3, Configuring Actuate Visualization Platform client 29 Table 2-1 directories (continued) Directory Contents 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 lists and describes the directories in the common/jslib/common path. Table 2-2 /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 lists and describes the iportal directories. Table 2-3 /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 lists and describes the \iportal\activePortal directories. Table 2-4 /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.

30 Installing Visualization Platform Table 2-4 /iportal/activePortal directories Directory Contents 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 elements included in all reporting web pages, \common such as banner and side menu elements. private Self-diagnostic utility page. \diagnosis private Pages that support working with files and folders. \filesfolders 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 Pages that support new requests, such as parameter \newrequest processing, scheduling, and job status pages. private Pages that support table parameters. \parameters private\sample Example custom requester page. viewer Pages that support report viewing.

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

Chapter 3, Configuring Actuate Visualization Platform client 31 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 \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:

■ is the name of the parameter. ■ is the parameter value. Do not enclose the keyword and value within quotes, and use no spaces between , the keyword or value, and . For example, the definition for the default locale parameter is: DEFAULT_LOCALE en_US 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 locale The 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: DEFAULT_LOCALE en_US 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 \WEB-INF\localemap.xml.

32 Installing Visualization Platform 3 Navigate to the lines that define DEFAULT_TIMEZONE, similar to the following code: DEFAULT_TIMEZONE America/Los_Angeles 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 \WEB-INF\TimeZones.xml. 4 Save web.xml. 5 Restart the application server or servlet engine that runs Visualization Platform client and clear your browser cache. 6 Open the Visualization Platform client web application. The login page for the custom application appears. Controlling the Message Distribution service load balancing The 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: MDS_ENABLED false 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: MDS_REFRESH_FREQUENCY_SECONDS 0

Chapter 3, Configuring Actuate Visualization Platform client 33 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. 5 Restart the application server or servlet engine that runs Visualization Platform client and clear your browser cache. Setting the JavaScript MIME types for Apache Tomcat Apache 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

js application/javascript 3 Change the value of the mime-type parameter to the following: text/javascript 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.xml To 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

34 Installing Visualization Platform 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: \WEB-INF\volumeProfile.xml For example, the following is a volume profile definition for the server1 server: true server1 enterprise http://server1:8000 volume1

■ is the name of this profile. ■ has one of two values, either enterprise or workgroup. ■ contains the iHub URL, for example, http://server1:8000. If RepositoryType is workgroup, ServerUrl is ignored. ■ is the volume name. If RepositoryType is workgroup, volume is ignored. ■ 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. ■ 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 element to the list in in volumeProfile.xml. Then, restart Visualization Platform. For example, the following profile accesses the volume2 volume on the server2 server: false server2 enterprise http://server2:8000 volume2

Chapter 3, Configuring Actuate Visualization Platform client 35 Using a volume profile defined in volumeProfile.xml Visualization 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 profile Visualization 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 profiles If 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.

36 Installing Visualization Platform Modifying global style elements Although 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 \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 \common\jslib \themes\img directory.

Chapter 3, Configuring Actuate Visualization Platform client 37 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: \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;

38 Installing Visualization Platform 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

Chapter 3, Configuring Actuate Visualization Platform client 39 Visualization Platform client configuration The 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: \WEB-INF\web.xml Table 2-5 lists the configuration files discussed in this chapter. Table 2-5 Visualization Platform client configuration files File Features Description erni_config.xml BIRT Studio Configures BIRT Studio functionality functionality-level.config Visualization Configures the Visualization Platform Platform client user interface by client 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

Configuring Visualization Platform client using web.xml Web.xml contains parameters that control Visualization Platform client features. Table 2-6 describes the configuration parameters for the Visualization Platform client application. 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.

40 Installing Visualization Platform Table 2-6 Visualization Platform client web.xml parameters (continued) Parameter name Description BIRT_RENDER_ Specifies which emitter will be used for a specific BIRT report. Valid FORMAT_EMITTER_ entries are of the format "render_format:emitter_ID" separated by a ID_MAPPING 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_ Controls how many seconds Visualization Platform client waits for TIMEOUT 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.

Chapter 3, Configuring Actuate Visualization Platform client 41 Table 2-6 Visualization Platform client web.xml parameters (continued) Parameter name Description 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_ Specifies display order of Fields and Folders. Default value is DISPLAY_ORDER "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 \WEB-INF\localemap.xml. DEFAULT_PAGE_ Specifies the number of rows to display in one page when viewing BREAK_INTERVAL 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 \WEB-INF\TimeZones.xml. ENABLE_CLIENT_ Specifies whether URL redirection is done on the client side or the SIDE_REDIRECT 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)

42 Installing Visualization Platform Table 2-6 Visualization Platform client web.xml parameters (continued) Parameter name Description ENABLE_DEBUG_ Indicates whether to record debugging messages in a log file called LOGGING Debug.log. Set the value to True to enable debug messages in the log file. The default value is False. ENABLE_ERROR_ Indicates whether to log errors. This parameter’s default value is LOGGING 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. ....log. ERROR_LOG_FILE_ Specifies the time period to wait before starting a new log file. ROLLOVER Options are Daily, Monthly, Weekly, and Yearly. The default value is Monthly. EXECUTE_DASH Specifies the time to wait, in seconds, for a gadget to generate when BOARD_GADGET_ running a dashboard design file. This parameter’s default value is GENERATION_WAIT_ 2seconds. TIME EXECUTE_REPORT_ Specifies the time to wait, in seconds, for a report to execute. This WAIT_TIME parameter’s default value is 20 seconds. For more information about the wait time parameter, see Integrating Applications into BIRT iHub. FORCED_GC_ Indicates the length in seconds of the interval that the Visualization INTERVAL 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_ Specifies the time to wait, in seconds, for an individual gadget to GENERATION_ generate. This parameter’s default value is 10 seconds. WAITING_TIME

Chapter 3, Configuring Actuate Visualization Platform client 43 Table 2-6 Visualization Platform client web.xml parameters (continued) Parameter name Description 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_ The level of Visualization Platform client activity to log to the LEVEL 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_ Specifies the number of log files for a particular time stamp, if the COUNT value of ENABLE_JUL_LOG is TRUE. JUL_LOG_FILE_ The level of Visualization Platform client activity to log in a file. LEVEL 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_ The maximum size, in kilobytes, for a Visualization Platform client KB 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_ Indicates which directory contains the log files. If the value is not LOCATION 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_ Specifies the maximum number of backup error log files to keep. ERROR_LOGS 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.

44 Installing Visualization Platform Table 2-6 Visualization Platform client web.xml parameters (continued) Parameter name Description MOBILE_APP_ The URL target of the download button displayed by Visualization DOWNLOAD Platform client when viewed in mobile/touch device. (continues) PROGRESSIVE_ Controls the interval in seconds at which an Actuate report REFRESH 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_ Specifies whether a paginated report starts to display in the VIEWING_ENABLED 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_ Specifies whether an outside domain is a legal value for the OUTSIDE_DOMAIN targetpage URL parameter. If set to false, targetpage cannot redirect traffic to any outside domain. The default value is false. SECURITY_ Specifies the fully qualified class of the security adapter, which ADAPTER_CLASS must extend com.actuate.iportal.security.iPortalSecurityAdapter, that controls access to Visualization Platform client functionality. The default value is no name. SESSION_DEFAULT_ Specifies the name of the object that stores the HTTP session-level PARAMETER_ report parameters. This object is an instance of the VALUE_ID 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_ Limits the amount of disk space that Visualization Platform client MAX_SIZE_KB uses for temporary files. The default value is 102400, which is 100 MB. TRANSIENT_STORE_ Path to Visualization Platform client transient files. The default PATH 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_ Specifies, in minutes, how long to retain Visualization Platform TIMEOUT_MIN client transient files. The default value is 40, which is 40 minutes.

Chapter 3, Configuring Actuate Visualization Platform client 45 Table 2-6 Visualization Platform client web.xml parameters (continued) Parameter name Description UPLOAD_FILE_TYPE_ Specifies the valid file types, by extension, for upload with LIST Visualization Platform client. The default value is blank, which indicates any file type. UPLOAD_SECURITY_ Specifies the fully qualified class of the security adapter, which MANAGER must extend com.actuate.iportal.security.IUploadSecurityAdapter, that controls access to the upload functionality. The default value is no name.

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 \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: Searching for places the cursor on the line having the descriptive name for the locale. Typically, the locale names have the following syntax: _ 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 \WEB-INF\web.xml.

46 Installing Visualization Platform Configuring time zones \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: Searching for 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 \WEB-INF\web.xml. Customizing messages and text according to locale Error messages and text for Visualization Platform client are encoded in resource files compressed in the /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 /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.

Chapter 3, Configuring Actuate Visualization Platform client 47 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 /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 /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 Server Visualization 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 Parameter name Description AUTO_SAVE_ Controls how long, in seconds, the dashboard engine should DASHBOARD_DELAY wait before sending a save message to persist the personal dashboard file. To disable auto save, set this value to 0.

48 Installing Visualization Platform Table 2-7 iHub connection web.xml parameters (continued) Parameter name Description DASHBOARD_SHARED_ Specifies the path for the shared dashboard and gadget RESOURCES 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_ Indicates the maximum number of Visualization Platform PER_SERVER 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_ Indicates, in seconds, how quickly Visualization Platform client FREQUENCY_SECONDS 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_ Specifies how long a repository cache remains valid. When the TIMEOUT_SEC cache becomes invalid, any user actions refresh the cache for the time-out duration. The default value is 900 seconds. SERVER_QUERY_ Specifies how long iHub Visualization Platform client waits for TIMEOUT a response before the socket times out for the BIRT iHub connection. Its default value is eight seconds. TEMP_FOLDER_ Specifies the directory Visualization Platform client uses to LOCATION 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.

Chapter 3, Configuring Actuate Visualization Platform client 49 Table 2-7 iHub connection web.xml parameters (continued) Parameter name Description VOLUME_PROFILE_ Path to the volume profile configuration file from the context LOCATION root. Default value is /WEB-INF/VolumeProfile.xml.

Restricting access to Actuate Visualization Platform client features using functionality levels Actuate 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 \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.

50 Installing Visualization Platform ■ 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 levels Customize or add functionality levels by modifying or creating a level definition in functionality-level.config. A functionality level definition consists of five parts:

■ Level name The level name must be a unique alphanumeric string, enclosed within and tags.

■ Matching security role The 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 and tags.

■ Available features Table 2-8 describes the five available features. 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

Features are specified one per line and are enclosed within and 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 subfeatures Subfeatures 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

Chapter 3, Configuring Actuate Visualization Platform client 51 feature is not included. The subfeatures are described in Table 2-9. 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 Dashboard NA Permits use of dashboards BusinessUser Dashboard NA Permits design and administration of Developer 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 SelfNotification Jobs Activates e-mail notification for WithAttachment 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

Subfeatures are specified one per line, enclosed within and tags.

52 Installing Visualization Platform The following code shows a sample functionality level entry: ViewAndSearch All Jobs Documents Search ShareFile DeleteFile 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 features The 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 reference This 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 \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

Chapter 3, Configuring Actuate Visualization Platform client 53 Table 2-10 Visualization Platform client JavaScript files Name Description 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

Using Visualization Platform client Java servlets Java 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 servlet Some 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.

54 Installing Visualization Platform ■ 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 servlet Invoke servlets using the following syntax: http://://servlet /

■ 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 reference Table 2-11 lists and describes the Visualization Platform client Java 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

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

Chapter 3, Configuring Actuate Visualization Platform client 55 DownloadFile servlet Downloads a file from the volume. Name com.actuate.reportcast.servlets.FileDownloadServlet Invoke the DownloadFile servlet as: http://://servlet/DownloadFile URI Table 2-12 lists and describes the URI parameters for the DownloadFile servlet. parameters

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.

Interactive Viewer servlet Displays 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.

56 Installing Visualization Platform - Figure 2-4 Interactive Viewer Name com.actuate.iv.servlet.IVServlet Invoke the Interactive Viewer servlet as: http://://iv URI Table 2-13 lists and describes the URI parameters for the Interactive Viewer parameters servlet. Table 2-13 Parameters for IV URI URI parameter Description __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

Chapter 3, Configuring Actuate Visualization Platform client 57 Table 2-13 Parameters for IV URI URI parameter Description __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

IDP User Password servlet Displays 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

58 Installing Visualization Platform Invoke the IDP User Password servlet as: http://:/idp/Authn/UserPassword URI Table 2-13 lists and describes the URI parameters for the Interactive Viewer parameters servlet. Table 2-14 Parameters for IDP Login URI URI parameter Description 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

Visualization Platform client JavaBeans overview This 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 \WEB-INF\ lib. The Javadoc is provided for the JavaBeans in \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 reference Table 2-15 lists and describes the Actuate packages used in Visualization Platform client. Table 2-15 Visualization Platform client packages Package Contents com.actuate JavaBeans that maintain information used by the Action .activeportal.beans classes. com.actuate JavaBeans derived from the Jakarta Struts .activeportal.forms org.apache.struts.action.ActionForm object. These JavaBeans store and validate the request parameters in HTTP requests. com.actuate An interface, IContentList, that defines the behavior of lists of .activeportal.list items such as files and folders. Several classes in com.actuate.activeportal.forms use this interface.

Chapter 3, Configuring Actuate Visualization Platform client 59 Visualization Platform client JavaBeans class reference This section lists and describes the Visualization Platform client JavaBean classes by topic.

Documents Table 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. FileFoldersPrivilegeAction Stores information about file and folder access rights, the Form 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.

60 Installing Visualization Platform General Table 2-17 describes the Visualization Platform client com.actuate.activeportal.beans class that supports general functionality. 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: text

Table 2-18 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support general functionality. 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.

Jobs Table 2-19 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support jobs. 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.

Chapter 3, Configuring Actuate Visualization Platform client 61 Table 2-19 Job classes Class Description 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.

Users Table 2-20 lists and describes Visualization Platform client com.actuate.activeportal.beans classes that support handling users. 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 lists and describes Visualization Platform client com.actuate.activeportal.forms classes that support handling users. 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.

62 Installing Visualization Platform Visualization Platform client UserInfoBean class reference Table 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 \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)

Chapter 3, Configuring Actuate Visualization Platform client 63 Table 2-22 UserInfoBean methods (continued) Method Description 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 Gets a string containing the value of a custom property having .String name) 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 system enterprise: 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 \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.

64 Installing Visualization Platform Table 2-22 UserInfoBean methods (continued) Method Description 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. isViewInNewBrowser Returns True if the report viewer is specified to launch in a Window( ) new browser window. toString() Returns a string representation of the object.

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. Table 2-23 UserInfoBean set methods Method Description setAcLocale(com.actuate. Sets the Actuate locale for the current user with the specified reportcast.utils.AcLocale AcLocale object. Also changes the Java locale. acLocale) setAlwaysGetFolderList Set to True if the Documents page should always show the (boolean b) folder list, even if it is not selected on the filter. setAuthid(java.lang.String Sets the authentication ID to the string passed in as a authid) 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 Sets the string specifying the most recent folder name accessed .String currentfolder) by the user.

Chapter 3, Configuring Actuate Visualization Platform client 65 Table 2-23 UserInfoBean set methods (continued) Method Description setDefaultServerURL(java Sets the URL to use as a default value for users. .lang.String defaultServerURL) setDefaultVolume(java.lang Sets the volume to use if no volume name is specified by the .String defaultVolume) URL in the request. By default, Visualization Platform client sets the default volume to the value in the VOLUME_DEFAULT tag in \WEB-INF\ web.xml. setFeatureOptions Sets a list of all Visualization Platform client features and iHub (FeatureOptionsBean options that are available to the current user. featureOptionsBean) setFilter(java.lang.String Sets the string specifying the filter to use as a default value in filter) 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 Sets the string specifying the user’s home folder. An .String string) administrator or application sets this value when creating auser. setMaxJobPriority(int Sets the maximum job priority permitted for this user. An priority) administrator sets this value for a user. setOnlylatest(java.lang Sets value to indicate if only latest version of the documents .String onlylatest) 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 Sets the password to the value of the string passed as a .String password) 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 Sets the value of a custom property. Create custom properties name, java.lang.String and set their values using this method. The parameters are the value) name of the custom property and the value to set. setRoleNames(java.lang Sets a list of the user’s feature roles, such as Administrator. .String[] strings[]) setServerurl(java.lang Sets the server URL currently used by the user. This URL .String surl) includes the protocol and the port, for example: http://localhost:9000.

66 Installing Visualization Platform Table 2-23 UserInfoBean set methods (continued) Method Description setShowdocuments(java Sets the value to indicate if documents are to be displayed in .lang.String the file folder list. “true” sets Visualization Platform client to showdocuments) display documents. setShowexecutables(java Sets the value to indicate if executables are to be displayed in .lang.String the file folder list. “true” sets Visualization Platform client to showexecutables) display executables. setShowFilters(boolean Set to True to specify that Visualization Platform client display showFilters) the filter panel for all pages showing lists of files, jobs, or subscriptions. (continues) setShowfolders(java.lang Sets the value to indicate if folders are to be displayed in the .String showfolders) file folder list. “true” sets Visualization Platform client to display folders. setSideBarFeatures(com Sets the list of features available to this user on the side menu, .actuate.activeportal tabs, the tree, or equivalent structure. This list is a subset of the .functionality.config features available to the user. .Feature[] feature) setSidebarSelected(java.lang Sets the feature highlighted on the side menu, tab, tree, or .String sideBarSelected) 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 Sets the iHub system name to the value of the string .String systemName) parameter. setTimezone(com.actuate Sets the AcTimeZone object specifying the user’s time zone. .reportcast.utils .AcTimeZone timezone) setUserAgent Sets the UserAgentBean for this user. The UserAgentBean (UserAgentBean userAgent) specifies the user’s browser type. setUserid(java.lang Sets the user ID for the user. .String userid)

Chapter 3, Configuring Actuate Visualization Platform client 67 Table 2-23 UserInfoBean set methods (continued) Method Description setView(java.lang.String Sets the current view for the user. The string contains the name string) of the constant for the desired view. The available constants are: ■ AcConstants.VIEW_CATEGORY ■ AcConstants.VIEW_LIST ■ AcConstants.VIEW_DETAIL ■ AcConstants.VIEW_ICON setViewInNewBrowser Set to True to specify that the report viewer launch in a new Window(boolean browser window. _newWindow) setVolume(java.lang Sets the value of the string specifying the name of the volume .String volume) the user is accessing.

68 Installing Visualization Platform Chapter 4

Chapter 4Configuring Report Studio

This chapter contains the following topics: ■ Assigning license options to a user ■ Enabling or disabling functionality ■ Configuring the application environment

Chapter 4, Configuring Report Studio 69 Assigning license options to a user If 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.

70 Installing Visualization Platform 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.

Choose to add a user

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

Chapter 4, Configuring Report Studio 71 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.

72 Installing Visualization Platform 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.

Chapter 4, Configuring Report Studio 73 Enabling or disabling functionality Report 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 items You 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: \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 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 element defines the category, and the element defines a specific action. Listing 2-1 shows the hierarchy of elements. Listing 2-1 An example of an element in erni_config.xml FileOperations true New true Open true Save true

74 Installing Visualization Platform SaveAs true By default, all actions are enabled. You can disable actions in the following ways: ■ To disable a particular action, change the action’s attribute from true to false. ■ To disable all actions within a category in one step, change the action set’s 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 actions Table 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.

Chapter 4, Configuring Report Studio 75 Table 2-1 User actions that you can enable or disable through erni_config.xml (continued) Action set Action Description ColumnHeader DeleteRow Deletes the row of the selected column header. Operations 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.

76 Installing Visualization Platform Table 2-1 User actions that you can enable or disable through erni_config.xml (continued) Action set Action Description 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. Conditional Formats data in a selected column, based on a Format 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. SwitchSummary Switches between summary table mode and Mode 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 GroupBy Groups table rows by values in the selected (continued) 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 PageLayoutIn Displays page layout toggle under toolbar. Toolbar Disabled by default. Preview PreviewHTML Shows a preview of the report in HTML format. ReportItemOperations Bookmark Assigns a bookmark to a report item.

Chapter 4, Configuring Report Studio 77 Table 2-1 User actions that you can enable or disable through erni_config.xml (continued) Action set Action Description 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. TemplateTable AutoSummarizeOn If set to true, creates a summary table by Operations default. If set to false, creates a detail table by default. UndoRedo Redo Redo the last action. Undo Undo the last action.

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

78 Installing Visualization Platform 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. Format Actions

Formatting actions

Figure 2-7 Default BIRT Studio page Listing 2-2 shows a change to the Formatting action set. Its 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 Formatting false AlignLeft true AlignCenter true

Chapter 4, Configuring Report Studio 79 AlignRight true Font true Border true ConditionalFormat true Data true Figure 2-8 shows the updated Report Studio page. None of the formatting actions appear in the toolbar or the context menu. Setting the 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

80 Installing Visualization Platform Listing 2-3 shows changes to the Font and Data actions within the Formatting action set. The Formatting action set’s 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 Formatting true AlignLeft true AlignCenter true AlignRight true Font false Border true ConditionalFormat true Data false 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.

Chapter 4, Configuring Report Studio 81 Alignment actions

Figure 2-9 Updated toolbar and context menu, without the Font and Data formatting actions Specifying the default position of aggregate values The 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: EnableNewAggregationStyle false ...

Using sample data in a preview Actual 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:

82 Installing Visualization Platform ... EnableSampleDataInPreview/name> true ...

Configuring advanced data operations You 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.

Synchronize Data Sets option Modify option

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.

Chapter 4, Configuring Report Studio 83 Listing 2-4 Intermediate and Advanced levels in functionality-level.config All ... InteractiveViewing AdvancedData DashboardDeveloper 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 environment You can change the values of the configuration parameters in the following file: \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 Parameter name Description BIRT_REPORT_DESIGN_ Specifies the amount of time, in seconds, before a cached BIRT CACHE_TIMEOUT report design is purged if it has not been used. The default value is 1800, which is 30 minutes. BIRT_REPORT_DESIGN_ Specifies the maximum number of BIRT report designs to CACHE_TOTAL_ cache. The default value is 50. NUMBER_OF_ENTRIES BIRT_REPORT_ Specifies whether to cache BIRT report documents when they DOCUMENT_CACHE_ are previewed or generated. The default value is true. ENABLED BIRT_REPORT_ Specifies whether to cache the number of pages in transient or PAGE_COUNT_CACHE_ persistent BIRT report documents when they are previewed or ENABLED 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 \resources. BIRT_SCRIPT_LIB_PATH Path to script libraries. The default value is \scriptlib.

84 Installing Visualization Platform Table 2-2 Report Studio web.xml parameters (continued) Parameter name Description DEFAULT_DATA_ The number of data rows to display in Report Studio when CACHE_ROW_COUNT 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. DEFAULT_PAGE_BREAK_ The number of rows to display on one page when viewing a INTERVAL report. A value of 0 indicates no page breaks. DEFAULT_REPORT_ The default BIRT report template category to load when a user TEMPLATE_CATEGORY_ opens BIRT Studio. The default value is Standard. NAME DEFAULT_TIMEZONE The default time zone. The default time zone is Pacific Standard Time (PST). MAX_BRSTUDIO_ The maximum number of designs a user can edit concurrently DESIGN_SESSION in Report Studio. The default is 10. MAX_BRSTUDIO_USER_ The maximum number of concurrent Report Studio sessions on SESSION the server. The default is 256. MAX_DATA_CACHE_ Limits the number of data rows that a user can choose to ROW_COUNT display in Report Studio when designing a report. The default value is 200. MAX_NUMBER_OF_ The number of values shown in the parameter dialog box for a VALUES_FOR_ dynamic value parameter in Report Studio: DYNAMIC_PARAMETER ■ 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_ Specifies the number of data rows to cache in memory. The CACHE_ROW_COUNT default value is 50. (continues)

Chapter 4, Configuring Report Studio 85 Table 2-2 Report Studio web.xml parameters (continued) Parameter name Description MORE_VALUE_ROW_ Specifies the number of rows to fetch when a user chooses to COUNT filter a report on a column in Report Studio. The default value is 200. PERSISTENT_ Specifies the amount of time, in seconds, before a cached file ARCHIVEFILECACHE_ that was created from a repository file is purged if it has not TIMEOUT_SECONDS been used. The default value is 7200, which is 120 minutes. SEARCH_ENABLE_ Indicates whether to include column headings in report search COLUMN_HEADERS results when the output format is CSV or TSV. Set this parameter to true, the default value, to include column headings. SEARCH_USE_ Indicates whether to enclose search results in quotation marks QUOTE_DELIMITER when the output format is CSV or TSV. The default value is true, which encloses the results in quotation marks. TRANSIENT Specifies the amount of time, in seconds, before a cached file ARCHIVEFILECACHE_ generated without saving it to the repository is archived if it TIMEOUT_SECONDS has not been used. The default value is 1200, which is 30 minutes.

86 Installing Visualization Platform Chapter 5

Chapter 5Customizing and integrating Report Studio

This 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

Chapter 5, Customizing and integrating Report Studio 87 About report templates A 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 considerations A 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 elements When 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.

88 Installing Visualization Platform Designing themes Report 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.

Chapter 5, Customizing and integrating Report Studio 89 Improving usability A 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

90 Installing Visualization Platform 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. List of elements in the template

Figure 3-3 Report Items listing all the template elements

Creating a report template You 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.

Chapter 5, Customizing and integrating Report Studio 91 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

92 Installing Visualization Platform 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 template If 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 source A 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

Chapter 5, Customizing and integrating Report Studio 93 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 element, shown in the following example: Data Source C:\ UTF-8 YES The HOME property shows the directory in which to place the CSV file. Excluding a data set You 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: UsageInBRS string true excluded

Creating themes for a report template As 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.

94 Installing Visualization Platform 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

or

.

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.

Chapter 5, Customizing and integrating Report Studio 95 ■ 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.

96 Installing Visualization Platform 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 template Templates 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

Chapter 5, Customizing and integrating Report Studio 97 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 \ \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.

98 Installing Visualization Platform 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.

Chapter 5, Customizing and integrating Report Studio 99 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.

100 Installing Visualization Platform 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 category By 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: \WEB-INF 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: DEFAULT_REPORT_TEMPLATE_CATEGORY_NAME Sales 3 Restart the appropriate Windows service for the change to take effect.

Publishing resources associated with a template Typically, 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.

Chapter 5, Customizing and integrating Report Studio 101 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.

p Figure 3-13 Selecting files for publishing to a specified iHub volume 5 Select the files to publish.

102 Installing Visualization Platform 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 sources To 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 source A 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.

Chapter 5, Customizing and integrating Report Studio 103 ■ 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 objects There are two types of data objects, and either one can be a data source:

■ Data object design A 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 store A 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.

104 Installing Visualization Platform ■ 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 templates When 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 \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 objects A 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 object Building 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.

Chapter 5, Customizing and integrating Report Studio 105 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 objects Data 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.

106 Installing Visualization Platform 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

Chapter 5, Customizing and integrating Report Studio 107 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 source Another 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.

108 Installing Visualization Platform Sample ODA data source Creating 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 OdaSample Sample ODA data source A sample ODA data source org.eclipse.birt.report.data.oda.jdbc CLASSICMODELS org.eclipse.birt.report.data.oda.jdbc. JdbcSelectDataSet CLASSICMODELS.PAYMENTS org.eclipse.birt.report.data.oda.sampledb. Driver jdbc:classicmodels:sampledb ClassicModels CUSTOMERNUMBER INTEGER PAYMENTDATE DATE CHECKNUMBER STRING AMOUNT FLOAT CLASSICMODELS.PAYMENTS true

Chapter 5, Customizing and integrating Report Studio 109 false 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 attribute in erni_config.xml to true. The erni_config.xml file is stored in the following location: \WEB-INF Typically, in standard installations the is as follows: \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

110 Installing Visualization Platform 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 The unique name of the data source. This name follows certain naming conventions. There can be no spaces, for example. The data source name that appears in the Data Source dialog box, as shown in Figure 3-18. The data source description that appears in the Available Data pane. Identifies the ID of the data set extension of the data driver. The display name of the data source. Identifies the ID of the data source extension of the data driver. The display name of the data set. The database URL to use to connect to the data source. The user name, used to connect to the database. The database password. The name of the database column to be included in the user interface. 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) The name of the database table if single table is used. The text of the query if the columns are from different tables. Not used. Indicates whether this data source is available to users. A URL or servlet that points to the first web page of your custom query builder.

Chapter 5, Customizing and integrating Report Studio 111 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 and 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 … org.eclipse.birt.report.data.oda.sampledb .Driver jdbc:classicmodels:sampledb ClassicModels …

Extended sample ODA example To 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

112 Installing Visualization Platform enable the data source, named OdaSampleExt, by setting the data source’s attribute in erni_config.xml to true. The erni_config.xml file is stored in the following locations: \BIRTiHubVisualization\modules\BIRTiHub\iHub\web\ iportal\WEB-INF Listing 3-7 shows in bold the 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 OdaSampleExt Extended sample ODA data source An extended sample ODA data source org.eclipse.birt.report.data.oda.jdbc org.eclipse.birt.report.data.oda.jdbc .JdbcSelectDataSet true true /OdaSample 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.

Chapter 5, Customizing and integrating Report Studio 113 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 driver You 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: \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

114 Installing Visualization Platform (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: \iHub2\MyClasses\eclipse\plugins In Visualization Platform client: \MyClasses\eclipse\plugins

Developing a custom query builder You 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: \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: \iportal\examples\oda\classes\com\actuate \erni\oda\ClassicModels

Creating the servlet A 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

Chapter 5, Customizing and integrating Report Studio 115 ■ 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. 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.

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-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)

116 Installing Visualization Platform Table 3-3 Actions corresponding to inedit and state values (continued) inedit value state value Action 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.

Compiling the servlet After 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: \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: \iHub\servletcontainer\webapps\acrsse\WEB_INF \lib

Deploying the servlet After 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: \WEB-INF\lib

Chapter 5, Customizing and integrating Report Studio 117 If you deploy the servlet as a class file, copy the servlet class to the following location: \WEB-INF\classes

Registering the servlet After 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: \WEB-INF The first entry, under the element, defines a name for the servlet and specifies the compiled class that executes the servlet. The following example shows the entry for the sample servlet: OdaSampleServlet com.actuate.erni.oda.ClassicModels.SampleServlet The second entry, under the element, defines the URL pattern that calls this servlet. The following example shows the entry for the sample servlet: OdaSampleServlet /OdaSample

Configuring the extended custom data source After 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: \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 element in erni_config.xml. Table 3-4 describes each attribute, within the element, that you configure.

118 Installing Visualization Platform Table 3-4 Attributes of an extended custom data source Attribute Description The unique name of the data source. This name follows specific naming conventions. There can be no spaces, for example. The data source name that appears in the Data Source dialog box, as shown in Figure 3-18. The data source description that appears in the user interface. 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. 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. Not used. Indicates whether this data source is available to users. A URL or servlet that points to the first web page of your custom query builder.

Chapter 5, Customizing and integrating Report Studio 119 120 Installing Visualization Platform Chapter 6

Chapter 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

Chapter 6, Configuring BIRT Viewer 121 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: \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 All/Role> SaveDesign true SaveDocument true … All tags are placed within the element. Each feature is described by the tag, and its availability is described with the 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 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

122 Installing Visualization Platform tag. The format of the iv_config.xml file appears as shown in the following code: Iportal com.actuate.iv.utility.filename.DefaultFileNameGenerator … … … 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)

Chapter 6, Configuring BIRT Viewer 123 Table 3-1 Actuate BIRT Viewer feature set (continued) Feature Availability tag description 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

124 Installing Visualization Platform Table 3-1 Actuate BIRT Viewer feature set (continued) Feature Availability tag description 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)

Chapter 6, Configuring BIRT Viewer 125 Table 3-1 Actuate BIRT Viewer feature set (continued) Feature Availability tag description 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

Configuring Actuate BIRT Viewer using web.xml Actuate 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. Table 3-2 Actuate BIRT Viewer web.xml parameters Parameter name Description ALLOW_EXPORT_PAGE_ Indicates the maximum number of pages that can be exported LIMIT 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_ The number of autosuggest parameter values to load on the SIZE parameters page. The default value is -1, which loads all values. AUTOSUGGEST_LIST_ The number of autosuggest parameter values to display on the SIZE 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_ The total memory available for BIRT report document files, in MEMORY_TOTALSIZE kilobytes. The default value is 50 megabytes. BIRT_CHART_CONVERT_ Sets the time out for conversion from chart to image in a BIRT TO_IMAGE_TIME_OUT report. The default value is 6.

126 Installing Visualization Platform Table 3-2 Actuate BIRT Viewer web.xml parameters (continued) Parameter name Description 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_ The maximum size for a variable used in a Flash chart, VARIABLE_SIZE measured in bytes. The default value is 0, which allows a variable to be of any size. BIRT_CUBE_FETCH_ The maximum column limit for accessing a data cube. The LIMIT_COLUMN_EDGE value must be a non-negative integer; 0 indicates no limit. BIRT_CUBE_FETCH_ The maximum row limit for accessing a data cube. The value LIMIT_ROW_EDGE must be a non-negative integer; 0 indicates no limit. BIRT_DATA_RESULTSET_ The result set buffer size, in megabytes, for a data set in a BIRT MAX_BUFFER_SIZE report. The default value is 10 megabytes. BIRT_ Enables the agentStyleEngine property for the HTML render HTMLRENDEROPTION_ option for a BIRT report. This setting is related to using a ENGCASSTYLE 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_ Specifies the number of idle connections cached by BIRT JDBC CONNECTION_POOL_ connection pool. The default value is 10. SIZE BIRT_JDBC_ Specifies how long an idle connection will remain in the BIRT CONNECTION_POOL_ JDBC connection pool in seconds. The default value is 3600. TIMEOUT BIRT_LINKED_DATA_ Sets an upper limit on data loaded into memory by a data MODEL_DATA_MODEL_ model at runtime, measured in megabytes. The default value SIZE 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 \resources. BIRT_SCRIPT_LIB_PATH Path for the BIRT script libraries (JARs). The default value is \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)

Chapter 6, Configuring BIRT Viewer 127 Table 3-2 Actuate BIRT Viewer web.xml parameters (continued) Parameter name Description 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_ Sets whether to collapse attribute nodes in the dimension tree. ITEM False sets nodes to collapse; True sets nodes to expand. The default value is false.

128 Installing Visualization Platform Table 3-2 Actuate BIRT Viewer web.xml parameters (continued) Parameter name Description EXPORT_AS_ Determines whether a Microsoft Excel, PowerPoint, or Word ATTACHMENT 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_ Specifies how long in seconds to cache images for Actuate BIRT IMAGE_CACHE_ reports and business reports. The default value is 86,400, which EXPIRATION 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_ Specifies the maximum number of threads in the Java Report SIZE Engine thread pool. The default value is 10. JREM_THREADPOOL_ Specifies the maximum time a synchronous report generation MAXSYNC_ is allowed to run. The default value is 600. TASKRUNTIME JREM_THREADPOOL_ Controls the interval in seconds at which the Java Report MONITORTHREAD_ Engine thread pool checks for Java report execution time-out or POLLINGINTERVAL queue time-out. The default value is 30. JREM_THREADPOOL_ Specifies the maximum time, in seconds, that a Java SYNC_TASKQUEUE_ synchronous request stays in the Java Report Engine task TIMEOUT queue before timing out, in seconds. The default value is 300. NUMBER_OF_FILTER_ Specifies the number of distinct values to display when a user VALUES chooses to filter a report on a column in BIRT Viewer. The default value is 200. DEFAULT_COLUMN_ Specifies the number of columns to display on one page when PAGE_BREAK_INTERVAL viewing a cross tab. Must be a non-negative number. Default value is 10. (continues)

Chapter 6, Configuring BIRT Viewer 129 Table 3-2 Actuate BIRT Viewer web.xml parameters (continued) Parameter name Description DEFAULT_PAGE_BREAK_ Specifies the number of rows to display in one page when INTERVAL viewing a report. If set to 0, there are no page breaks. DEFAULT_ROW_PAGE_ Specifies the number of rows to display on one page when BREAK_INTERVAL 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_ Specifies, in seconds, how long to retain temporary files that TIMEOUT_SEC BIRT Viewer creates when a user modifies the appearance of a report. The default value is 900, which is 15 minutes. TEMP_FOLDER_ Path to the folder where temporary files are created. LOCATION

Configuring default export formats You 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: \Jar\BIRT\platform\plugins \com.actuate.birt.report.engine.emitter.config_ .v On BIRT Designer Professional, the location of the folder containing the sample .xml files is: \eclipse\plugins\ com.actuate.birt.report.engine.emitter.config_. v Each XML file has the following name: org.eclipse.birt.report.engine.emitter..xml

130 Installing Visualization Platform 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

The element contains the following child elements:

■ 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 is true.

■ Represents an export option in Export Content. Contains the following attributes, which support configuring the export option:

■ name Name of the export option. Required.

■ default Default 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.

■ enable Determines 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 is true if this attribute is omitted in the 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 ChartDpi Sets the chart resolution. Value can be formats any integer greater than 0. DOCX EmbedHtml Permissible values are true or false.

132 Installing Visualization Platform Table 3-3 Configurable default settings for exporting content (continued) Format Option name Permissible values PDF, pdfRenderOption Enables bidirectional text support. PostScript .bidiProcessing Permissible values are true or false. PDF, pdfRenderOption Enables text wrapping. Permissible PostScript .textWrapping values are true or false. PDF pdfRenderOption Enables splitting words with a hyphen .hyphenation at line breaks. Permissible values are true or false. PDF, pdfRenderOption Enables font substitution for unknown PostScript .fontSubstitution fonts. Permissible values are true or false. PDF, pdfRenderOption Controls rendering content when the PostScript .pageOverflow 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 Embeds fonts in the output document. .embeddedFonts 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 Enables text wrapping. Permissible .wrappingText values are true or false. XLS/XLSX excelRenderOption Enables pivot tables. Permissible values .EnablePivotTable are true or false. (continues)

Chapter 6, Configuring BIRT Viewer 133 Table 3-3 Configurable default settings for exporting content (continued) Format Option name Permissible values XLS/XLSX excelRenderOption Enables BIRT Viewer to automatically .AutoFitPivotTable adjust content for display in pivot tables. Permissible values are true or false. XLS/XLSX excelRenderOption Renders charts as images only. .ExportChartsAsImages Permissible values are true or false. XLS/XLSX excelRenderOption Enables formulas for derived values. .EnableLiveFormula Permissible values are true or false. XLS/XLSX excelRenderOption Hides grid lines. Permissible values are .hideGridlines true or false. XLS/XLSX excelRenderOption Enables multiple worksheet output. .multipleSheet Permissible values are true or false.

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 extension The 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: \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: \modules\BIRTiHub\iHub\etc For example, to enable myIVExtension.jar to operate on BIRT Viewer, add an entry to birtviewer-extension.xml as follows:

134 Installing Visualization Platform com.actuate.sample.MyIvExtension For an Information Console application deployed to an application server, save the compiled code archive to the \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: \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 changes void 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 saved void 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 occurs void beforeDesignChange( IBirtViewerContext context, IBirtViewerOp operation, ReportDesignHandle designHandle ); // Event handler that runs before a design opens void beforeDesignOpen( IBirtViewerContext context, String path ); // Event handler that runs before a design is saved boolean beforeDesignSave( IBirtViewerContext context, IBirtViewerOp operation, ReportDesignHandle designHandle, String path );

Chapter 6, Configuring BIRT Viewer 135 // 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: package com.actuate.birtviewer.extension; public interface IBirtViewerContext { // Gets the base URL for the viewer String getAppBaseUrl( ); // Gets reportlet id/bookmark if user is working on a reportlet. String getReportletId( ); // Gets the extended session object IBirtViewerSession getSession( ); // Gets the current user name String getUserName( ); // Gets the volume profile name String getVolumeProfile( ); // Gets the resource folder name String getVolumeResourceFolder( ); } The IBirtViewerOp interface defines methods that retrieve information from the extended session for BIRT Viewer, as follows: package com.actuate.birtviewer.extension; public interface IBirtViewerOp { // Gets column ids if target element is a table String[] getColumnIIds( ); // Gets the operation name String getName( ); // Gets the target element instance ids String[] getTargetIIds( ); // Get target element type String getTargetType( ); }

136 Installing Visualization Platform The IBirtViewerSession interface defines methods that retrieve and set a session from the extended session for BIRT Viewer, as follows: package com.actuate.birtviewer.extension; 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 ); }

Chapter 6, Configuring BIRT Viewer 137 138 Installing Visualization Platform Index

A activePortal directory 30 activity logs 22, 43, 44 ac.acceptlicense property 18 Add Group command 124 ac.downloadonly property 18 AddFile subfeature 52 ac.homedir property 18 adding ac.login property 18 aggregate data 82 ac.password property 18 bookmarks 77 access permissions. See privileges data items to data objects 105 accessing data objects 103 BIRT Studio functionality 74 dedicated iHub accounts 16 dashboards 27 features 53 data 103, 108 folders 52, 60 data objects 104 functionality categories 74 Encyclopedia volumes 48, 68 functionality levels 50, 51, 53, 84 external data sources 105 home folders 71 iHub Visualization Platform client hyperlinks 61 functionality 40, 54, 59 iHub profiles 100 Interactive Viewer 52 locales 46 JSPs 29 page breaks 77, 85, 129 report files 60 report elements to libraries 95 reports 70 report elements to templates 88, 90, 92 repository items 27 resource folders 96, 99 resources 22, 35, 46 styles 95 sample data source configurations 110 text file data sources 93 shared resources 84, 97, 106 themes 89, 94–97 accounts 70, 71, 73 time zones 47 creating dedicated iHub System 16 tooltips 92 installing on Linux systems and 16 user actions 74 AcGetFileDetailsAction class 60 user roles 83 AcGetJobDetailsAction class 61 users 71 AcServlet class 54 volume profiles 34–36, 46–?? Action class 59 web pages 27 action element 74 administration console applications 11 action forms 59, 61 administrator accounts 16 action paths 26 Administrator functionality level 51 action sets 75 administrator privileges 11 ActionForm class 59 administrators 74, 104 actions 26, 52 deploying distribution packages and 17 custom query builder 116 Advanced functionality level 51 enabling or disabling 74, 75, 78, 83 Advanced Sort command 123 actionServlet component 26 AdvancedData subfeature 52 actionSet element 74 advancedSort action 78 actionSets element 74 AdvancedSort feature 123

Index 137 agentStyleEngine property 127 array.js 53 aggregate data arrays 53 adding to tables 82 ascending sort order 78 disabling user actions for 75 ASCII formats 48 aggregation action 75 attachments 52 Aggregation command 123 authentication IDs 63, 65 Aggregation feature 123 authentication information 5 alignCenter action 77 AutoEnableIV feature 123 alignLeft action 77 AUTO_SAVE_DASHBOARD_DELAY Alignment command 124 parameter 48 alignRight action 77 AUTOSUGGEST_DELAY parameter 126 ALLOW_EXPORT_PAGE_LIMIT parameter AUTOSUGGEST_FETCH_SIZE parameter 126 126 ALLOW_IV_PAGE_LIMIT parameter 126 AUTOSUGGEST_LIST_SIZE parameter 126 allscripts.js 53 autoSummarizeOn action 78 analytics gadgets 40 Availability tag 122 analyze action 76 Available Data options 83 Analyze button 123 axes values Analyze command 123 See also charts Analyze feature 123 Apache Tomcat servers 12 B deploying to 20 banner application context root 110 hiding features in 51 application context roots 28 bar charts application programming interfaces 130 See also charts application server cache 24 BaseActionForm class 61 application server configurations 20 Basic functionality level 50 application servers 3, 5, 10, 12, 19, 20, 21, 23 BEA WebLogic servers 20 applications 129 beans 59, 65 accessing data sources and 114 beans package 59, 63 changing 37 binary files 54 configuring 40 BIRT 360 web resources 40 configuring BIRT Studio environment for BIRT Design Engine API 130 84 BIRT Designer Professional 95, 105 deploying web 23 BIRT iHub. See iHub System designing custom reporting 5, 26, 31, 37 BIRT objects 105 developing 115 BIRT report documents 57 enabling or disabling BIRT functionality BIRT reports for 74, 75, 78, 83 See also reports registering servlets with 118 BIRT repository. See Encyclopedia volumes setting default locale for 42, 46 BIRT Studio 22, 40, 127 setting default time zone for 42 configuring 84 setting global styles for 37–38 creating text file data sources for 93 archiving 126 customizing 74 area charts data sources supported 108, 118 See also charts disabling actions for 75, 78, 80, 83 array elements 53

138 Installing Visualization Platform enabling ODA drivers for 115 birtviewer-extension.xml 130 limiting functionality of 74, 84 BIRT_VIEWER_LOCALE parameter 127 predefined data sources in 103 BIRT_VIEWER_LOG_DIR parameter 22 predefined themes in 89 BizRDRptTemplates folder 98 report parameters and 103 bookmark action 77 report template categories in 97, 100 bookmark parameter 57 setting up sample data sources for 109, 113 bookmarks unavailable features and 83 adding 77 BIRT Viewer 40 border action 77 displaying reports and 126 borders 77 extending functionality of 130 branding 74, 89 opening Interactive Viewer from 129 browsefile action 60 BIRT viewer 22 BrowseFileActionForm class 60 BIRT Viewer interface 122 browsers. See web browsers BIRT Viewer Toolkit browsertype.js 53 deploying 20 browsing 60 BIRT360PLUS_URL parameter 40 buffer size parameter 127 BIRT_ARCHIVE_ MEMORY_TOTALSIZE parameter 126 C BIRT_CHART_MAX_ROW parameter 126 C++ libraries 17 BIRT_CHART_MAX_VARIABLE_SIZE cache 84, 85, 128, 129 parameter 126 cache (web pages) 23 BIRT_CUBE_FETCH_LIMIT_ CACHE_CONTROL parameter 41, 128 COLUMN_EDGE parameter 127 caching web pages 41, 49 BIRT_CUBE_FETCH_LIMIT_ROW_EDGE CalculatedColumn feature 123 parameter 127 calculation action 75 BIRT_DATA_RESULTSET_MAX_BUFFER_ Calculations action set 75 SIZE parameter 127 cascading style sheets 127 BIRT_HTMLRENDEROPTION_ case sensitivity 26, 55 ENGCASSTYLE parameter 127 categories (templates) 97, 100, 101 BIRT_JDBC_CONNECTION_POOL_ Change Font command 124 TIMEOUT parameter 127 Change Type command 124 BIRT_JDBC_CONNECTION_POOL_SIZE changes, undoing or redoing 78 parameter 127 changeSubtotal action 75 BIRT_RENDER_FORMAT_ changing EMITTER_ID_MAPPING parameter 41 actions 75 BIRT_REPORT_ DOCUMENT_ configurations 32 CACHE_ENABLED parameter 84 folder names 99 BIRT_REPORT_ PAGE_COUNT_ functionality levels 53 CACHE_ENABLED parameter 84 images 38–40 BIRT_REPORT_DESIGN_ CACHE_TOTAL_ locales 22, 32 NUMBER_OF_ENTRIES parameter 84 reporting applications 37 BIRT_REPORT_DESIGN_CACHE_TIMEOU reports 85 T parameter 84 servlets 54, 55 BIRT_RESOURCE_PATH parameter 22, 84, styles 89 127 table type 77 BIRT_SCRIPT_LIB_PATH parameter 84, 127

Index 139 time zones 22, 32 comments (templates) 91 user interface elements 40 compilers 117 user roles 83 compiling JSPs 26 character encoding 48, 54 compiling servlet classes 117 character strings. See strings computed columns characters disabling user actions for 75 data object design file names 106 concurrent sessions 85 chart action 75 conditional formats 77 chart DPI settings 134 Conditional Formatting command 124 Chart Property command 123 conditionalFormat action 77 Chart Subtype command 123 ConditionalFormat feature 124 ChartProperty feature 123 configuration files 40, 122, 126, 130 charts configuration parameters 84, 126, 134 binding to rows 126 changing 32 disabling user actions for 75 iHub connections 48 selecting data for 104 iHub Visualization Platform client 31, 40 ChartSubType feature 123 Visualization Platform 32 class files 117 configurations class reference (JavaBeans) 60, 63 accessing iHub Visualization Platform classes 115, 117, 118, 130 client functionality and 40 ClassicModelQueryBuilder.jsp 115 accessing text file data and 94 ClassicModels sample database 112, 114 changing messages and 47 clearing web browser cache 24 changing user actions and 74, 75, 78, 83 ClearType text 10 connecting to iHub and 34, 46, 48 client applications 11 creating custom applications and 31–40 cluster nodes 49 customizing BIRT Studio and 74 clusters 2, 3, 4, 5, 11 customizing data sources and 118 deploying iHub Visualization Platform defining features and 51 client and 23 defining functionality levels and 50, 51, 53 code 114, 115 defining subfeatures and 52 CollapseExpand feature 123 deploying iHub Visualization Platform column headers client and 20 disabling user actions for 76 disabling load balancing and 5 searching 86 generating locale-specific sites and 46, 47 column names 111 invoking servlets and 55 column types 111 redirecting web pages and 6 Column Width command 124 registering query builder servlet and 118 ColumnEdit feature 123 running BIRT Studio and 84 ColumnHeaderOperations action set 76 running multiple applications and 5 ColumnOperations action set 76 running sample data sources and 109, 111, ColumnResize feature 124 113 columns setting application server ports and 12 See also fields setting up firewalls and 6, 7 disabling user actions for 76 specifying default template category and setting page breaks for 129 101 columnWidth action 76 specifying time zones and 47 comma-separated values files 86, 93 configuring

140 Installing Visualization Platform application servers 20 CreateFolderActionForm class 60 ClearType text 10 createSection action 77 iHub distribution setup script 18 creating Visualization Platform 22, 23 custom data sources 108–119 connecting to custom query builders 115–118 ClassicModels database 114 data objects 103, 105 Encyclopedia volumes 100 dedicated iHub accounts 16 ODA data sources 111, 116 features 53 connection parameters 26 folders 52, 60 connection pool 127 functionality categories 74 connection pools 49 functionality levels 50, 51, 53 connection properties 100, 112 home folders 71 connection timeout intervals 127 hyperlinks 61 connections iHub profiles 100 accessing data and 105 information objects 105 accessing Encyclopedia and 26 libraries 95 dropping 41 ODA drivers 114 establishing iHub 48 report templates 88, 91–93 running Visualization Platform and 24 reports 88 setting maximum number of 49 resource folders 96, 99 timing out 44 styles 95 CONNECTION_TIMEOUT parameter 41 template categories 100 console applications 11 text file data sources 93 context menus 122 themes 89, 94–97 limiting functionality 74, 75 tooltips 92 context paths 20 users 71 context root 110 web applications 5, 26 context roots 28 web pages 27 converter.js 54 cross tab elements 105 cookie.js 54 cross tab reports 104 COOKIE_DOMAIN parameter 42 cross tab templates 104, 105 COOKIE_ENABLED parameter 42 cross tabs cookies 42, 54 disabling user actions for 76 COOKIE_SECURE parameter 42 setting page breaks for 129 Copy Format command 125 Crosstab Builder 76 Copy Information Objects to Shared CrosstabOperations action set 76 Resources Folder command 107 CSV files 86, 93 Copy Library to Shared Resource Folder cubes 127 command 97 customizing Copy Style command 125 BIRT Studio 74 copyright statements 93 data sources 108–119 country codes 46, 47 functionality levels 51–53 CPUs messages 47 running Visualization Platform and 20 query builder 115–118 Create Template Report Item command 92 reporting applications 5, 26 createfolder action 60 styles 95, 96 CreateFolder subfeature 52 user interfaces 109

Index 141 Visualization Platform 19, 31, 32 controlling access to 104 Visualization Platform WAR files 22 creating 103, 105 deploying 104 D designing 105–?? DashboardBusinessUser subfeature 52 retrieving data from 93, 104 DashboardDeveloper subfeature 52 data points dashboards 27, 48, 52 See also charts dashboards servlet 27 data repository DASHBOARD_SHARED_RESOURCES See also Encyclopedia volumes parameter 49 data rows data caching 85 See also values disabling user actions for 76 accessing 103, 108 displaying 85 disabling user actions for 77 retrieving 86 displaying 26 setting maximum number of 85 filtering 60, 61, 67 data rows. See rows hiding 94 data series including in templates 88, 93 See also charts previewing 82 data set extensions 111, 116, 119 retrieving 104, 105 data sets 127 synchronizing 52 configuring custom data sources for 109 updating 83 hiding 94 viewing restrictions for 128 including in templates 88, 93 data action 77 joining 83 Data Analyzer 76 retrieving 93 data buffer 127 selecting 93 data cache 85 Data Source dialog box 111, 119 data cubes 127 data source extensions 111, 116, 119 data fields data sources disabling user actions for 75 accessing data in 103, 108 .data files 104 accessing external 105 data filters configuring 118 disabling user actions for 75 connecting to ODA 111, 114, 116 specifying number of rows to retrieve 86 creating templates and 93 data filters. See filters customizing 108–119 data items naming 111, 119 adding to data objects 105 retrieving data from 104, 105 data models 26 selecting 103 data object data sources 103, 104 setting up CSV flies as 93 data object design file names 106 setting up data objects as 103 data object designs 104 testing custom 110, 112 data object store data sources 104 data stores 22 data object stores 104 Data Tools Platform projects (Eclipse) 114 data objects database connection properties 112 adding data items to 105 database servers 5 building reports and 103 databases 104, 111 .datadesign files 104

142 Installing Visualization Platform dataFields action 75 data objects 104 dataObject element 111 iHub distribution package 17 datasetDisplayName element 111 information objects 107 datasetExtensionId element 111, 119 query builder servlet 117 datasourceExtensionId element 111, 119 reports 3, 10 data-sources element 94 Visualization Platform 2, 12, 19–23 date-and-time formats 127 WAR files 19 debugging messages 43 deploying BIRT Viewer Toolkit 20 decompressing WAR files 23 deployment tools 20 default context root 28 descending sort order 78 default Encyclopedia volume 66 description element 111, 119 default error codes 47 Description property 92 default locale 22, 32, 42, 46, 65, 85, 128 design cache 84 default settings 32, 33 Design Engine API 130 default template category 98 design files 76 default templates 89 design tools 74 default time zone 22, 42, 85, 128 designing DEFAULT_COLUMN_PAGE_BREAK_ data objects 103, 105–?? INTERVAL parameter 129 report templates 88, 91 DEFAULT_DATA_CACHE_ROW_COUNT reports 74 parameter 85 designing custom web applications 5, 26, 31, DEFAULT_LOCALE parameter 22, 32, 42, 85, 37 128 designs 127 DEFAULT_PAGE_BREAK_ INTERVAL editing 85 parameter 85 limiting functionality 74, 76 DEFAULT_PAGE_BREAK_INTERVAL purging 84 parameter 42, 129 saving 91 DEFAULT_REPORT_TEMPLATE_ detail rows 77 CATEGORY_NAME parameter 85, 101 detail table mode 77 DEFAULT_ROW_PAGE_BREAK_ developing INTERVAL parameter 130 custom query builders 115–118 DEFAULT_TIMEZONE parameter 22, 32, 42, ODA data drivers 114 85, 128 web applications 115 delete action 76 directories 28, 29 Delete Column command 123 deploying Visualization Platform and 22 Delete Group command 124 extracting product files to 11 deleteColumn action 76 directory names 26 DeleteColumn action set 76 directory paths DeleteFile subfeature 52 cross tab templates 105 DeleteFolder subfeature 52 flat file ODA drivers 114 deleteRow action 76 home folders 73 deleteSection action 77 sample query builder 115 deleting sample query builder servlet 117 folders 52 script libraries 84 report files 52 shared resources 84 deploying template files 98 cross tab templates 105 text file data sources 94

Index 143 disk space 45 dynamic value parameters 85 Display Name property 92 display names 46, 47, 90, 92, 111, 119 E displaying EAR deployments 21 data 26 Eclipse DTP project components 114 data rows 85 edit action 76 distinct values 129 Edit Computed Column command 123 files and folders list 42 edit text icon 125 folders 67 editable report elements 90, 92, 93 libraries 97 editCalculation action 75 locales 46 EditReport feature 124 page layouts 77 editText action 76 report elements 95 EditText action set 76 report executables 67 emitters 41, 133 report templates 90, 97 Enable Interactivity command 124, 129 reports 27, 29, 45, 54, 57 ENABLE_CLIENT_SIDE_REDIRECT table of contents 125 parameter 6, 42 displayName element 111, 119 enabled attribute 75 DisplayName tag 46, 47 ENABLE_DEBUG_LOGGING parameter 43 distinct values 129 enabledInEnterpriseMode element 110, 111, .do file name extensions 26 113, 119 Do Not Repeat Values command 125 enabledInWorkgroupMode element 111, 119 doc format value 57 ENABLE_ERROR_LOGGING parameter 43 document cache 84 ENABLE_JUL_LOG parameter 43 document classes 60 EnableNewAggregationStyle attribute 82 document files 67 EnableSampleDataInPreview attribute 82 documentation v encode method 54 Visualization Platform deployments and encoder.js 54 19 encoding 48, 54 documents 84 Encyclopedia volumes See also reports accessing 48, 68 exporting specific pages 126 adding objects to 52 Documents attribute (features) 51 connecting to 26, 100 Documents page 60 creating folders for 60 domains 42 creating resource folders for 99 DownloadFile servlet 56 creating user accounts for 70 DownloadFile subfeature 52 deleting objects in 52 downloading downloading from 52, 56 binary files 54 publishing information objects to 106, 107 product files 11 publishing template resources to 101 reports 56 publishing templates to 98, 99 DPI settings running Visualization Platform and 2 chart resolution 134 specifying default 66 drift.js 54 entryPoint element 111, 119 drivers 108, 111, 114 erni_config.xml 74, 118 DTP project components (Eclipse) 114 error codes 47 dynamic data 53

144 Installing Visualization Platform error log files 43, 44 feature lists 63, 66, 67 error messages Feature tag 122 localizing 47–48 FeatureConfiguration tag 122 ERROR_LOG_FILE_ROLLOVER parameter FeatureControl tag 122 43 FeatureID tag 51 errors 43, 122 FeatureOptionsBean class 62 errors (console applications) 23 features 51, ??–53, 62, 67, 74, 83, 122, 123 event handler methods 131 fields Excel emitters 133 See also columns Excel formats disabling user actions for 75 configuring default settings for 135 file cache 86 Excel spreadsheets 129 file IDs 56 exceptions 122 file lists 42, 60, 66 executable files file name extensions 106 displaying 67 file names 26, 106 EXECUTE_DASHBOARD_GADGET_ file numbers 44 GENERATION_ WAIT_TIME parameter 43 file paths 127, 130 EXECUTE_REPORT_WAIT_TIME parameter filefoldersprivilege action 60 43 FileFoldersPrivilegeActionForm class 60 executing fileId parameter 56 Java servlets 55 FileListActionForm class 60 jobs 27 FileOperations action set 76 Export Content command 124 files Export Data command 124 accessing 27, 60 export options 129 archiving 126 EXPORT_AS_ATTACHMENT parameter 129 converting to ASCII 48 ExportData feature 124 deleting 52 ExportElement feature 124 disabling user actions for 76 ExportElementData feature 124 downloading 56 exporting downloading iHub 11 report content 126, 133 getting information about 60 specific report pages 126 purging 84, 86 ExportReport feature 124 saving 54 extended sample ODA data source 108, 112, sharing 52 114, 118 Files and Folders page (Management extension IDs 111, 116, 119 Console) 70 external data sources 105 filesfolders JSPs 27 extracting filter action 75 iHub product files 11 filter action forms 60, 61 web archives 23 Filter command 124 Filter feature 124 F filtering Facebook Comment command 124 data 60, 61, 67 FacebookComments feature 124 filters 66 failover 5 disabling user actions for 75 feature definitions 51 retrieving distinct values and 129 specifying number of rows to retrieve 86

Index 145 Firefox browser 129 ftp distributions firewalls 6, 7, 12 iHub System 11 flashchartsxml format value 57 functionality categories 74 FlashGadgetFormat feature 124 functionality levels 83 FlashGadgetType feature 124 adding 50, 51, 53 flat file ODA drivers 114 associating with users 50, 51 floatingfooter parameter 57 changing 53 folder lists 42, 60, 65, 66 customizing 51–53 folder names 65, 99 naming 51 folders preserving 53 accessing 27 specifying features for 51 accessing reports and 70 specifying subfeatures for 52 copying ODA driver files to 115 functionality options 84 creating 52, 60 functionality-level.config 83 creating home 71 functions 115 creating resource 96, 99 See also methods creating temporary files and 130 deleting 52 G deploying query builder class files to 118 gadget gallery 49 displaying 67 GADGET_ GENERATION_ WAITING_TIME getting home 63 parameter 43 navigating through 29 gadgets 43 publishing information objects and 106 gadgets interface 27 publishing resource files to 102 garbage collection 43 publishing templates to 98 GeneralFilterActionForm class 60, 61 specifying resource 22 GeneralOperations action set 77 specifying type 66 generating viewing information about 60 web pages 6–11, 26, 27 viewing library files in 97 generating reports 129 font action 77 getAcLocale method 63 footers 57, 82 getAdminRights method 63 FORCED_GC_INTERVAL parameter 43 getAuthid method 63 Format command 124 getCurrentfolder method 63 format emitters 133, 134 getDefaultServerURL method 63 Format feature 124 getDefaultVolume method 63 Format Flash Gadget command 124 getFeatureBean method 62 format parameter (Interactive Viewer) 57 getFeatureOptionsBean method 63 formats getFeatures method 63 displaying reports and 57 getfiledetails action 60 limiting functionality 74, 77 GetFileDetailsActionForm class 60 formatting getFilter method 63 reports 89 getHomefolder method 63 Formatting action set 77 getIportalid method 63 formatting options 89 getjobdetails action 61 forms package 59 GetJobDetailsActionForm class 61 from_page_range parameter 57 getLocale method 63 from_page_style parameter 57

146 Installing Visualization Platform getMaxJobPriority method 63 hideDetail action 77 getOnlylatest method 64 HideShowItems feature 124 getPassword method 64 hiding getProfile method 62, 64 data 94 getProperty method 64 grid lines 133 getRepositoryType method 64 toolbars 125 getRoleNames method 64 Highlight feature 124 getServerurl method 64 highlighting 124 getShowdocuments method 64 home directory 28 getShowexecutables method 64 home folders 63, 66, 70, 71 getShowfolders method 64 HOME property 94 getSideBarFeatures method 64 hosts 42 getSidebarSelected method 64 HoverHighlight feature 124 getSubfeatures method 64 HTML code 37 getSystemname method 64 html format value 57 getTimezone method 64 HTML formats 77 getUserAgent method 64 rendering to 127 getUserid method 65 htmlselect.js 54 getView method 65 HTTP requests 6, 45, 62 getVolume method 65 HTTP sessions 132 global style elements 37–38 HTTPServlet class 115 global variables 53 hyperlink action 78 Grand Total option 124 hyperlinks GrandTotal feature 124 creating 61 graphical window manager 17 disabling user actions for 78 graphs. See charts grid lines 133 I group footers 82 IBirtViewerContext interface 132 group headers 82 IBirtViewerExtension interface 131 groupBy action 77 IBirtViewerOp interface 132 GroupEdit feature 124 IBirtViewerSession interface 132 Grouping action set 77 IBM WebSphere servers 20 groups IContentList interface 59 aggregating data and 82 IDAPI_TIMEOUT parameter 44 disabling user actions for 77 idle connections 127 iHub H balancing workload on 4, 5, 33 heap size 21 connecting to 34, 46, 48, 66 help 77, 91, 92 copying ODA driver files to 115 help action 77 creating profiles for 100 Help action set 77 creating user accounts for 70 Help menu 126 deploying Visualization Platform and 2 Hide Column command 123 installing Visualization Platform with 3, 11, Hide Detail command 123 44 Hide/Show Item command 124 publishing information objects to 106, 107 hideColumn action 76 publishing template resources to 101

Index 147 publishing templates to 98, 99 running multiple instances of 5 running BIRT Studio and 85 setting application server port for 12 sending requests over 6, 29 setting connection parameters for 24 iHub distribution package 17 setting context paths for 24 iHub distribution setup script setting log file location for 22 configuring 18 setting port number for 24 running 19 starting 6, 24 iHub licensing options 70 testing installations for 24 iHub profile property 100 viewing available locales for 46 iHub System 3, 10, 26 Information Delivery API 6 creating dedicated account for 16 information object files 107 downloading files for 11 information object projects firewalls and 12 selecting 107 integrating application servers with 20 information objects required libraries for 17 creating 105 iHub system names 67 deploying 107 image cache 129 enabling or disabling BIRT functionality image files 101 for 83, 84 imageid parameter 57 publishing 106, 107 images 90, 92, 101 informational text 91 changing 38–40 init method 65 inedit parameter 116 insertRow action 76 information 65 installation Information Console C++ libraries 17 accessing functionality 40, 54, 59 Java Runtime Environment 12 adding web pages to 27 Java Software Development Kit 12 adjusting layers for 54 missing files and 11 assigning CPUs to 20 testing 24 caching web pages for 23 Visualization Platform 3, 10, 11, 19 changing default settings for 32, 33 installation wizard 12 configuring 22, 23 installing Visualization Platform 3, 11, 44 configuring as web applications 31–40 INSTALL_MODE parameter 44 configuring BIRT Studio for 84 instanceid parameter 57 configuring proxy servers for 6, 7 interactive features 123 copying ODA driver files for 115 Interactive Viewer 52, 56 creating custom applications for 5, 26 displaying reports and 126 customizing 19 starting 129 defining user actions and 83 Interactive Viewer servlet 56 deploying 2, 12, 19–23 InteractiveViewing subfeature 52 installing 3, 10, 11, 19, 44 Intermediate functionality level 50 integrating custom query builder with 115 Internet Explorer 129 integrating with application servers 23 IO Design perspective 105 localizing messages for 47–48 iportal context root 24, 28 logging in to 24 iportal directory 30 missing functionality for 23 iportal.jar 117 overview 5 isAlwaysGetFolderList method 65 resizing pages for 54 isHomeFolderSet method 65

148 Installing Visualization Platform isIE method 62 executing 27 isNS4 method 62 getting information about 61 isNS6 method 62 sending notifications for 52 isShowFilters method 65 setting priorities for 52, 66 isViewInNewBrowserWindow method 65 setting properties for 62 iv_config.xml 122 submitting 27, 62 IV_ENABLE_IV parameter 129 Jobs attribute (features) 51 joins 83 J JRE files 12 J2EE installations 20 JREM_TASK_QUEUE_SIZE parameter 129 Jakarta Struts Framework 54 JREM_THREADPOOL_MAXSYNC_ JAR files 130, 133 TASKRUNTIME parameter 129 JAR files (query builder servlet) 117 JREM_THREADPOOL_MONITORTHREAD Java classes 130 _ POLLINGINTERVAL parameter 129 Java heap size 21 JREM_THREAD_POOL_SIZE parameter 129 Java programming interfaces 130 JREM_THREADPOOL_SYNC_TASKQUEUE Java Runtime Environment 12 _TIMEOUT parameter 129 Java Server Pages 23 JSP engine 3, 6, 10 Java Software Development Kit 12 JSPs 23 JavaBean methods 59 accessing 29 JavaBeans 59, 65 compiling 26 JavaBeans class reference 60 generating web pages and 11–27 JavaBeans package reference 59 implementing URIs and 28 javac compiler 117 implementing URLs and 26 Javadoc 59 selecting templates for 29 JAVA_REPORT_API_IMAGE_CACHE_ JUL_LOG_CONSOLE_LEVEL parameter 44 EXPIRATION parameter 129 JUL_LOG_FILE_COUNT parameter 44 JavaScript API 30 JUL_LOG_FILE_LEVEL parameter 44 JavaScript code 26 JUL_LOG_FILE_SIZE_KB parameter 44 JavaScript components 54 JavaScript files L developing web applications and 53 labels 47 JavaScript functions 115 landing page 29 JavaScript reference 53 language codes 46, 47 JavaServer Pages (JSPs) 115 languages 40 JBoss servers 20 launchiv parameter 57 JDBC connection pool 127 layer functionality 54 JDBC data sources 108, 109, 111 layer.js 54 JDBC database connections 112 Level tag 53 JDBC drivers 114 libraries 17, 84, 89, 95, 96, 127 JDK files 12 library files 96, 101 job action forms 61 licenses 72 job classes 61 licensing options 70 JobActionForm class 61 line charts JobPriority subfeature 52 See also charts jobs Link tag 61

Index 149 Link To This Page command 124 ManageData action set 76 LinkBean class 61 Management Console 3, 10, 51, 54 links 6 adding resource folders and 99 LinkToThisPage feature 124 creating user accounts and 71, 73 Linux servers manuals. See documentation installing Openmotif bundle for 17 MAX_BACKUP_ERROR_LOGS parameter setting run level for 17 44 setting up user accounts for 16 MAX_BRSTUDIO_DESIGN_SESSION Linux systems 4, 10, 28 parameter 85 list package 59 MAX_BRSTUDIO_USER_SESSION lists 42, 44, 59 parameter 85 load balancing 4, 5, 33 MAX_CONNECTIONS_PER_SERVER locale codes 46, 47 parameter 49 locale IDs 46 MAX_DATA_CACHE_ROW_COUNT locale names 46 parameter 85 locale parameter 58 MAX_LIST_SIZE parameter 44 Locale tag 46 MAX_NUMBER_OF_VALUES_FOR_ locales DYNAMIC_PARAMETER parameter 85 accessing repository for 26 MDS_ENABLED parameter 5, 33, 49 adding 46 MDS_REFRESH_FREQUENCY_SECONDS configuring 46, 47 parameter 33, 49 creating error messages for 47–48 memory 43, 49 selecting templates for 91, 101 MEMORY_DATA_CACHE_ROW_COUNT setting default 22, 32, 42, 46, 65, 85, 128 parameter 85 specifying 127 menus 51, 54, 122 localizing messages 47–48 limiting functionality 74, 75 log file numbers 44 merge action 76 log files 22, 43, 44 mergeColumns action 76 LOG_FILE_LOCATION parameter 22, 44 Message Distribution Service 4, 33, 49 logging in to messages (templates) 91 Visualization Platform 24 method calls 65 logging levels 44 methods 53, 59, 116 login action 7 See also functions login forms 62 missing product files 11 login information 42, 62 Mobile attribute (features) 51 LoginForm class 62 MOBILE_APP_DOWNLOAD parameter 45 logins Model-View-Controller architecture 26 getting user information for 62 Modify button 83 redirecting 6 MORE_VALUE_ROW_COUNT parameter 86 LOGIN_TIMEOUT parameter 44 Move To Group command 124 Move to Left command 125 M Move to Right command 125 machine names 12 MoveColumn feature 125 MainMenu feature 124 moveToDetail action 76 Manage Data dialog box 76 moveToGroup action 76 manageData action 76 multi-user mode 17

150 Installing Visualization Platform N ODA data source configurations 112 ODA data source extensions 111, 116, 119 name element 111, 119 ODA data sources 109, 112, 118 name parameter ODA design sessions 116 DownloadFile servlet 56 ODA drivers 108, 114 named user licenses 70 ODA framework 114 names ODA session IDs 116 changing folder 99 odaColumn dataType element 111 predefined styles and 95 odaColumn name element 111 report elements 90 odaconfig element 118 servlets 118 odaPassword element 111 naming OdaSample data source 110 data object design files 106 OdaSampleExt data source 112 data sources 111, 119 odaURL element 111 editable report items 92 odaUser element 111 functionality levels 51 online documentation v non-editable report items 93 open action 76 report elements 90 opening report templates 92 Interactive Viewer 52, 129 resource folders 99 reports 129 users 71 Visualization Platform 24 naming restrictions 26, 55 web browser windows 68 native2ascii utility 48 Openmotif bundle 17 networked environments 11, 130 operating systems 70 configuring run levels for 17 option controls 54 networks 2, 4, 45 options JSPs 27 new action 76 options page 62 New Computed Column command 123 Outline view 95 New Data Object dialog 105 output format emitters 133, 134 New iHub Profile wizard 100 New Library wizard 95 P New Style command 95 New Style wizard 95 packages 59 New Template wizard 92 Page Break command 125 New Theme wizard 96 page breaks 42, 77, 85, 129 New User page (Management Console) 71 page engine 6 non-editable report elements 90, 93 page layout toggle 77 noRepeat action 76 page layouts notifications displaying 77 sending 52 page navigation icons 125 NUMBER_OF_FILTER_VALUES parameter page parameter 58 129 page ranges 57 numeric formats 127 page styles 57 pageBreak action 77 O PageBreak feature 125 PageLayout action set 77 objects 105 pageLayoutInToolbar action 77 ODA data set extensions 111, 116, 119

Index 151 PageNavigation feature 125 retrieving data and 104 parameter action 77 performance analytics gadgets 40 Parameter button 125 permissions. See privileges parameter definitions 32 PERSISTENT_ ARCHIVEFILECACHE_ Parameter feature 125 TIMEOUT_SECONDS parameter 86 parameters ping action 61 adding custom query builder and 116 PingActionForm class 61 adding data objects and 103 pivot tables 133 changing 32 plug-ins 133 configuring BIRT Studio and 84 poling intervals 129 configuring report viewers and 126 pop-up menus 54 configuring Visualization Platform and 40 popupmenu.js 54 connecting to Encyclopedia and 26, 48 ports 6 customizing reporting applications and 31, Apache Tomcat service 12 32 Visualization Platform 24 deploying Visualization Platform and 22, PostgreSQL databases 24 installing iHub and 16 disabling user actions for 77 PostScript formats formatting output and 134 configuring default settings for 135 loading JSPs and 26 PowerPoint documents 129 loading web pages and 27 PowerPoint formats prompting for 126 configuring default settings for 135 setting number of values displayed 85 ppt format value 57 Parameters dialog box 85 predefined data sources 103 parameters page 126 predefined styles 95 passwords predefined themes 89 creating users and 71 presentation models 26 getting 64 presentations 88 setting 66 Preview action set 77 paths 127, 130 previewHTML action 77 cross tab templates 105 previewing dashboard resources 49 data 82 flat file ODA drivers 114 Print command 125 home folders 73 Print feature 125 log files 44 printing sample query builder 115 reports 126 sample query builder servlet 117 prioritizing jobs 52, 66 script libraries 84 private cache 41 shared resources 84 privileges 4, 10, 60 template files 98 accessing data objects and 105 temporary files 45, 49 installing Visualization Platform and 11 text file data sources 94 publishing information objects and 106, pdf format value 57 107 PDF formats publishing templates and 100 configuring default settings for 134 process redirect page 6 performance 43, 127 product files 11 previewing data and 82 ProfileBean class 62

152 Installing Visualization Platform ProfileName parameter 35, 46 redirection 6, 42 profiles 34, 46, 50, 62, 66 redo action 78 selecting iHub 100 refresh intervals 34, 49 progressive viewing 45 refreshes (web pages) 24 PROGRESSIVE_REFRESH parameter 45 registering query builder servlet 118 PROGRESSIVE_VIEWING_ENABLED relational databases parameter 45 See also databases projects remote servers 11 selecting 107 renaming themes 95 properties 66 rendering reports 127 Encyclopedia connection 100 Reorder Columns command 125 JDBC database connection 112 reorderColumns action 76 report template 90, 92 ReorderColumns feature 125 setting iHub distribution script 18 Repeat Values command 125 styles 95, 96 repeatValues action 76 .properties files 101 report design cache 84 properties files 22 report design files 76 protecting data. See security Report Design perspective 88, 92 proxy servers 5, 6, 7, 45, 128, 130 report design tools 74 PROXY_BASEURL parameter 45, 130 report designs 127 ps format value 57 editing 85 Publish Resources dialog box 102 limiting functionality 74, 76 Publish Resources to iHub command 102 purging 84 Publish Templates dialog box 99 saving 91 Publish Templates to iHub command 99 report document cache 84 Publish to iHub command 107 report document files 67 publishing report documents 84 information objects 106, 107 See also reports resources 101–103 exporting specific pages 126 templates 97–101 report elements purging cached files 84, 86 adding to libraries 95 adding to templates 88, 90, 92 Q applying styles to 95 queries 111, 116 naming 90, 92 See also SQL statements report emitters 41, 133 query builder Report Encyclopedia. See Encyclopedia developing custom 115–118 volumes setting entry point for 111, 119 report executable files 67 query builder page 113 report files query builder servlet 115–118 accessing 27, 60 queryText element 111 archiving 126 queue 129 deleting 52 downloading 56 R getting information about 60 saving 54 records. See rows sharing 52 redirect attribute 7 report items

Index 153 assigning bookmarks to 77 creating 88 assigning hyperlinks to 78 deploying 3, 10 formatting 89 designing 74 including in templates 92 displaying 27, 29, 45, 54, 57 __report parameter 58 downloading 56 report parameters 103 exporting content 126, 133 report section headings formatting 89 adding fields to 78 generating 129 report sections including in templates 88 disabling user actions for 78 opening 129 report template categories 97, 100, 101 printing 126 Report Template dialog box 90, 101 refreshing 45 report template files 91, 92, 98 rendering HTML 127 report templates 22, 127 running 43 accessing resources for 101 selecting data for 108 adding report elements to 88, 90, 92 selecting data sources for 103 adding themes to 89, 94–97 setting page breaks for 77, 85, 129 associating libraries with 96 standardizing 89 building cross tabs and 104, 105 structuring 88, 90 changing styles in 89 submitting requests for 6 creating 88, 91–93 repositories designing reports and 88, 90 accessing items in 27 disabling user actions for 78 downloading from 58 displaying 90, 97 repository excluding data sets in 94 See also Encyclopedia volumes localizing 91, 101 REPOSITORY_CACHE_TIMEOUT_SEC naming 92 parameter 49, 130 providing data with 93 repositoryType parameter 58 providing descriptions for 90, 92 request parameters 116 providing images for 90, 92 requests 116, 128, 129 publishing 97–101 limiting number of items returned 44 setting properties for 90, 92 loading web pages and 27 specifying default category for 85, 101 running multiple applications and 5 specifying editable report elements for 92 sending 4, 26, 29 specifying non-editable report elements submitting 6 for 93 timing out 41 report viewer activity logs 22 Resize feature 125 report viewers 56 resize.js 54 report.js 54 resource files 47, 103 reporting system. See iHub System Resource folder property 99 reporting tasks 122 resource folders 22, 96, 99, 102 ReportItemOperations action set 77 resources 26, 27, 35, 46, 53, 127 reportlet format value 57 accessing 22 reports accessing shared 84, 97, 106 accessing 70 deploying data objects and 104 changing 85 publishing information objects and 107 controlling user actions for 74, 75, 78, 83 publishing template 98, 101–103

154 Installing Visualization Platform thumbnail images and 92 script libraries 84, 127 result set buffer 127 scroll control panel 125 reverse proxies 6 ScrollControl feature 125 Role tag 51 Search attribute (features) 51 roles 74, 83 Search page 60 creating 50, 66 search results 86 defining functionality levels and 50, 51 SEARCH_ENABLE_COLUMN_HEADERS rows parameter 86 binding to charts 126 searchfiles action 60 caching 85 SearchFilesActionForm class 60 disabling user actions for 76 SEARCH_USE_QUOTE_DELIMITER displaying 85 parameter 86 retrieving 86 section headings setting maximum number of 85 adding fields to 78 setting page breaks for 130 sectionHeading action 78 .rpttemplate files 91 SectionOperations action set 78 rtl parameter 58 sections run levels (Linux) 17 disabling user actions for 78 running security 16, 41, 128 iHub distribution setup script 19 security roles 74, 83 Java servlets 55 SECURITY_ADAPTER_CLASS parameter 45 jobs 27 Select Data dialog box 94 reports 43 selection parameter 116 selectjobs action 62 S SelectJobsActionForm class 62 sample data 82 SelfNotificationWithAttachment subfeature sample database 112, 114 52 sample ODA configurations 109, 111, 113 sending notifications 52 sample ODA data source 109 sending requests 26, 29 sample query builder 115 series sample query builder servlet 115, 117 See also charts SampleServlet.class servlet 117 Server Print command 125 SampleServlet.java 115 server URLs 66 save action 76 ServerPrint feature 125 Save Design command 125 servers 20, 128, 130 Save Document command 125 See also iHub servers saveAs action 76 balancing workload among 4, 5, 33 saveas.js 54 deploying Information Console to 20 SaveDesign feature 125 deploying Visualization Platform over 2 SaveDocument feature 125 deploying Visualization Platform to 12, 20 saving dropping connections to 41 dashboards 48 extending functionality of 54 report designs as templates 91 installing Visualization Platform on 3, 11 report files 54 integrating Visualization Platform with 23 scatter charts maintaining session states for 5 See also charts optimizing performance for 43 preventing cache conflicts for 24

Index 155 running multiple applications and 5 setTimezone method 67 sending requests over 6, 27 setUserAgent method 67 setting context roots for 20 setUserid method 67 setting port numbers for 12 setView method 68 setting up firewalls and 6, 7 setViewInNewBrowserWindow method 68 serverURL parameter setVolume method 68 Interactive Viewer servlet 58 Share Information Objects dialog box 107 servlet element 118 shared resources 84, 97, 106 servlet engine 3, 6, 10 ShareFile subfeature 52 servlet names 55, 118 ShareFormat feature 125 servlet.jar 117 ShareStyle feature 125 servlet-mapping element 118 Show Column command 123 servlets 26, 27, 54–55 Show Detail command 123 creating query builder and 115, 115–118 showColumns action 76 servlets reference 55 showDetail action 77 session IDs 116 ShowTooltip feature 125 session state 5 side menu 51 SESSION_DEFAULT_PARAMETER_ Sort Ascending command 125 VALUE_ID parameter 45 Sort Descending command 125 sessionId parameter 116 Sort feature 125 sessions 5, 42, 44, 45, 85, 116 sort order 78 sessionTimeout parameter 45 sortAscending action 78 Set Template Property page 92 sortDescending action 78 setAcLocale method 65 Sorting action set 78 setAlwaysGetFolderList method 65 source code 114, 115 setAuthid method 65 split action 76 setCurrentfolder method 65 spreadsheets 129 setDefaultServerURL method 66 SQL statements setDefaultVolume method 66 See also queries setFeatureOptions method 66 stack trace (exceptions) 122 setFilter method 66 Standard Viewer 56 setHomefolder method 66 starting setMaxJobPriority method 66 Interactive Viewer 129 setOnlylatest method 66 Visualization Platform 24 setPassword method 66 starting Visualization Platform 6 setProfile method 66 state parameter 116 setProperty method 66 static text 76 setRequest method 62 static value parameters 85 setRoleNames method 66 strutscommon.js 54 setServerurl method 66 style definitions 37 setShowdocuments method 67 style sheets 127 setShowexecutables method 67 styles 37–38, 89, 95 setShowFilters method 67 SubfeatureID tag 52 setShowfolders method 67 subfeatures 52 setSideBarFeatures method 67 submitjob action 62 setSidebarSelected method 67 SubmitJobActionForm class 61, 62 setSystemname method 67 submitting jobs 27, 62

156 Installing Visualization Platform SubTotal feature 125 adding report elements to 88, 90, 92 subtotal functions 75 adding themes to 89, 94–97 SubTotal option 125 associating libraries with 96 summary table mode 77 building cross tabs and 104, 105 summary tables building JSPs and 29 converting to detail tables 77 changing styles in 89 disabling user actions for 75 creating 88, 91–93 summary values designing reports and 88, 90 See also aggregate data disabling user actions for 78 SuppressDuplicate feature 125 displaying 90, 97 Switch View command 125 excluding data sets in 94 switchSummaryMode action 77 localizing 91, 101 switchView action 76 naming 92 SwitchView feature 125 providing data with 93 symbolic links 17 providing descriptions for 90, 92 Synchronize Data Sets button 83 providing images for 90, 92 synchronizing data 52 publishing 97–101 system names 67 setting properties for 90, 92 specifying default category for 85, 101 T specifying editable report elements for 92 Table Builder specifying non-editable report elements enabling or disabling 77 for 93 table elements 93 TemplateTableOperations action set 78 table of contents 125 temporary files 22, 45, 49, 84, 86, 130 table type conversions 77 temporary server profiles 36 tableBuilder action 77 testing tables sample ODA data sources 110, 112 disabling user actions in 78 Visualization Platform installations 24 displaying aggregate data in 82 text 47 setting number of rows in 85 disabling user actions for 76 tab-separated values files 86 localizing 91, 101 tags providing informational 91 adding locales and 46 text file data sources 93 adding time zones and 47 text files 48 defining functionality levels and 51 text strings. See strings defining subfeatures and 52 TextEdit feature 125 temp directory 49 themes TEMP_FOLDER_LOCATION parameter 22, creating 89, 94–97 49, 130 renaming 95 template categories 97, 100, 101 selecting 74, 89 Template Category property 100 updating 89 template files 91, 92, 98 Themes list 95 Template Image property 92 third-party applications 4 Template page 92 thread pool 129 templates 22, 127 threads 21 accessing resources for 101 thumbnail images 92, 101 time formats 127

Index 157 time zone IDs 47 loading servlets and 54 time zones 22, 32, 40, 42, 47, 67, 85, 128 redirecting web pages and 6 time-out values 41, 44, 45 submitting requests and 6, 29 TimeZone tag 47 URLs 130 TOC command 125 connecting to iHub System and 26, 34, 46, Toc feature 125 66 Tomcat servers 12 custom query builder 119 Toolbar feature 125 ODA data drivers 114 ToolbarHelp feature 126 ODA data source connections 111 toolbars 54, 74, 75, 89, 122, 125 query builder 111 tooltips 92, 125 query builder servlet 118 Top/BottomN command 126 redirecting web pages and 6, 42 TopBottomNFilter feature 126 setting up firewalls and 6 toString method 61, 65 specifying default 66 trace (exception stack) 122 transmitting actions and 26 TRANSIENT ARCHIVEFILECACHE_ Visualization Platform 24 TIMEOUT_SECONDS parameter 86 UsageInBRS property 94 transient files 22, 45, 49, 84, 86, 130 Use Library command 97 TRANSIENT_STORE_MAX_SIZE_KB Use Library dialog box 97 parameter 45 user accounts 70, 71, 73 TRANSIENT_STORE_PATH parameter 22, 45 adding dedicated iHub System 16 TRANSIENT_STORE_TIMEOUT_SEC installing on Linux systems and 16 parameter 45 user classes 62 TSV files 86 user IDs 16, 58, 59, 67 types. See data types user interfaces 108, 109 changing elements in 37–40 U enabling features for 50, 51 unavailable features 83 enabling subfeatures for 52 undo action 78 submitting requests and 6 UndoRedo action set 78 user names 71 unencode method 54 user option settings 27 ungroupBy action 77 user profiles 62, 66 Uniform Resource Locators. See URLs user-agent header 62 UNIX systems 4, 10, 28 UserAgentBean class 62 unprivileged user IDs 16 UserAgentBean objects 67 updating userid parameter 58, 59 actions 75 UserInfoBean class 62, 63–68 data 52, 83 UserOptionsActionForm class 62 themes 89 users upgrades 53 assigning licensing options 70 UPLOAD_FILE_TYPE_LIST parameter 46 changing roles for 83 uploading binary files 54 creating 71 UPLOAD_SECURITY_MANAGER getting passwords for 64 parameter 46 limiting BIRT Studio functionality for 74, URIs 75, 78, 83 implementing 28 providing tooltips for 92 returning information about 62, 63

158 Installing Visualization Platform selecting functionality levels 62 Interactive Viewer servlet 58 setting features for 67 volume profiles 34–36, 46–??, 50 setting functionality levels for 50, 51 VOLUME_PROFILE_LOCATION parameter setting passwords for 66, 71 50 specifying home folders for 71 VolumeProfiles tag 35 Users page (Management Console) 71 volumes. See Encyclopedia volumes V W value parameters 85 wait values 41, 43 values WAR deployments 21 See also data WAR files 12, 19, 21, 22 creating tooltips for 92 web administrator privileges 11 variables 126 web applications 5, 23, 84, 115, 118 version parameter web browsers 23, 70 DownloadFile servlet 56 detecting 53, 62 Version property 100 displaying reports and 128, 129 versioning options 100 loading web pages for 27 view constants 68 maintaining session state for 5 viewer activity logs 22 opening new windows for 68 viewer servlet 56 preserving login information for 42 viewers 56 redirecting 6, 42 viewing rendering reports and 127 data 26 setting cache for 41, 128 data rows 85 specifying 67 distinct values 129 web pages 23 files and folders list 42 adding 27 folders 67 caching 41, 49 libraries 97 generating 6–11, 26, 27 locales 46 loading 27 page layouts 77 resizing 54 report elements 95 submitting requests and 6 report executables 67 web resources 26, 27 report templates 90, 97 web servers 3, 11, 21 reports 27, 29, 45, 54, 57 web sites 3, 10 table of contents 125 web.xml 40, 84, 118, 126 viewing restrictions 128 WEB-INF directory 40 viewnav.js 54 WebLogic servers 20 views 68 WebSphere servers 20 visible attribute 75, 80 window displays 54 visual report elements 88 Windows language pack 48 Visualization Platform 126, 127 Windows systems 4, 10, 28 Visualization Platform technology 2 configuring firewalls for 12 volume administrators 104 installing JDK files for 12 volume names installing JRE files for 12 accessing Visualization Platform and 12 installing Visualization Platform for 11, 19 volume parameter Word documents 129

Index 159 X x-axis values See also charts XLS emitter 133 xls format value 57 XML files 94 Y y-axis values See also charts

160 Installing Visualization Platform