Chapter 31 Using the Web Components

In this chapter

Overview 798

URL Reporting 798

JavaServer Faces 813

BusinessObjects Enterprise XI .NET Server Controls 816

Portal Integration Kits 820

Review 824

Overview

This chapter explores a series of rapid development options that permit you to quickly integrate BusinessObjects Enterprise XI with your enterprise applications. These include the capability to view, create, and edit reports simply by calling URLs; integrating components visually using .NET components or Java Server Faces (JSF); or simply deploying prebuilt catalog browsing and viewing portlets into Microsoft SharePoint, WebSphere Portal, or any other JSR-168–compliant Java portal.

URL Reporting

This section of the book is vital because it covers, from an integration standpoint, the most common integration use-cases through invocation of simple URLs. To run without prompting the user for credentials, these URLs take a token parameter that represents the session token of an active BusinessObjects Enterprise session. This token is generated by using the getToken() method of the user’s BusinessObjects Enterprise session (see Chapter 30, “Using the BusinessObjects Enterprise APIs”). These credentials expire automatically in a configurable amount of time unless they are invalidated earlier by use of the logoff() method.

Historically, Crystal Enterprise customers were accustomed to using the viewrpt.cwr dispatcher. Classic Business Objects customers, by contrast, were accustomed to the openAnalytic.jsp dispatcher. BusinessObjects Enterprise XI includes a new dispatcher called openDocument.jsp/aspx. OpenDocument is the most flexible of the dispatchers and moving forward, it will be the preferred approach.

Viewing a Crystal Report or OLAP Intelligence Document with viewrpt.cwr

Before discussing openDocument.jsp/aspx, please note that viewrpt.cwr has not been deprecated. Existing viewrpt.cwr users do not need to migrate their implementations. In fact, in a handful of cases, viewrpt.cwr has no analog in OpenDocument and is the only solution.

Viewrpt.cwr is a Crystal classic technology whose implementation has evolved slightly with BusinessObjects Enterprise XI. In a Java environment, viewrpt.cwr is a mapping to the viewrpt servlet. In an ASP or .NET environment, viewrpt.cwr is redirected to viewrpt.aspx or viewrpt.asp.

Although it cannot display Web Intelligence documents, viewrpt.cwr enables a variety of ways for viewing Crystal Reports that OpenDocument does not. For instance, it supports the no longer trendy but uniquely capable ActiveX and Java Applet viewers. These viewers support report streaming without page reloading. If your Crystal Report uses summarizations and formulas carefully, it is possible to begin displaying a report using these viewers before the report has finished processing.

For desktop Windows applications, there is no equal to the CRViewer1 ActiveX control, chosen by hundreds of third-party OEMs. For desktop Java applications, there is, unfortunately, no Java viewing component. Even the Java Applet viewer requires a web-based host application. Customers have had modest success by installing an application server locally and viewing reports within an embedded Java Web browser by ICEsoft (www.icesoft.com).

Additionally, viewrprt.cwr supports a powerful use case where you can programmatically push the entire reportClientDocument into the viewer via a shared session variable, identified in the URL query string.

For additional information on viewrprt.cwr, please consult the Viewers COM SDK guide.

Viewing a Crystal Report, Web Intelligence Document, or OLAP Intelligence Document with OpenDocument

OpenDocument, new to BusinessObjects Enterprise XI, provides the ability to integrate a wide variety of InfoView objects into your development projects, as well as interlink reports to one another.

Several scenarios include

• Linking from one Crystal Report to another
• Opening a managed Microsoft Office document from a custom Java or .NET application
• Drilling from an OLAP Intelligence dimension to a Web Intelligence document, passing context as a parameter
• Integrating Crystal or Web Intelligence reports with third-party web-based applications, such as ESRI ArcIMS

For readers familiar with the Crystal Report viewer SDKs, OpenDocument might not seem like a big deal—implementing a custom viewer is easy. You will find a fairly robust, standalone Crystal Reports viewer built using the SDK on www.usingcrystal.com. Neither Web Intelligence nor OLAP Intelligence, however, has (today) a drop-in componentized viewer. You can write your own Web Intelligence viewer using instructions in the customizing_webintelligence.pdf document that ships with the product or looking at the source code in InfoView. Be forewarned, it’s fairly complicated. Using OpenDocument, you can access the InfoView viewer and do not need to write your own.

