Building Web Applications Using BIRT APIs 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 - 2015 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.opentext.com 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 Bitmap Library. d3-cloud. Day Management AG: Content Repository for Java. Dygraphs Gallery. 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). Bits Per Second, Ltd. and Graphics Server Technologies, L.P.: Graphics Server. Dave Gandy: Font Awesome. Gargoyle Software Inc.: HtmlUnit. GNU Project: GNU Regular Expression. Google Charts. 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. IDAutomation.com, Inc.: IDAutomation. IDRsolutions Ltd.: JPedal JBIG2. InfoSoft Global (P) Ltd.: FusionCharts, FusionMaps, FusionWidgets, PowerCharts. InfoVis Toolkit. 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, JQuery Sparklines. 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. Membrane SOA Model. MetaStuff: dom4j. Microsoft Corporation (Microsoft Developer Network): CompoundDocument Library. Mozilla: Mozilla XML Parser. MySQL Americas, Inc.: MySQL Connector/J. Netscape Communications Corporation, Inc.: Rhino. NodeJS. nullsoft project: Nullsoft Scriptable Install System. OOPS Consultancy: XMLTask. OpenSSL Project: OpenSSL. Oracle Corporation: Berkeley DB, Java Advanced Imaging, JAXB, Java SE Development Kit (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. Raphael. RequireJS. Rogue Wave Software, Inc.: Rogue Wave Library SourcePro Core, tools.h++. Sencha Inc.: Extjs, Sencha Touch. Shibboleth Consortium: OpenSAML, Shibboleth Identity Provider. Matteo Spinelli: iscroll. StAX Project (stax.codehaus.org): Streaming API for XML (StAX). Sam Stephenson (prototype.conio.net): prototype.js. 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. 141215-2-431302 June 23, 2015 Contents
About Building Web Applications Using BIRT APIs ...... iii Chapter 1 Introducing BIRT APIs for applications ...... 1 Using BIRT APIs in applications ...... 2 Introducing the BIRT Aviatio example application ...... 2 Accessing source code and resources ...... 5 About application project files ...... 5 About resources used by the example application ...... 6 About AngularJS frameworks ...... 6 Chapter 2 Building web content with BIRT ...... 9 Overview of BIRT iHub Information Console ...... 10 Considering which Actuate API to use ...... 10 About the representational state transfer API ...... 11 About the JavaScript API ...... 11 Using BIRT Designer Professional for web content ...... 12 Introducing GitHub ...... 13 Chapter 3 Integrating REST API ...... 15 Reviewing REST API integration ...... 16 Building URIs to access REST API ...... 16 Authenticating with REST API ...... 17 Displaying a list with REST API ...... 20 Searching for files with REST API ...... 22 Running reports with REST API ...... 23 Chapter 4 Integrating JavaScript API ...... 27 Reviewing JSAPI integration ...... 28 Displaying BIRT content in a web page ...... 28 Loading visualizations by bookmark name ...... 29 Chapter 5 Extending web functionality ...... 31 Optimizing BIRT content for web viewing ...... 32 Using external authentication ...... 32 Changing application default values ...... 32
i Additional optimizations ...... 33 Chapter 6 Using developer resources ...... 35 Using Actuate documentation ...... 36 Visiting the Actuate developer site ...... 38 About additional REST API resources ...... 39 Index ...... 41
ii About Building Web Applications Using BIRT APIs
Building Web Applications Using BIRT APIs provides information about using the Actuate REST API in web browser-based applications. ■ About Building Web Applications Using BIRT APIs. This chapter provides an overview of this guide. ■ Chapter 1. Introducing BIRT APIs for applications. This chapter introduces web applications and introduces the BIRT Aviatio web application. ■ Chapter 2. Building web content with BIRT. This chapter introduces the tools used to build the BIRT Aviatio sample application. ■ Chapter 3. Integrating REST API. This chapter discusses methods to integrate the REST API in a web application. ■ Chapter 4. Integrating JavaScript API. This chapter discusses methods to integrate the JavaScript API in a web application. ■ Chapter 5. Extending web functionality. This chapter discusses possible customization of the BIRT Aviatio application. ■ Chapter 6. Using developer resources. This chapter lists resources to learn more about REST API.
About Building Web Applications Using BIRT APIs iii iv Building Web Applications Using BIRT APIs Chapter1
Chapter 1Introducing BIRT APIs for applications
This chapter contains the following topics: ■ Using BIRT APIs in applications ■ Introducing the BIRT Aviatio example application ■ Accessing source code and resources ■ About application project files ■ About resources used by the example application ■ About AngularJS frameworks
Chapter 1, Introducing BIRT APIs for applications 1 Using BIRT APIs in applications This chapter discusses how to incorporate BIRT data objects and reports into your web application. The BIRT files contain your data, report templates, and visualizations. The BIRT iHub server supports application development using the REST API and JavaScript API (JSAPI). You can use one or both of these APIs to integrate BIRT visualizations and access data files stored in BIRT iHub servers. The REST API supports: ■ Authenticating users ■ Searching for BIRT files ■ Running jobs from BIRT designs with selected parameters and locales ■ Downloading reports in PDF and Excel formats ■ Downloading and filtering data in JSON or CSV format An application can extract data from iHub using the REST API and use the values to navigate content or send the values to a third-party data visualization, such as a chart or map. The JSAPI supports: ■ Embedding interactive BIRT visualizations in web pages ■ Handling scripted events within BIRT reports or BIRT report elements ■ Accessing table of contents and parameters in BIRT reports ■ Operating the BIRT Interactive Viewer and Crosstabs BIRT visualizations, such as a chart, table or a multi- page BIRT report display in interactive web pages using JSAPI. Use these APIs to access and generate BIRT content, enabling your application to display secure, interactive data visualizations in any programming language that supports REST and JavaScript.
Introducing the BIRT Aviatio example application This example illustrates how to integrate BIRT iHub resources into a web application using HTML and JavaScript. This application is designed for a minimum screen size of 1024 x 768px.
2 Building Web Applications Using BIRT APIs The Actuate REST API authenticates the application and retrieves data used to build navigation links and information about files on the demonstration BIRT iHub 3.1 server. The Actuate JavaScript API (JSAPI) retrieves data and visualizations from a server. The iHub server resources used by this example are included with the source code. This example application demonstrates the following functionality: ■ User authentication to a user account residing on a BIRT iHub server ■ Searching for the file ID of a BIRT data object ■ Downloading a list of location names from the BIRT data object ■ Building an interactive list of location names ■ Executing a BIRT design to update data and create a BIRT document using the selected state as a parameter value ■ Searching for the file ID of the generated BIRT report document ■ Retrieving meta-data about the BIRT document ■ Loading BIRT visualizations into different DIV elements of the web page When the web application first loads, it authenticates with the iHub server and retrieves a JSON formatted list of region and state names. After using REST API to extract location names from a BIRT data object, this application builds navigation links. When a user selects a link, the REST API generates a report for the selected location if a valid one does not already exist. The Actuate JSAPI then displays items from the report in the DIV elements of the HTML page. The index.html file contains the following HTML DIV elements: ■ startPage, containing the landing page for the application ■ content, containing a menu and report content ■ leftSidebarDiv, containing the menu of location names ■ mainDiv, containing the loading animation and user selected visualizations ❏ overlay, containing loading message while data is downloads ❏ container, containing navigation buttons and report visualizations The container DIV contains the following DIV elements: ■ appTitle, containing the name of the location ■ nextButton and backButton to navigate the list of locations ■ busiest_worst, containing the bookmarked grid named busiest_worst
Chapter 1, Introducing BIRT APIs for applications 3 ■ percentage, containing the bookmarked chart named percentage ■ average, containing the bookmarked chart named average ■ causes, containing the bookmarked grid named causes, displaying pie charts ■ timestamp, containing the time and date the report was generated Figure 1-1 shows the application’s interface.
appTitle DIV
busiest_worst DIV
causes DIV
percentage DIV
average DIV
timestamp DIV
leftSidebar Div
Figure 1-1 User interface displaying a list, charts, and navigation buttons This example writes data to the JavaScript console of the web browser for debugging purposes. When the application authenticates with an iHub server the word success appears in the JavaScript console.
4 Building Web Applications Using BIRT APIs When the user selects a location, the region name, state abbreviation, and generated report are displayed in the JavaScript console. The following console output shows the result of a user selecting the state of Washington: region = West state = WA filename = /Home/West/WA.rptdocument Cleared div mask While a new report is generated, a temporary DIV appears in the application notifying the user that data is loading. After the report generation finishes, the report items download to the web application and the loading DIV is cleared.
Accessing source code and resources The source code and BIRT resources to build the example web application are available from the Actuate GitHub web site at the following URL: https://github.com/ActuateBIRT/AviatioExample BIRT Aviatio uses the following third-party chart libraries: ■ HTTPS://angularjs.org/ ■ HTTP://fonts.googleapis.com ■ HTTP://jquery.com If you want to distribute or use any of these libraries, check the library’s web site for licensing information.
About application project files The following is a general overview of the BIRT Aviatio source code: ■ index.html, containing the HTML to render the application in a web browser ■ /css folder containing the style.css file for the web application ■ /images folder containing the application image files and icons ■ /js folder containing the JavaScript files used in the web application ■ angular-loader.min.js, AngularJS loader for Angular modules ■ angular-resource.min.js, AngularJS interaction support with RESTful services via the $resource service ■ angular.min.js, minimized version of AngularJS frameworks
Chapter 1, Introducing BIRT APIs for applications 5 ■ controller.js, contains JavaScript functions such as login, initViewer, loadBookmark, executeReport, nextState, previousState, selectState ■ factory.js, generates requests to each RESTful service the application uses ■ main.js, generates REST URIs and sets default values for the application ■ services.js, template for RESTful HTTP requests
About resources used by the example application The example, BIRT Aviatio, retrieves data from a BIRT data store an visualizations from BIRT report document files installed at the iHub server. This application uses the following server-side files to generate all BIRT content displayed in the web page: ■ flight delay.data ■ Flight Performance.RPTDESIGN These resource files are included with the BIRT Aviatio Reports folder in the source code, stored on GitHub. Choose Download ZIP on the GitHub web page to download these resources to your computer. If you are using your own iHub server, install the flight delay.data file in the \Resources\Data Objects folder of the iHub volume. The report design is stored in the home folder of the user account that the application uses to log in. The user name is set in the main.js JavaScript file, and uses a default value of flightdemo. Install the Flight Performance.rptdesign file into the \Home\
About AngularJS frameworks This web application uses the AngularJS JavaScript framework to build navigation links in the web page, organize JavaScript functions and maintain a
6 Building Web Applications Using BIRT APIs responsive web application. AngularJS is a client-side JavaScript framework for building interactive web applications.
Chapter 1, Introducing BIRT APIs for applications 7 8 Building Web Applications Using BIRT APIs Chapter2
Chapter 2Building web content with BIRT
This chapter contains the following topics: ■ Overview of BIRT iHub Information Console ■ Considering which Actuate API to use ■ Using BIRT Designer Professional for web content ■ Introducing GitHub
Chapter 2, Building web content with BIRT 9 Overview of BIRT iHub Information Console BIRT iHub Information Console is a browser-based solution for document delivery, data analysis and building reports. Information Console enables users to securely access data in the following ways: ■ View and share interactive reports and dashboards. ■ Analyze data in cross tabs and tables. ■ Extract data from caches and stores of data. Information Console includes a user administration console that enables administrators to manage user profiles, user groups, as well as authorizing user and group access to published files. A volume administration console enables administrators to manage volume level operations such as assigning volume license options, managing files, scheduling file creation jobs, and archiving files. This product is a set of dynamic web pages that installs automatically when you install BIRT iHub. Alternatively, you can install BIRT iHub Information Console as a stand-alone product.
Considering which Actuate API to use Actuate provides software development tools as a collection of APIs that support designing new applications or extending or customizing existing applications. Each API offers the developer different methods to access and control data, visualizations and iHub server functionality. The API that you use depends on what you need to do. Actuate API libraries extend functionality in applications that provide API integration points. The APIs used for client-side application development include: ■ Representational state transfer API (REST API). The REST API accesses and manages data and files built with Actuate BIRT technology. Use this API to manage and generate new documents, and to request data in the JSON format. ■ JavaScript API (JSAPI). The JSAPI provides libraries for web and client-side visualizations using the JavaScript programming language. Use this API to render BIRT visualizations and reports in a web page.
10 Building Web Applications Using BIRT APIs About the representational state transfer API The Actuate REST API is an HTTP service that runs on a Node.js platform. This service interacts with BIRT content and files on an iHub server using URI requests such as: http://
Chapter 2, Building web content with BIRT 11 determines the usage of the reports and report data. The iHub server receives the JSAPI requests and sends HTML content for display in a selected HTML DIV element. Many functions in the Actuate JavaScript API use a callback function. A callback function is a custom function written into the web page that is called immediately after the function that calls it is finished. A callback function does not execute before the required data or connection has been retrieved from the server. For more information about using the JSAPI, see Integrating Applications into BIRT iHub.
Using BIRT Designer Professional for web content Actuate BIRT Designer Professional is a report designer for report developers who want to use the functionality provided by Actuate Corporation that enhances the Eclipse BIRT Report Designer. You can use BIRT Designer Professional to build the following content: ■ BIRT visualizations that securely display data charts, cross tabs, maps, and tables ■ Templates to export HTML, PDF, and Microsoft Excel file formats ■ Structured data from databases, web services, XML files, and other data sources ■ Custom data and visualization solutions using expressions and scripting BIRT design files query data sources and display charts, tables, cross tabs and maps interactively on web pages using the Actuate JSAPI. These designs can also be run and downloaded in formats such as Adobe PDF and Microsoft Excel using the Actuate REST API. BIRT data object files can query multiple data sources and cache the data in data sets, data models, and data cubes for analysis and visual display in charts and maps. You can filter and retrieve data sets from a data object in the JSON format using REST API. You can also use data objects to provide data to BIRT designs and dashboards. You can use the REST API to extract aggregated data when that data is grouped in BIRT report items. Each item in a BIRT report such as a chart, cross tab, and table can group data and can include a bookmark name to identify the item. The REST API uses the bookmark value to find the report item and then to extract the data displayed in the report item. For example, a bookmark named MapState can identify a cross tab that summarizes population statistics about each state in a BIRT design file. You can use the REST API to find the bookmark name and extract the data summary in the JSON format for use in your application.
12 Building Web Applications Using BIRT APIs BIRT data objects also offer the following features: ■ Securing data using Actuate Page and Row Level Security, and Java code execution security ■ Supporting data sources such as Amazon, Cassandra, Cloudera, Hbase, Hive, JDBC, MongoDB, POJO, and web services ■ Easy scripting of data queries ■ Fast analytic queries using columnar data stores ■ Improving data retrieval performance using caching and in-memory data models ■ Optimizing direct data access using data trimming and push down For more information about using BIRT Designer Professional, see Actuate BIRT Application Developer Guide.
Introducing GitHub GitHub is a web site that stores source code repositories for many public and private projects. The source code for BIRT Aviatio is available at GitHub. You do not need an account with GitHub to download the source code for BIRT Aviatio, but you must have a user account to use the GitHub issue tracker or to submit comments or changes about the source code. For more information about GitHub, visit the following URL: https://github.com/
Chapter 2, Building web content with BIRT 13 14 Building Web Applications Using BIRT APIs Chapter3
Chapter 3Integrating REST API
This chapter contains the following topics: ■ Reviewing REST API integration ■ Building URIs to access REST API ■ Authenticating with REST API ■ Displaying a list with REST API ■ Searching for files with REST API ■ Running reports with REST API
Chapter 3, Integrating REST API 15 Reviewing REST API integration The BIRT iHub server offers many RESTful URI endpoints to access stored resources on the server. This example uses JavaScript to make the following REST API requests: ■ Authenticate the user to receive an authentication ID to attach to other REST API requests. ■ Download a list of locations that are used to build BIRT reports. ■ Download visualizations for display in HTML DIV tags. The application sends the RESTful URI request to the iHub server using services.js. The metadata collected using the REST API includes the timestamp when the BIRT document was created. JavaScript uses this value to check if the data is older than the report_refresh_Time value, located in main.js. If the data is older the report is executed to refresh the data. The following REST API operations are used in BIRT Aviatio: ■ /Login to return an authId for an authenticated user. ■ /Files to retrieve a file id by searching for the file name. ■ /Visuals to execute a BIRT design file. ■ /Dataobject to extract values from a data set in a selected data store file. The main JavaScript functions used in the application are organized into the following files: ■ controller.js contains JavaScript functions to log in, load visualizations, and run reports. ■ factory.js generates requests to each RESTful service the application uses. ■ main.js library builds RESTful URIs to access resources on the iHub server. ■ services.js is a template for RESTful HTTP requests.
Building URIs to access REST API The BIRT Aviatio application builds the URIs to access the iHub server’s REST API in the main.js file. The following code show the different URI’s used by the application: /* Controllers */
16 Building Web Applications Using BIRT APIs var mainCtrl = angular.module('mainApp', []); var restHost = "aviatioexample.actuate.com"; var restPort = "\\:5000"; var visuals = "visuals"; var ihubHost = "aviatioexample.actuate.com"; var ihubPort = ":8700"; mainCtrl.constant('mainAppCtrl', { login: 'http://' + restHost + restPort + '/ihub/v1/login', folders: 'http://' + restHost + restPort + '/ihub/v1/folders', files: 'http://' + restHost + restPort + '/ihub/v1/files/ :fileId', downloadReport: 'http://' + restHost + restPort + '/ihub/v1/' + 'files', reports: 'http://' + restHost + restPort + '/ihub/v1/' + visuals + '/:reportsId/:outputFormat', reportData: 'http://' + restHost + restPort + '/ihub/v1/' + visuals + '/:reportsId/data/:datasetname/?format=:format', reportBookmarks: 'http://' + restHost +restPort + '/ihub/v1/' + visuals + '/:reportsId/bookmarks', reportMetadata: 'http://' + restHost + restPort + '/ihub/v1/' + visuals + '/:reportsId/datasets', reportBookmarksData: 'http://' + restHost + restPort + '/ihub/ v1/' + visuals + '/:reportsId/bookmarks/:bookmarkName', reportMetadataData: 'http://' + restHost + restPort + '/ihub/v1/ ' + visuals + '/:reportsId/datasets/:datasetname', downloadFile: 'http://' + restHost + restPort + '/ihub/v1/' + visuals + '/:reportsId/download', dataObject: 'http://' + restHost + restPort + '/ihub/v1/ dataobject/:dataObjectId', dataObjectElement: 'http://' + restHost + restPort + '/ihub/v1/ dataobject/:dataObjectId/:dataobjectElement', executeReport : 'http://' + restHost + restPort + '/ihub/v1/' + visuals + '/:reportsId/execute', jsapiUrl: 'http://' + ihubHost + ihubPort + '/iportal/jsapi', iportalUrl : 'http://' + ihubHost + ihubPort + '/iportal', report_refresh_Time : '15', idle_time : '20', username : "flightdemo", password: "Demo1234" });
Authenticating with REST API An authId is an authentication identifier passed back from iHub after successful authentication and is required for all subsequent REST API requests.
Chapter 3, Integrating REST API 17 To generate the authId token, use a POST request for the /login resource with a username as a query parameter. Other parameters for /login are optional. An HTTP request does not encrypt the password field, so always use an HTTPS request for /login. For instructions to enable HTTPS support for REST API see Integrating Applications into BIRT iHub. When successful, the REST API request returns an authentication identifier, authId with information about the user account. A REST API authentication identifier remains valid for 24 hours by default. The URI used to login is created in the /js/main.js file. The index.html file starts the login function when the page loads using the following code in index.html: This starts the login function in /js/controller.js that uses a URI to the Actuate REST /login resource. The login function runs the following code: $scope.login = function() { var params= { 'username': mainAppCtrl.username, 'password': mainAppCtrl.password }; API.Login.post(params, function(dataResponse) { $scope.response = dataResponse; A successful authentication returns a response body similar to the following: { "AuthId": "jIWy49iySIytHlaDNHSyStu6/ KSKB2NJeGNo2RKryzupeK23GPyF9wBqBRH2+JDaKtThHpworWqsuMQTPZXR5Zam 27DckdXTLxdDKfdJxxh6cYr75qMKUmyNJ+FKP4j3iEI2Zn04f61r0luc7tKFnZH oPPa9nTXxhrQ+lRiNs8t3NOcglCbGWHc+g64RaLQ0rflDawq/ 6FBfsh87w0D3Qs+raaJrTrbdiuJkrDXYq/ GZthzB8lmRlhhlRi0MhTfSSDj2kwXqQpX5hepvtWVBDv24a+nhPjRYOQZOlRdSS vvhOLPgoNpZM0WmzdRj2+eqFTdDvj+lIcZtkO4Fh7KWaXOVRErKapokfIb/ 77X9h6de0YY63tm0OMzMkq/o5c6+", "User": { "Id": "200100000100", "Name": "flightdemo", "EmailAddress": "[email protected]", "HomeFolder": "/Home/flightdemo" } }
18 Building Web Applications Using BIRT APIs Next, the login function sends a request to the /files resource to search for the file id of flight delay.data using the following code: if (dataResponse.AuthId) { $rootScope.userData = dataResponse; $rootScope.AuthId = dataResponse.AuthId; params = { search :"/Resources/Data Objects/flight delay.DATA", authId: $rootScope.AuthId }; API.DownloadReport.query(params, function (dataResponse) { A successful file search returns a response body similar to the following: { "ItemList": { "File": [ { "Id": "410300000100", "Name": "flight delay.data", "FileType": "DATA", "PageCount": "0", "Size": "10647543", "Version": "1" } ] }, "TotalCount": "1" } Then the login function sends a request to the /dataobject resource with the file id of flight delay.data. This request searches for the geographic data set in the flight delay.data file using the following code: if (dataResponse.TotalCount > 0) { params = { dataObjectId : dataResponse.ItemList.File[0].Id, dataobjectElement : "geographic", authId: $rootScope.AuthId }; API.DownloadDataObjectElement.query(params, function (dataResponse) {
Chapter 3, Integrating REST API 19 A successful data set search returns a response body similar to the following: { "data": [ { "state": "AL", "full_state": "Alabama", "region": "South", "scale": "5" }, { "state": "TN", "full_state": "Tennessee", "region": "South", "scale": "5" }, { "state": "AR", "full_state": "Arkansas", "region": "South", "scale": "4" }, The login function finishes the login process by storing the state names in an array for the region associated with each state. See the source code for the complete example.
Displaying a list with REST API This example builds a navigation list of locations, BIRT Aviatio requests values from a data set in the flight delay.data file. The following is a general overview of that process: ■ Search for the flight delay.data file by building a URI using the REST API. ■ Append the authentication identifier to the end of the URI and send it to an iHub server. ■ Extract the file id from the file search request. ■ Use the file id to make a second REST API request that retrieves a data set of locations from the flight delay.data file. ■ Parse the JSON response from the iHub server into an array for each region. ■ Build the state name navigation of the application using these names.
20 Building Web Applications Using BIRT APIs The index.html file displays region names for a user to select using the following HTML:
When the user selects a region, the showState function displays the states in the selected region using the following JavaScript code from controller.js: $scope.showState = function(region, page) { $scope.statePopOverClass = "hide"; if ($scope.selectedRegion != region) { $scope.highlightRegion(region, page); $scope.selectedRegion = region; $scope.statePopOverClass = region + "Class"; } else { $scope.highlightRegion($scope.currentRegion, page); $scope.selectedRegion = ""; } } When the user selects a state, the selectState function runs. This function populates the previous and next navigation buttons with the correct state to load, initializes the JSAPI BIRT viewer if it is not already initialized, runs the reportNeedsReRun function to prepare for loading report visualizations. See the source code for the complete example.Chapter 3, Integrating REST API 21 Searching for files with REST API The reportNeedsReRun function searches to see if the report for the selected state already exists using the following code: var fileName = "/Home/" + region + "/" + state + ".rptdocument"; console.log("region " + "= " + region); console.log("state " + "= " + state); params = { search : fileName, authId: $rootScope.AuthId }; API.DownloadReport.query(params, function (dataResponse) { if (dataResponse.TotalCount > 0) { A successful data set search returns a response body similar to the following: { "ItemList": { "File": [ { "Id": "320610000100", "Name": "WA.rptdocument", "FileType": "RPTDOCUMENT", "PageCount": "1", "Size": "2369202", "Version": "1" } ] }, "TotalCount": "1" } If the file exists, it is queried for meta-data about the file with the following code: if (dataResponse.TotalCount > 0) { params = { fileId : dataResponse.ItemList.File[dataResponse.ItemList.File.length - 1].Id, authId: $rootScope.AuthId }; API.Files.query(params, function (dataResponse) { var ts = dataResponse.File.TimeStamp; $scope.timestamp = "Generated " + $filter('date')(new Date(ts), "MM/dd/yyyy 'at' h:mma");
22 Building Web Applications Using BIRT APIs A successful data set request returns a response body similar to the following: { "File": { "Id": "320610000100", "Name": "/Home/West/WA.rptdocument", "FileType": "RPTDOCUMENT", "PageCount": "1", "Size": "2369202", "TimeStamp": "2014-11-11T15:55:24.000Z", "Version": "1", "Owner": "flightdemo" }, "ACL": {}, "ArchiveRules": {} } If the report time stamp validates within the report refresh time, then the visualizations of the report load into the application. If the report is older than the report refresh time, it is run again. The following code shows this validation check: if((new Date().getTime() - new Date(ts).getTime()) > mainAppCtrl.report_refresh_Time * 60 * 1000 ) { $scope.executeReport(fileName,region, state); } else { $scope.loadBookmarks(fileName); } }, See the source code for the complete example.
Running reports with REST API When a user makes a selection from a list of locations, the application verifies if the selected report already exists and if it is recent. If the report is older than the report refresh time or if the report does not exist, the report is generated with the executeReport function. The following overview describes this functionality in the example application: ■ Check if the report design file id exists. ■ If the file id is not known, a search is made for the file id of Flight Performance.rptdesign; the design file that generates the BIRT report visualizations. ■ Define parameters to run the report design and generate the report for the selected state.
Chapter 3, Integrating REST API 23 ■ Run the loadBookmarks function to display the report visualizations on the web page. The executeReport function searches for the BIRT report design file id if the id does not already exist with the following code: $scope.executeReport = function(fileName, region, state) { console.log("fileName = " + fileName); var params = { search : '/Home/Flight Delay App/Flight Performance.rptdesign', authId: $rootScope.AuthId }; if (!$rootScope.reportId ) { API.DownloadReport.query(params, function (dataResponse) { $rootScope.reportId = dataResponse.ItemList.File[0].Id; A successful file search returns a response body similar to the following: { "ItemList": { "File": [ { "Id": "882200000100", "Name": "Flight Performance.rptdesign", "FileType": "RPTDESIGN", "PageCount": "0", "Size": "400400", "Version": "1" } ] }, "TotalCount": "1" }
24 Building Web Applications Using BIRT APIs Once the file id is known, the id is used to generate a report from the report design file using the following code: var paramValues = {"ParameterValue" : [ {"Name" : "Region","Value": region}, {"Name" : "State", "Value": state} ] }; params = { reportsId : dataResponse.ItemList.File[0].Id, paramValues : angular.toJson(paramValues, false), saveOutputFile : true, replaceExisting : true, requestedOutputFile : fileName, authId: $rootScope.AuthId }; $scope.timestamp = "Generated " + $filter('date')(new Date(), "MM/ dd/yyyy 'at' h:mm a"); API.ExecuteReports.post(params, function (dataResponse) { $scope.loadBookmarks(fileName); }, A successful job execution returns a response body similar to the following: { "Status": "FirstPage", "ObjectId": "220710000100", "OutputFileType": "RPTDOCUMENT", "ConnectionHandle": "bAq+y9HJrv5y7XC/gX7MO721WvOI/ w6jmbZwg7PYF19Cq3057d+JTeUKSSPpu8CJEdtWledo6r5Fb4yX4Ucvyt84/ 3qNdvlyqKFp41x9MxeCmRgzAYm90ztm3Lyfjqx82DvON58eYK8rSKFmLiwjk8G3 yjwNvQ0UG0eLmAm6yieKHTpWon9M95UJcKNnCtdE6HFYH+iv3kbbC1t2L7opIIn DUZnxKjZ6YZgrmUYKgYPKVi0rSGjMWS1obFISqHPASoQcmOHMSkyry94aXKCn+e LVBZJu9VSY" } The executeReport function then extracts the bookmarked visualizations from the generated file. See the source code for the complete example.
Chapter 3, Integrating REST API 25 26 Building Web Applications Using BIRT APIs Chapter4
Chapter 4Integrating JavaScript API
This chapter contains the following topics: ■ Reviewing JSAPI integration ■ Displaying BIRT content in a web page ■ Loading visualizations by bookmark name
Chapter 4, Integrating JavaScript API 27 Reviewing JSAPI integration This application uses JSAPI to display BIRT visualizations in DIV tags of a web page. The application loads JSAPI using the jQuery method getScript, located in controller.js. JSAPI communicates with the iHub server using the authentication values used in the REST API login request. The JSAPI then extracts content from the report generated by the REST API and displays each item in the report in a different DIV tag. Bookmarks are a method to identify content in a BIRT report, such as charts, tables, or a grid including both charts and tables. This application uses JSAPI to complete the following tasks: ■ Create a BIRT viewer in different DIV elements on the web page ■ Load report items for the selected state into each instance of BIRT viewer For more information about embedding BIRT visualizations in HTML see Integrating Applications into BIRT iHub. More information about using JSAPI can also be found at the following URL: http://developer.actuate.com/resources/documentation/ihubftype/ integration/
Displaying BIRT content in a web page Displaying the visualizations and layout of a BIRT design in HTML requires JavaScript and the Actuate JSAPI. Using JSAPI enables you to embed a BIRT document or part of a BIRT document into an HTML web page. BIRT Aviatio loads the Actuate JSAPI library from the iHub server as part of the login function. The following script is used to load the Actuate JSAPI: $.getScript( mainAppCtrl.jsapiUrl ) .done(function( script, textStatus ) { console.log( textStatus ); }) .fail(function( jqxhr, settings, exception ) { console.log( textStatus ); }); When a user selects a state name, the selectState function checks to see if a JSAPI BIRT viewer is already loaded. If there is no viewer available, the initViewer
28 Building Web Applications Using BIRT APIs function is called. This function uses the following Actuate JSAPI code to initialize the viewer: $scope.initViewer = function (region, state) { if ($scope.viewerInitialized) { return; } var reqOps = new actuate.RequestOptions( ); reqOps.setVolumeProfile( "default volume" ); reqOps.setVolume( "default volume" ); actuate.load("viewer"); $rootScope.idleTime = new Date(); actuate.initialize( mainAppCtrl.iportalUrl, reqOps, mainAppCtrl.username, mainAppCtrl.password, function () { $scope.viewerInitialized = true; $scope.reportNeedsReRun(region, state); } ); } See the source code for the complete example.
Loading visualizations by bookmark name BIRT report visualizations are loaded using their bookmark names. After locating or generating a valid report, BIRT Aviatio loads the visualizations from the report into the web page. The following loadBookmarks function is used to load the visualizations into the DIV tags of the application: $scope.loadBookmarks = function (fileName) { $scope.loadBookmark(fileName, "percentage", "percentage", 575, 245); $scope.loadBookmark(fileName, "average", "average", 575, 250); $scope.loadBookmark(fileName, "causes", "causes", 130, 515); $scope.loadBookmark(fileName, "busiest_worst", "busiest_worst", 732, 70);
Chapter 4, Integrating JavaScript API 29 The loadBookmark function uses Actuate JSAPI to load each visualization into the correct DIV tag of the HTML page. The following code loads each bookmark from the selected state report: $scope.loadBookmark = function (fileName, bookmark, divId, width, height) { var viewer = new actuate.Viewer( divId); viewer.setReportName( fileName ); viewer.setSize(width, height); var options = new actuate.viewer.UIOptions( ); options.enableToolBar(false); options.enableToolbarContextMenu(false); viewer.setUIOptions( options ); viewer.setReportletBookmark(bookmark);
viewer.registerEventHandler(actuate.viewer.impl.EventConstants. ON_EXCEPTION, function() { console.log(divId + " render error"); $scope.done.push(divId); } ); See the source code for the complete example.
30 Building Web Applications Using BIRT APIs Chapter5
Chapter 5Extending web functionality
This chapter contains the following topics: ■ Optimizing BIRT content for web viewing ■ Using external authentication ■ Changing application default values ■ Additional optimizations
Chapter 5, Extending web functionality 31 Optimizing BIRT content for web viewing The report documents displayed in BIRT Aviatio use a single report design template. The page layout of the report is not used. Instead, each report item is loaded into a different HTML DIV in the report output. The JavaScript framework Angular JS rearranges these DIV elements to best fit the current orientation of the application. You can limit the quantity of data transferred using the REST API by adding data groups in the SQL statements or using REST API to filter the data. Data sets downloaded using the REST API are not aggregated.
Using external authentication The BIRT Aviatio application uses the iHub server to authenticate users. The iHub server can use its own authentication database, connect to your LDAP or Active Directory user data, or use a single sign-on (SSO) service. See Using BIRT iHub System Console for more information about supported authentication services.
Changing application default values Default URLs and authentication to an iHub server are set in the main.js file of the project. You can build the application for use with your own iHub server by changing the values in this file. You can also change the file path location of BIRT resources used in the application in this file. The following values are contained in this file: ■ ihubHost , you can change this value using the following URL format: aviatioexample.actuate.com
■ ihubPort, you can change the port to access the actuate JSAPI library: :8700
■ restPort, you can change the port to access the REST API endpoints: \\:5000
■ username, the user name to log in to the iHub server: flightdemo
■ password, the password to log in to the iHub server: Demo1234
32 Building Web Applications Using BIRT APIs ■ report_refresh_Time, number of minutes before requesting new data: 15 ■ idle_time, number of minutes to maintain a connection to the iHub server: 20
Additional optimizations This example application demonstrates common integration techniques. Optimize your own code to make use of your software platform features and your enterprise requirements. For example, depending on the devices you expect to use and your application specifications, you might: ■ Use SSL connections to secure user authentications and data. ■ Aggregate data in SQL queries. ■ Aggregate data in BIRT report items and identify the data with bookmarks. ■ Use an alternative JavaScript frameworks such as: ■ Backbone ■ Ember ■ Sencha Ext JS ■ Store data requests in the web browser’s local storage to speed up user selection.
Chapter 5, Extending web functionality 33 34 Building Web Applications Using BIRT APIs Chapter6
Chapter 6Using developer resources
This chapter contains the following topics: ■ Using Actuate documentation ■ Visiting the Actuate developer site ■ About additional REST API resources
Chapter 6, Using developer resources 35 Using Actuate documentation Interactive documentation for Actuate REST API operations is also installed with an iHub server. This documentation is accessible using a web browser at the following URL: http://
Figure 6-1 Reviewing the Actuate REST API documentation
36 Building Web Applications Using BIRT APIs This documentation enables you to test the different URIs available in the Actuate REST API. To test a REST API operation, select one of the available operations, type parameter values, and then choose Try it out. Figure 6-2 shows the options to test the /login URI.
Figure 6-2 Testing the login operation After sending your test values to the selected operation, the documentation displays the response from iHub. Figure 6-3 shows the results when the username Administrator was sent to the /login URI.
Chapter 6, Using developer resources 37 Figure 6-3 Reviewing results from the REST API
Visiting the Actuate developer site Additional information about integrating BIRT technology into applications is available at the following URL: http://developer.actuate.com/deployment-center /integrating-birt-into-applications/ Forums for discussing BIRT technologies are available at the following URL: http://developer.actuate.com/community/forum/
38 Building Web Applications Using BIRT APIs For more information about using the REST API and other Actuate APIs, see Integrating Applications into BIRT iHub, and the Actuate developer web site at the following URL: http://developer.actuate.com/
About additional REST API resources There are many resources available on the internet discussing the use of RESTful web services. The following URLs are samples of some of those web sites: http://docs.oracle.com/javaee/6/tutorial/doc/gijqy.html https://www.ibm.com/developerworks/webservices/library/ws-restful/
Chapter 6, Using developer resources 39 40 Building Web Applications Using BIRT APIs Index
A BIRT design files See also design files access rights BIRT iHub. See iHub System See also privileges BIRT Interactive Crosstabs. See Interactive accessing Crosstabs Information Console functionality 11 BIRT report files ACL files See also report files See also access control lists BIRT reports ACLs. See access control lists See also reports ACS. See Caching service BIRT Viewer adding See also report viewer display names. See display names browsers. See web browsers Administrate operations Business Intelligence and Reporting Tools. See also administration operations See BIRT administrators See also administration operations C aggregate data. See aggregation aggregate functions. See aggregation cache database. See Caching service database functions calculated columns aging rules. See archiving rules See also computed columns AIS. See Integration service character data. See strings application programming interfaces (APIs) character encoding. See encoding See also Information Delivery API character encryption. See encryption applications character strings. See strings building user interfaces for. See user chart objects interfaces See also charts developing IDAPI. See IDAPI applications chart wizard launcher developing RSSE. See RSSE applications See also chart builder developing web. See web applications charts archive files See also Flash charts; HTML5 charts See also jar files; war files developing. See charting APIs archive rules. See archiving rules client applications. See applications ArchiveRule objects column headers See also archiving rules See also column names arguments. See command line arguments; column headings parameters See also column names attributes comma-separated values files. See CSV files See also properties completion notices autoarchiving. See archiving operations See also notifications Axis servers. See Apache Axis environments computed columns See also calculated columns B conditions. See filter conditions; search conditions beans. See JavaBeans
Index 41 connection definition files. See database charts. See charting APIs connection definition files IDAPI applications. See IDAPI applications connection handles. See ConnectionHandle RSSE applications. See RSSE applications element diagnostic information connections See also Ping operations setting properties for. See connection directory paths. See paths properties display formats. See formats consolidator application. See log consolidator distributed iHub System. See clusters application documentation creating See also help collections display names. See display names documents IDAPI applications. See applications See also reports CSS files .dov files. See data object values files See also cascading style sheets download operations See also downloading D downloading data See also download operations aggregating. See aggregation duplicating. See copying extracting. See data extraction operations localizing. See locales E data analyzer component elements. See report elements; XML elements See also Interactive Crosstabs e-mail data charts viewer sending attachments with. See attachments See also charts setting notification options for. See data cubes. See cubes notifications data elements events See also data items handling. See event handlers data fields execution requests. See ExecuteReport See also columns operations data filters. See filters Extensible Markup Language. See XML data items See also data F data repositories fields See also Encyclopedia volumes See also columns data rows. See rows file attributes data set fields. See fields See also file properties data sorters. See sorters file IDs database connection properties. See See also FileId element connection properties file paths. See paths database drivers. See drivers files database schemas. See schemas See also report files databases naming. See file names See also data sources setting properties for. See file properties DCD. See database connection definitions finding data. See search operations dependent files. See file dependencies folder paths. See paths developing formats
42 Building Web Applications Using BIRT APIs See also output formats adding toolbars. See Interactive Crosstabs functions toolbars See also callback functions; methods interfaces See also user interfaces G iPortalSecurityAdapter class graphical user interfaces. See user interfaces See also IPSE applications graphics elements iServer System. See iHub System See also images graphs. See charts J groups Java RSSE framework See also notification groups; resource See also RSSE applications groups jobs GUI components failing. See failed jobs See also user interfaces pending. See pending jobs print operations and. See print jobs H sending notifications for. See notifications header elements (SOAP messages) See also SOAP headers L hyperlinks Lightweight Directory Access Protocol. See See also URLs LDAP servers hypertext markup language. See HTML code links (Information Console) HyperText Transfer Protocol. See HTTP See also hyperlinks Linux servers I See also UNIX systems IDAPI applications log files See also Information Delivery API tracking error information and. See error iHub log files sending requests over 11 tracking usage information and. See usage iHub clusters. See clusters log files iHub repository. See Encyclopedia volumes Login operations iHub services See also SystemLogin operations See also specific iHub service Information Console M accessing functionality 11 mail. See e-mail Information Console Security Extension MDS. See Message Distribution service See also IPSE applications messages. See e-mail Information Delivery API metadata schemas. See schemas See also IDAPI applications methods input file IDs. See InputFileId element See also functions input file names. See InputFileName element Microsoft NET environments. See .NET input messages environments See also requests Microsoft Windows. See Windows systems Integration Technology. See iHub Integration monitoring tools Technology See also performance monitoring Interactive Crosstabs multilingual reports. See locales
Index 43 N plug-in extensions. See extensions PMD. See Process Management Daemon names PPT formats. See PowerPoint formats See also user names preferences (users). See user preferences naming restrictions. See case sensitivity print jobs nodes. See cluster nodes See also printing non-native reports. See third-party reports print requests. See print jobs notifications printer settings. See printer options sending attachments with. See attachments printing requests. See print jobs O purging. See deleting object IDs R See also ObjectId element RCP Report Designer package on-demand report generation. See See also BIRT RCP Report Designer synchronous jobs records online analytical processing servers. See See also rows OLAP servers removing. See deleting online help report components. See components See also help report design engine classes operations See also Design Engine API administration. See Administrate report documents operations See also reports archiving files and. See archiving Report Encyclopedia. See Encyclopedia operations volumes login. See Login operations report execution requests. See ExecuteReport searching. See search operations operations updating files and. See update operations report explorer. See ReportExplorer output components formatting. See output formats report files output messages See also files; specific report file type See also responses naming. See file names report objects. See reports P report parameter files page-level security See also data object values files; report See also page security application object value files parameter files report parameters See also data object values files; report See also parameters object value files restricting values for. See cascading parameter values files. See data object values parameters files; report object value files Report Server Security Extension parameters See also RSSE applications; RSSE API See also report parameters report servers. See iHub servers defining dynamic filters. See dynamic filter reporting system. See iHub System parameters reports permissions. See privileges sending as attachments. See attachments pick lists. See selection lists repositories
44 Building Web Applications Using BIRT APIs See also Encyclopedia volumes Software Development Kit requests See also SDK package See also SOAP messages sort fields. See sort columns sending 11 spreadsheets. See Excel spreadsheets responses SQL statements. See queries See also SOAP messages subdirectories. See subfolders result sets system administrators See also queries; search results See also administrators .rov files. See report object value files system schemas. See schemas RPCs. See remote procedure calls rptdesign format T See also report design files tab-separated values files. See TSV files rptdocument format tcpmon utility. See TCPMonitor See also report document files temporary files. See transient files RSSE applications temporary reports. See transient reports See also Report Server Security Extension text strings. See strings registering external users for. See external transactions user registration See also Transaction operations rules. See archiving rules types. See data types run requests. See report generation requests S U UI elements scheduled jobs See also user interfaces See also jobs Uniform Resource Locators. See URLs schemas universal hyperlinks. See hyperlinks See also WSDL schemas Universal Resource Identifiers. See URIs search criteria. See search conditions URIs search operations submitting requests and 11 See also searching user groups. See groups setting conditions for. See search user IDs conditions See also UserId element searching See also search operations V security credentials. See credentials security roles. See roles values sending requests 11 See also data servers version names See also iHub servers See also VersionName element services view parameters See also iHub services; web services See also ViewParameter element settings. See properties viewing parameters. See view parameters Simple Object Access Protocol. See SOAP viewing preferences. See viewer preferences SOAP endpoints viewing service. See View service See also SOAP ports Vista computers. See Windows systems SOAP requests. See requests volume administrators. See administrators SOAP responses. See responses volume schemas. See schemas volumes. See Encyclopedia volumes
Index 45 W web applications See also applications web service applications See also IDAPI applications Web Service Description Language. See WSDL web services messaging framework. See SOAP WSDL documents See also WSDL files WSDL elements See also XML elements WSDL2Java package See also code emitter X XML attributes. See attributes XML code See also code XML reports. See XML documents XML schemas See also WSDL schemas XP computers. See Windows systems
46 Building Web Applications Using BIRT APIs