Where to Go from Here

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

Note

Between Crystal Reports, report-to-report linking can also be accomplished using the built-in navigation in the Hyperlink tab of the Format Editor. This capability requires practice to master, but elegantly supports cut-and-paste report part linking.

For readers familiar with the Crystal Report viewer SDKs, OpenDocument might not seem like a big dealimplementing 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 :

http://<SERVER_NAME>:<PORT>/businessobjects/enterprise11/desktoplaunch_
/opendoc/openDocument.jsp

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

http://<SERVER_NAME>/businessobjects/enterprise11/InfoView/scripts/_
openDocument.aspx

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

[View full width]

[View full width]

http://dcakrinsky02:8080/businessobjects/enterprise11/desktoplaunch/opendoc/

openDocument.

jsp?token

=DCAKRINSKY02.CRYSTALD.NET

%401901JcNkdQhE3MvUpGjE1899JoLchMLcZOj03wtk&

sDocType

=rpt&

sDocName

=World+Sales+Report

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

Note

The Document ID is an internal integer identifier that cannot be easily determined from InfoView. You should navigate to the document in the Central Management Console. In the File Name string, you see the path within the File Input Server. Every document has its own subfolder that the document ID corresponds with the internal identifier. Here, the document ID is 306. If you click on Preview, the following URL is shown in the browser: http://dcakrinsky02:8080/businessobjects/enterprise11/admin/en/ infoobject .cwr?action=10005&cmd=view& id=306

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.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.4 shows the same report part as the prior example, but without contextual data. This is called Part mode.

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

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.

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

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:

StringVar openDocURL;
openDocURL:="http://dcakrinsky02:8080/businessobjects/enterprise11/";
openDocURL:=openDocURL+"desktoplaunch/opendoc/openDocument.jsp?sDocType=rpt";
openDocURL:=openDocURL+"&sDocName="+URLEncode("World Sales Report Prompted");
openDocURL:=openDocURL+"&lsSCountry="+URLEncode({Customer.Country});
openDocURL

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 actionsa 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:

[View full width]

http://dcakrinsky02:8080/businessobjects/enterprise11/desktoplaunch/opendoc/openDocument

.jsp?sDocType=rpt&sDocName=Sales+Report& lsSYear=[Year].[Year].&[1]

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

Note

Earlier in the chapter, the token parameter was discussed from the perspective of single sign-on from a third-party application. When linking between reports, there is no way to insert the user's session token in the link. OpenDocument does not require a token if a user session is already active. If the session times out or if it's the first report link the user ever clicks, OpenDocument automatically redirects the user to a login page.

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:

/businessobjects/enterprise11/desktoplaunch/InfoView/_
CrystalEnterprise_Webi/new.do

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.

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

<SCRIPT LANGUAGE="JavaScript">
    var editor="DHTML";
    function toggleEditor(newEditor){ editor=newEditor; }
    function createWebIDoc(universeID) {
        var viewURL="webiDHTMLOpenQueryPanel.jsp?unvid="+escape(universeID)+"& token=<%

=Util.URLEncodeUTF8(logonToken)%>";
        if (editor=="JAVA"){
            viewURL="webiAppletOpenQueryPanel.jsp?unvid="+escape(universeID);
        }
    windowprops = "height=600,width=800,location=yes,scrollbars=yes,menubars=yes

,toolbars=yes,resizable=yes";
        reportWindow = window.open(viewURL,"rptWindow",windowprops);
        reportWindow.focus();
    }
</SCRIPT>
WebI Editor:
<% if (BOEUtil.isWebIDHTMLCanCreate){%>
<INPUT TYPE=RADIO NAME="editor" VALUE="DHTML" checked onclick="toggleEditor('DHTML');">DHTML
<% } if (BOEUtil.isWebIJavaCanCreate) { %>
<INPUT TYPE=RADIO NAME="editor" VALUE="JAVA" onclick="toggleEditor('JAVA');">Java
<% } %>
<br>Universes<hr>
<% IInfoObjects universes=null;
    IInfoObject universeObject=null;
    universes=BOEUtil.getUniverses(iStore);
    int totalUniverses = universes.size();
    if (totalUniverses>0){
        for (int i = 0; i < totalUniverses; i++) {
        universeObject = (IInfoObject) universes.get(i);
        out.print("<IMG SRC='../images/universe.gif'> __
<A HREF=\"javascript:createWebIDoc('" +Util.URLEncodeUTF8(universeObject.getCUID())+"');\

">" +universeObject.getTitle() +"</A><br>");
        } out.print("<hr>");
    } else { out.write("<SPAN CLASS=normalText>No universes found</SPAN>");}
%> </TD></TR></TABLE>

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

var embed_size_attr = 'WIDTH="' + (self.innerWidth) + '" HEIGHT="' + (self.innerHeight-24)

+ '"';
out.println('<APPLET name="webiApplet"' + embed_size_attr +
' codebase="<%= contextPath %>/webiApplet/"' +
' archive="ThinCadenza.jar" ' +
' code="com.businessobjects.wp.tc.TCMain"> ' +
' <param name="Isapi" value="<%= contextPath %>/cdzServlet"></param>' +
' <param name="Server" value="<%= request.getServerName() %>"></param>' +
' <param name="Protocol" value="http"></param>' +
' <param name="Port" value="<%= request.getServerPort() %>"></param>' +
' <param name="Type" value="signed"></param>' +
' <param name="WebiSession" value="<%= strWISession %>"></param>' +
' <param name="CdzSession" value="<%= instanceID %>"></param>' +
' <param name="DocumentID" value="<%=""%>"></param>' +
' <param name="UniverseID" value="UnivCUID=<%=universeCUID%>"></param>' +
' <param name="bRobot" value="false"></param>' +
' <param name="bTraceInLogFile" value="false"></param>' +
' <param name="HelpRoot" value="<%= request.getContextPath().substring(1) %>">' +
' </param><param name="SaveAs" value="<%= request.getContextPath()%>
/javasdk/saveWebiAppletDoc.jsp?unvId=<%=universeCUID%>"></param><param name= "Lang"

value="<%= request.getAttribute( "lang" ) %>"></param></APPLET>');

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