Now that you know what OpenDocument is, when to use it, and a bit about why, how to use OpenDocument is discussed next.

OpenDocument.jsp and OpenDocument.aspx

In the Java environment, the OpenDocument dispatcher is called OpenDocument.jsp and can be found at the following path:

In the .NET environment, the same functionality can be found at

QueryString Syntax

The OpenDocument dispatchers require parameters in the form of a URL query string (the part after the “?” in a URL) in order to function. Query strings are collections of ParamName/ParamValue pairs separated by equal signs (“=”) and joined together by ampersands (“&”).

A sample syntax for opening the World Sales Report without prompting a login is

The first part of the URL refers to the machine and application server port. A default Apache Tomcat installation is run locally, so the server name is DCAKRINSKY02 and the port is 8080. The token value was captured programmatically using code discussed in Chapter 30. The sDocType parameter is the file type of the target document: wid (Web Intelligence document), rpt (Crystal Report), or car (OLAP Intelligence document). The sDocName represents the name of the object on the system. If more than one document by this name exists on the system, the first one found is used.

Table 31.1 describes each of the supported parameters and its use. For brevity, the full URL path and the token argument has been omitted from the example URLs. If a user has already logged into InfoView or a token has been provided in a prior request, the token parameter is optional because it has already been persisted in the application server session. If the Enterprise session has expired, users are redirected to the default InfoView logon page and then redirected to the requested URL. Several documented parameters, including sOutputFormat and NAII, do not work as specified and have been omitted from this table. Others that work but are not documented, such as token, have been added. Service packs and documentation updates should address these issues.

Table 31.1. OpenDocument URL Parameters

Figure 31.1 shows how a report part is named using the Object Name property of the Common tab of the Crystal Reports Object Format editor. Figure 31.2 shows a report part rendered using the sReportPart syntax in the previous example.

Figure 31.1. Report Part Names are set in the Crystal Report Format Editor window.

Figure 31.2. Viewing a Report Part.

Table 31.1. OpenDocument URL Parameters (continued)

Figure 31.3 shows a particular, non top-level report part, Country, known by the dimension USA in the report group. This report part might be accessible in the top-level of a report, or might requiring drilling to reach. By default, the report part is shown in the context of its data. This is called Full mode.

Figure 31.3. Report part context in Full mode.

Table 31.1. OpenDocument URL Parameters (continued)

Figure 31.4 shows the same report part as the prior example, but without contextual data. This is called Part mode.

Figure 31.4. Report part context in Part mode.

Table 31.1. OpenDocument URL Parameters (continued)

Following is a summary of differences between Web Intelligence documents and Crystal Reports accepting multiple prompt values.

Web Intelligence

For filling prompts that accept multiple values (in list):

• Multiple values must be specified using lsM<PROMPTNAME>=val1;val2
• Single values must be specified lsM<PROMPTNAME>=val1

Crystal Reports

For filling prompts that accept multiple values:

• Multiple values must be specified using lsM<PROMPTNAME>=[val1],[val2]
• Single values must be specified lsS<PROMPTNAME>=val1

Table 31.1. OpenDocument URL Parameters (continued)

Context is a fairly complex topic covered elsewhere in this book. If there are multiple ways to resolve a SQL query, the context must be specified in order for the Universe to pass the Designer integrity check. Figure 31.5 shows how context is defined in the Universe Designer.

Figure 31.5. The context definition in the Universe Designer.

As shown in Figure 31.6, the end-user is prompted if a valid value for lsC is not provided.

Figure 31.6. The context run-time prompt.

Creating an OpenDocument Link in Crystal Reports

To open another report from Crystal Reports, use the Hyperlink tab of the Field Format Editor and follow these steps:

1. Open the source report in Crystal Reports.
2. Right-click the field in which you want to insert the OpenDocument link and select Format from the shortcut menu.
3. In the Format Editor, select the Hyperlink tab.
4. Select a website on the Internet.
5. In the Hyperlink Information area, leave the Website Address field empty and click the Format Formula Editor button.
6. In the Formula Editor, use your preferred Crystal syntax to build a context-aware OpenDocument URL link string like the following (this example also demonstrates string concatenation and the new URLEncode() function in Crystal Reports):
   

   

