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.

Note

In this chapter, URLs are referred to as dispatchers or handlers. This means that these files dispatch or handle other filesin this case, any .rpt, .car, or .wid report file. This design pattern provides utmost flexibility by not binding the service to any one particular report.

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

Parameter Syntax	Description of Parameter	Mandatory?	Values Accepted for Parameter
sType or sTyp	The file type of target document or report	Yes for WebI, Crystal Reports, or OlapI documents	wid rpt car
	For agnostic documents, such as Word, Excel, and Txt, the sType parameter must be explicitly omitted.
sDocName or sDoc	Document name	sDocName or iDocID is mandatory	Document name
iDocID	Document identifier	One of sDocName or iDocID is mandatory	Document identifier
Example: openDocument.jsp?sType=rpt& iDocID=306
sIDType	Crystal object type	Yes, if the ID is not the default, numeric InfoObjectID	CUID Cluster identifier GUID Global identifier RUID Package identifier ParentID Numeric ID in cluster InfoObjectID (default) Numeric ID in cluster
Example: openDocument.jsp?sType=wid&sIDType=CUID&iDocID=AfC7y9nvVHhMmWyZ_uiCL6EInfoObjectID, CUID and GUID identifiers can be retrieved programmatically under the properties SI_ID, SI_CUID, SI_GUID respectively.
sReportPart	Indicates which specific part (Object Name) of the target report to open.	No	Name of the report part object. Report parts may include field objects, charts or maps, images, cross-tabs, and text objects. They may not include subreports, among other things.
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report&sReportPart=Top5CountryChart
sPartContext	In Crystal Reports, a report part is associated to a data context.	Yes, if a value is specified for sReportPart	Data context of the report part
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report&sReportPart=CountrySalesGraph&sPartContext=/Country[USA]
sReportMode	For Crystal targets only, indicates whether the link should open the full target report or just the report part specified in sReportPart.	No (default is Full); only applies if a value is specified for sReportPart	Full Part
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report&sPartContext=/Country[USA]&sReportMode=Part
sRefresh	Forces document refresh with prompting	No	Y (forces the document's refresh) N (if Refresh on Open is set to Yes in the CMC, the document is refreshed)
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report&sRefresh=Y
sInstance	Indicates which specific instance of the target report to open.	No (use with sDocName and lsS[NAME])	User Latest instance owned by current user Last Latest instance for report Param Latest instance of report with matching parameter values
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report&sInstance=User
lsS[NAME]	Specifies a value for a single prompt. [NAME] is the text of the prompt.	No	A single prompt value.
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report+Prompted&lsSCountry=USA
lsM[NAME]	Specifies multiple values for a prompt. [NAME] is the text of the prompt.	No	Multiple prompt values, separated by a comma. If the target is a Crystal report, each value must be enclosed in square brackets and separated by commas. If the target is a Web Intelligence document, multiple values must be separated by semi-colons. For more information on OLAP Intelligence parameters, please consult the product documentation. Note: To supply a single value to a Crystal Reports prompt that accepts multiple values, you must use lsS rather than the lsM.
Example: openDocument.jsp?sDocType=rpt&sDocName=World+Sales+Report+Prompted&lsMCountries=[USA],[Germany]
lsR[NAME]	Specifies a range of values for a prompt. [NAME] is the text of the prompt. Note: Not supported by OLAP Intelligence	No	A range of values for the prompt, separated by a double period (..). If the target is a Crystal Report, the range must be enclosed in square brackets and/or parentheses (use a square bracket next to a value to include it in the range, and parentheses to exclude it).
Example: openDocument.jsp?sType=rpt&sDocName=SalesReport&lsRCustomer+Order+Count=[10..25]&lsROrder+Date+Range=[DateTime(2003,1,1,0,0,0)..DateTime(2004,12,1,0,0,0)]
sReportName	Indicates which report to open if the target document contains multiple reports (Web Intelligence documents only)	No	Active report is opened by default
lsC	Specifies a contextual prompt if there is an ambiguity during SQL generation (Web Intelligence documents only)	No	A prompt value that resolves the ambiguity in the SQL generation.
Example: openDocument.jsp?sDocType=wid&sDocName=Ambiguous+Contexts+Example&lsC=RESERVATION

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.1. Report Part Names are set in the Crystal Report Format Editor window.

Figure 31.2. Viewing a Report Part.

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.

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.

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.

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

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: [View full width] http://dcakrinsky02:8080/businessobjects/enterprise11/desktoplaunch/opendoc/openDocument .jsp?sDocType=rpt&sDocName=Sales+Report& lsSYear=[Year].[Year].&[1]
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 36.
13.	Click OK.

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.

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

[View full width]

<SCRIPT LANGUAGE="JavaScript">     var editor="DHTML";     function toggleEditor(newEditor){ editor=newEditor; }     function createWebIDoc(universeID) {         var viewURL="webiDHTMLOpenQueryPanel.jsp?unv& token=<% =Util.URLEncodeUTF8(logonToken)%>";         if (editor=="JAVA"){             viewURL="webiAppletOpenQueryPanel.jsp?unvheight=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='/books/2/423/1/html/2/../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

[View full width]

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

Acceptable Characters
The alphanumeric characters az, AZ, and 09 remain the same.
The special characters ".", "-", "*", and "_" remain the same.
Reserved Characters		Unsafe Characters
These characters have a special role inside URLs. If appearing outside that role in text, they must be encoded.		These characters can be misunderstood by the system for various reasons.
Reserved	Encoded	Unsafe	Encoded
Ampersand ("&")	%26	Space (" ") standard	+
Dollar ("$")	%24	Space (" ") alternate	%20
Plus ("+")	%2B	Quotation marks	%22
Comma (",")	%2C	Less Than symbol ("<")	%3C
Forward slash/virgule ("/")	%2F	Greater Than symbol (">")	%3E
Colon (":")	%3A	Left curly brace ("{")	%7B
Semi-colon (";")	%3B	Right curly brace ("}")	%7D
Equals ("=")	%3D	Vertical bar/pipe ("|")	%7C
Question mark ("?")	%3F	Backslash ("\")	%5C
At symbol ("@")	%40	Caret ("^")	%5E
Pound character ("#")	%23	Tilde ("~")	%7E
Percent character ("%")	%25	Left square bracket ("[")	%5B
		Right square bracket ("]")	%5D
		Grave accent ("`")	%60

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.