You can test the formula by creating a temporary parameter that uses the same formula and outputting it directly on your report. Click the Save and Close button in the Formula Workshop to continue.

Creating an OpenDocument Link in OLAP Intelligence

Although not the focus of this book, OLAP Intelligence is a very welcome tool in the quiver of any Business Objects customers that have deployed traditional OLAP databases. Among its more powerful features is the capability to define custom actions—a welcome addition to Crystal Analysis v.10 that also made it into XI. Prior to this enabling feature, you needed to define actions in the underlying OLAP database. Follow these steps to create a hyperlink from an OLAP Intelligence document using the openDocument.jsp/aspx dispatcher:

1. Open the source report in the OLAP Intelligence designer.
2. Click New to create a new action.
3. Enter an action name.
4. Select the area to which the action (the link) will apply.
5. Enter the OpenDocument link leveraging MDX syntax according to samples in the product documentation:
   

   

6. Click OK to save the link.
7. Close the Action Manager dialog box.
8. Create an Analysis button on the source report.
9. Right-click the Analysis button.
10. In the drop-down menu, select Properties and then Edit.
11. Select Launch an Action.
12. Select the action that corresponds to the OpenDocument link created in steps 3–6.
13. Click OK.

Actions for OLAP Intelligence are covered in more detail in Chapter 19, “Creating OLAP Intelligence Reports.”

Creating a New Web Intelligence Document

With the release of the near feature parity 0-client (IE, Netscape [Mozilla], and Safari) Web Intelligence document editor, exposing industry-leading ad hoc analysis capabilities to intranet and extranet customers is arguably the most compelling new feature in all of Business Objects XI. As a result, it was surprising to find no dispatcher that permits creation of a new Web Intelligence document with the DHTML query panel (based on a Universe identifier and a user session token). This will be rectified in the next release. In the meantime, there are two solutions that will work for XI.

First, you can call the InfoView STRUTS action that presents the user with a list of Universes and subsequently permits creating a new Web Intelligence document:

Figure 31.7 shows a page inside a frameset. Clicking on a Universe name in the Title column opens either the DHTML or Java query panel, depending on a user’s InfoView preferences.

Figure 31.7. Creating a new Web Intelligence document.

Because InfoView is likely to be rewritten and the new.do action is undocumented, this approach might break in subsequent releases. The scenarios described here will probably be fully supported through well-documented dispatchers at that time.

The second approach is to actually write dispatchers to create new WebI documents inside the DHTML and Java query panels. The code for the Java query panel actually comes from the Developer suite and is fully documented there. The code for the DHTML query panel wrappers an InfoView JSP file, openQueryPanel.jsp, that is subject to change in future releases. For both approaches, you need to first create a session token, check permissions to create Web Intelligence documents, and retrieve a list of Universes. This code is already provided in Chapter 30 and is not repeated here.

Displaying a List of Universes

The last chapter showed how to query the InfoStore to retrieve a list of Universes. This and code showing how to determine a user’s rights vis-à-vis creating WebI documents are encapsulated in the utility function BOEUtil.java found on www.usingcrystal.com. Listing 31.1 shows how functions are used to render a list of Universes from which a user can create new WebI documents using either the DHTML or Java viewers.

Listing 31.1. Universes.jsp

Creating a New Web Intelligence Document in the Java Query Panel

You can find the complete code listing for the webiAppletOpenQueryPanel.jsp and the companion webiAppletSaveDoc.jsp files at www.usingcrystal.com. To give you a sense of what is involved, a partial code listing is shown in Listing 32.2. Remember that for the applet to work properly, you must configure the cadenza servlet in web.xml, through which the Java applet communicates with the WebIntelligence Report Engine, before samples like this will work properly.

Listing 31.2. Snippets from webiAppletOpenQueryPanel.jsp

Creating a New Web Intelligence Document in the DHTML Query Panel

The DHTML query panel is comprised of a series of JSP pages. One of them is a file called openQueryPanel.jsp that does everything you want it to do except log in the user. In order to create a new WebI document without InfoView prompting the user to enter credentials, you need to put a login page in front of openQueryPanel.jsp that logs in the user and then forwards the request to it. Place the login page in the /desktop/InfoView/viewers/cdz_adv/directory. The full listing, webiDHTMLOpenQueryPanel.jsp, is posted on www.usingcrystal.com.

URL Parameter Building Tips

Conventions that apply to building any URLs apply here. Since malformed URLs are a common source of problems when building internet applications, some tips on building URLs are included in the following sections.

URL Encoding

Because name-value pairs in a URL are delimited by = and separated from one another by &, values containing these and certain other special characters must be encoded and, when used, decoded. These are called reserved characters because they have a special role inside URLs. If appearing outside that role in text, they must be encoded. Other special characters are called unsafe characters because they can be misunderstood by the system for various reasons. These must also be encoded.

Encoded values appear as three-letter codes, starting with % and ending with the two-letter hexadecimal representation of the encoded character byte. Naturally, % is also a special character that must be encoded. Normally, this work is done by URL encoder/decoder functions in your development environment of choice. The rules for URL encoding are provided in Table 31.2.

Table 31.2. URL Encoding Conventions

Other Tips

Here are some other tips for building URLs in Business Objects and sometimes elsewhere:

• The encoded URL cannot exceed 2,083 characters.
• Parameters in Business Objects handlers are case-sensitive.
• Strip spaces between separator characters (“=” and “&”) and at the end of parameters.
• Use the new URLEncode() function in the Crystal Formula language.

JavaServer Faces

For years, Microsoft ASP developers debated best practices for organizing their web applications and managing interactions between the front- and back-ends. The .NET framework answered many of these questions, providing a neat methodology, system libraries, and IDE integration capability for quickly and easily wiring together stateless components into interactive web applications. In certain respects, what .NET is to ASP, JavaServer Faces (JSF) is to JSP. The similarities are so striking, in fact, that you might surmise that Redmond helped with the design. Its goal is to make rapid, consistent, and visual application development possible through a set of libraries and strict methodologies that integrated development environments (IDEs) can understand.

JSF is a follow-on to the ever-popular Apache STRUTS application development framework. Both provide an architectural design based on the Model View Controller (MVC) JSP Model 2 pattern that specifies that end-user requests are managed by a servlet that controls the flow, components are used to access and manipulate the data, and JSP is used to render content to the browser. The JSP Model 2 pattern can be difficult to understand. A simplified diagram is shown in Figure 31.8. Please Google this topic to learn more.

Figure 31.8. The JSP Model 2 MVC design pattern.

Although STRUTS had a large following, it was not a standard managed by the Java Community Process (JCP). Some critics note that the design changed frequently and tool vendors were late and inconsistent in their support. JSF, on the other hand, is a JCP standard that was designed for use inside of tools from the very beginning. As such, it is a stable specification supported by all Java tool vendors.

If JSF thrives, it is likely that you will see much more in this area from vendors such as Business Objects. In XI, Business Objects offered a taste of JSF with the Crystal Reports viewer control.

Figure 31.9. The JSP Model 1 design pattern.

JSF Component Overview

With BusinessObjects Enterprise XI, six JSF components are provided. Together, they permit logging into BusinessObjects Enterprise, changing passwords, displaying and browsing repository folders, rendering folder breadcrumbs, and viewing a Crystal Report.

Product documentation fully describes configuring and using the JSF components. The technical support team has also put together some wonderful viewlets documenting a sample development project in IBM Rational IDE that they have kindly posted at www.usingcrystal.com.

After these controls are registered with the IDE, they can be easily added to web projects. Figure 31.10 shows adding Enterprise Faces Components, Report Viewers Faces Components, and the Java Reporting Component (JRC) to a web project. Larger implementations prefer using the BusinessObjects Enterprise Page Server as a report source, eliminating the need for the JRC.

Figure 31.10. Adding JSF controls to a project.

After the components are added to your project, you can drag and drop them onto your pages, set their properties, and wire them together using listeners in the code-behind pages. Figure 31.11 shows a folder-browsing and report-viewing application under construction.

Figure 31.11. JSF folder-viewing application.

The six JSF components are as follows

• logon—Renders an HTML BusinessObjects Enterprise logon form
• changePassword—Renders an HTML BusinessObjects Enterprise change password form.
• itemsGrid—Renders (along with one or more itemsColumn tags) an HTML table, or grid, that displays the items from an EnterpriseItem or EnterpriseItems bean
• itemsColumn—Renders column within itemsGrid to display property of items from an EnterpriseItem or EnterpriseItems bean
• path—Renders hyperlink breadcrumb trail
• reportPageViewer—Renders Crystal Reports DHTML viewer

For more complete instructions for setting up and working with JSF components, please consult the product documentation and check out www.usingcrystal.com.

BusinessObjects Enterprise XI .NET Server Controls

As always, .NET developers will be delighted by Business Objects’ support for the platform. As shown in Figure 31.12, .NET support is provided through a four-tiered API stack: server controls, components, supporting API, and the underlying .NET API.

Figure 31.12. The .NET server controls for the API stack.

Together these APIs expose the entire BusinessObjects Enterprise infrastructure and Crystal Reports functionality. Public APIs are not provided for viewing or editing Web Intelligence and OLAP Intelligence documents. Rather, use openDocument.aspx discussed earlier in this chapter. These components are exhaustively documented in the core product. You will find examples that cover adding controls to your .NET Studio projects, setting properties, and scripting interactivity using code-behinds. This section provides a top-level glimpse of how a web developer might use the server controls to build a quick business intelligence portal.

.NET server controls are broken down into four logical categories:

• Authentication and user management
• Object listing and navigation through objects
• Scheduling of objects
• Viewing of objects

The controls included in each category and how they can help you in BusinessObjects Enterprise XI application development are discussed next.

Authentication and User Management

This category includes two controls: logon and change password.

The logon control (see Figure 31.13) creates a form on your web page that allows users to authenticate themselves against the Enterprise CMS, generate a session token, and persist their entire Enterprise session for fast access on subsequent requests.

Figure 31.13. The .NET logon control.

The change password control allows the end user to change her password when she wants to do so (see Figure 31.14).

Figure 31.14. The .NET change password control.

Repository Browsing

The items grid control (see Figure 31.15) allows the users to easily navigate through the folder structure inside the system and is implemented in the form of a table where columns represent the properties of each object, such as name, description, and so forth, and the rows are the items returned from the CMS. BusinessObjects Enterprise XI applies security filtering automatically.

Figure 31.15. The .NET items grid control.

Scheduling

The scheduling control provides a nice user interface wrapper around the BusinessObjects Enterprise XI scheduling engine (see Figure 31.16).

Figure 31.16. The .NET schedule control.

Most times, just specifying the date and time is not all that is required to schedule the report. That is why the following controls have also been implemented as part of this category:

• Destination control—Allows you to specify the destination for the report; for example, inbox, e-mail, FTP, file, and so forth
• ReportFormat control—Allows the user to specify which format the report should run; for example, Adobe Acrobat, Microsoft Word, Excel, Text, and so on
• ReportFilters control—Allows the user to specify the filters that should be applied when the report runs; for example, {Customer.Country}=’USA’
• ReportPrint control—Allows the user to specify the print settings when printing the report, as well as the report layout
• ReportDatabaseLogon control—Allows the user to set database username and password prior to running the report
• ReportParamters control—Allows the user to specify the required parameter values for the particular report

Java developers ought to be rightly envious—Business Objects provides them no similar out-of-the-box control.

Object Viewing

Finally, the viewer control permits in-line viewing of Crystal Reports as shown in Figure 31.17.

Figure 31.17. The .NET viewer control.

Event Handling

Business Objects makes it easy for you to use server controls in your projects. All the controls share one common AutoHandleEvents property that allows for the forms submission to automatically perform the default action associated with the particular control. For example, when the user clicks on the Submit button on the schedule form and the AutoHandleEvents property is set to True, the default action is performed by the control and the specified report will be scheduled inside the BusinessObjects Enterprise XI system. You can override these events with your own logic that handles the default behavior.

Business Objects XI continues the Crystal tradition of excellent support of the .NET platform. Please consult the product documentation for more information.

Portal Integration Kits

Business Intelligence is a natural complement to an intranet. Most companies today have implemented custom, open-source, or commercial portals that provide a security, navigation, and layout framework for presenting corporate information assets. Products include Microsoft SharePoint, Apache Jetspeed, OpenText Livelink, and namesake portal servers by IBM, Vignette, Plumtree, BEA, SAP, and Oracle, to name but a few.

For many years, every portal product had their own API for creating, managing, and communicating between blocks in the portal, often referred to as portlets. In Microsoft SharePoint, these are called web parts. In SAP portals, they are iViews. Recently, Java vendors have coalesced around the JSR 168 standard that permits vendors such as Business Objects to write a single portlet implementation and deploy it in a wide variety of portal products. Business Objects has been producing portal integration kits (PIKs) for many years. On the Crystal side, the first portlets were web parts developed for Microsoft SharePoint by Crystal veteran Craig Chaplin.

The next generation of Business Objects PIKs is modeled on the SharePoint integration and supports the JSR-168 specification. Functionality, partially shown in the following screenshots, includes preference integration; folder browsing and management; scheduling; inbox; favorites (“subscriptions”); and personalized, parameterized viewing of Crystal Reports, Web Intelligence documents, and managed Microsoft Office/PDF files. On-report parameter support is better implemented than in the core product itself and linking between portlets on the same page (interportlet communication) is fully supported.

Light customization is possible through style sheets. Users can customize foreground and background colors themselves. If major changes are required, you can start from scratch or dig into the (somewhat complex) source code.

You can preview the JSR-168 portlets in the following figures below. Figure 31.18 shows navigating through the folder hierarchy and listing the reports within. Clicking on Subscribe adds a report to your personal favorites.

Figure 31.18. The JSR-168 Repository Browser portlet.

Figure 31.19 shows how the various types of objects are surfaced through the portlet and shown through a pop-up window—in this case, a Microsoft PowerPoint document.

Figure 31.19. The JSR-168 Viewer portlet, showing a hosted Microsoft Powerpoint document.

Figure 31.20 shows a Crystal Report viewer and Figure 31.21 shows a WebI document.

Figure 31.20. The JSR-168 Viewer portlet, showing a Crystal Report.

Figure 31.21. The JSR-168 Viewer portlet, showing a WebI document.

On Java platforms, portlets are packaged in a WAR archive. Instructions for configuring the BusinessObjectsPortlets.war file are provided for BEA, IBM, and Oracle application servers and IDEs in the Business Objects XI Portal Integration Kit documentation. You will be able to deploy the portlets on other J2EE application servers as well by following the methodology in the documentation.

SAP Portals

Business Objects has invested tremendous resources in making its product stack the pre-eminent platform for business intelligence on SAP R/3 and BW. Crystal Reports, Web Intelligence, OLAP Intelligence, and Data Integrator all have native connectors for SAP that reduce the need for ABAP and BAPI programmers. SAP co-developed several of the solutions and bundles solely Business Objects BI products with their software. Additionally, should you want more than a limited license to the tool, SAP itself is an authorized Business Objects reseller.

Business Objects ships a collection of cross-platform iViews that deeply integrate with SAP security and provide similar capabilities as the JSR-168 portlet implementation. These iViews permit tight and fast integration of production reports, ad hoc query, and guided analysis with your SAP portal (see Figure 31.22).

Figure 31.22. The SAP PIK, viewing a Web Intelligence document.

More than 100 predefined reports are shipped with the SAP solution kit and there is a wizard-driven install on the Business Objects SAP BW CD-ROMs.

For more information on SAP integration, please visit www.businessobjects-sap.com.

Review

SDK integration, covered in Chapter 30, is the most powerful and flexible way to incorporate Business Objects functionality into your applications. However, it requires familiarity with programming and might be daunting. As described in this chapter, integrating reports using URL dispatchers, by contrast, is quick and easy—requiring only a knowledge of creating URLs. Other component integration requires some programming, but in most cases it provides more functionality in less time than writing code from scratch or cutting and pasting from samples. Beware of the little things, however. Many customers find the Java server faces development paradigm difficult to understand and the JSR-168 Business Objects PIKs do not support security integration out of the box.