SAP Business objects Enterprise XI 3.0 Viewing Reports and Documents using URLs
Viewing Reports and Documents
using URLs
BusinessObjects Enterprise XI 3.1
Copyright
© 2010 SAP AG. All rights reserved.SAP, R/3, SAP NetWeaver, Duet, PartnerEdge,
ByDesign, SAP Business ByDesign, and other SAP products and services
mentioned herein as well as their respective logos are trademarks or registered
trademarks of SAP AG in Germany and other countries. Business Objects and the
Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web
Intelligence, Xcelsius, and other Business Objects products and services mentioned
herein as well as their respective logos are trademarks or registered trademarks
of Business Objects S.A. in the United States and in other countries. Business
Objects is an SAP company.All other product and service names mentioned are
the trademarks of their respective companies. Data contained in this document
serves informational purposes only. National product specifications may vary.These
materials are subject to change without notice. These materials are provided by
SAP AG and its affiliated companies ("SAP Group") for informational purposes
only, without representation or warranty of any kind, and SAP Group shall not be
liable for errors or omissions with respect to the materials. The only warranties for
SAP Group products and services are those that are set forth in the express
warranty statements accompanying such products and services, if any. Nothing
herein should be construed as constituting an additional warranty.
2010-03-25
Contents
OpenDocument 5Chapter 1
Getting started.............................................................................................6
OpenDocument syntax................................................................................9
Session management................................................................................11
Parameter reference..................................................................................13
Crystal Reports URL Reporting 37Chapter 2
About this documentation.......................................................................6
What's new with OpenDocument...........................................................7
Basic URL syntax...................................................................................9
URL syntax considerations...................................................................10
Logon tokens........................................................................................12
User sessions ......................................................................................13
Session management parameters.......................................................17
Document identifier parameters...........................................................18
Input parameters..................................................................................23
Output parameters...............................................................................33
Getting started...........................................................................................38
About this documentation.....................................................................38
What's new with Crystal Reports URL reporting..................................39
Migrating your links..............................................................................40
URL syntax................................................................................................41
Basic URL syntax.................................................................................41
URL syntax considerations...................................................................42
Command reference..................................................................................42
Authentication commands....................................................................45
Viewing Reports and Documents using URLs 3
Contents
Document identifier commands............................................................51
Input commands...................................................................................53
Output commands................................................................................65
More Information 69Appendix A
Index 73
4 Viewing Reports and Documents using URLs
OpenDocument
1
OpenDocument
1
Getting started
Getting started
About this documentation
This documentation provides you with information for constructing
parameterized URLs with the OpenDocument syntax. OpenDocument URLs
link to Business Intelligence (BI) documents in an BusinessObjects Enterprise
system. A parameter reference, including syntax and usage examples, is
provided for each OpenDocument URL parameter.
For information about deploying the OpenDocument web application after
the installation of BusinessObjects Enterprise, see the BusinessObjects
Enterprise Web Application Deployment Guide.
Who should use this documentation?
This documentation is for anyone creating URLs to BI documents with the
OpenDocument syntax. We recommend consulting this guide if you are:
• Providing end users with hyperlinks to a document through email or other
direct means.
• Embedding hyperlinks in one document to another.
• Programmatically generating hyperlinks to documents in your custom
application.
Familiarity with the management and organization of objects in your
BusinessObjects Enterprise deployment is beneficial.
About OpenDocument
OpenDocument is one of many deployed web applications within an
BusinessObjects Enterprise system. It processes incoming URL requests
for documents and any other viewable object type in the Central Management
Server (CMS), and delivers the correct document to the end user in the
appropriate viewer. This allows you to send users direct links to a document
and avoid having them navigate through a folder hierarchy, such as in
InfoView. The OpenDocument syntax and its parameters allow you to
6 Viewing Reports and Documents using URLs
OpenDocument
Getting started
construct URLs that link to these documents. For example, consider the
following URL:
http://<servername>:<port>/OpenDocument/opendoc/openDoc
ument.jsp?iDocID=Aa6GrrM79cRAmaOSMGoadKI&sIDType=CUID
Note:
Replace <servername>:<port> with the name and port number of your web
server where OpenDocument is deployed.
This URL accesses the object in the CMS with the CUID value of Aa6Gr
rM79cRAmaOSMGoadKI. If this is a Crystal report, for example, then the
report is rendered to the user in a default Crystal Reports viewer. In this
example, iDocID is one of many URL parameters. These parameters specify
how to access a particular document in the CMS, or determine how to display
the document to the user.
You can link to many viewable object types with the OpenDocument syntax.
Some examples include:
• Crystal reports
• Web Intelligence documents
• Voyager workspaces
• InfoView dashboards
• Xcelsius visualizations published as SWF files.
1
Some of the designers for these BI document types provide GUI-based URL
builders to help you embed openDocument URLs into your documents.
Consult their respective product documentation for information on these
features.
What's new with OpenDocument
URL syntax change
The virtual directory businessobjects is no longer created during installion
of BusinessObjects Enterprise. This affects the URL syntax for
OpenDocument links.
Viewing Reports and Documents using URLs 7
OpenDocument
1
Getting started
The previous URL syntax was:
http://<servername>:<port>/businessobjects/enter
prise115/<platformSpecific>?<parameter1>&<parame
ter2>&...&<parameterN>
The new URL syntax is:
http://<servername>:<port>/OpenDocument/<platformSpecif
ic>?<parameter1>&<parameter2>&...&<parameterN>
The exact syntax of the <platformSpecific> parameter depends on your
BusinessObjects Enterprise deployment:
• For Java deployments, use openDocument.jsp in place of the
<platformSpecific> parameter.
• For .NET deployments , use opendocument.aspx in place of the
<platformSpecific> parameter.
Note:
Variables are denoted with angle brackets. You must substitute the proper
value for these variables. For example, you must use the name of your
BusinessObjects Enterprise server where OpenDocument is hosted in place
of <servername> and you must use the correct port number in place of
<port> to access the OpenDocument web application.
Links to documents must use the new URL syntax, or you must create the
appropriate businessobjects virtual directory.
sReportMode
sReportMode is a new URL parameter to view a Crystal Report in different
modes depending on the option passed to the parameter. Possible values
include:
• part displays part of a report using the parts viewer to render the report.
• printlayout displays the report in a print preview layout.
• weblayout displays the report as a web page layout.
8 Viewing Reports and Documents using URLs
Interactive Parameters
Crystal Reports parameter prompt values passed into the URL are always
be applied to the report, even if the report instance contains saved data. This
is a change in behavior from previous releases.
Forcing the Prompts dialog for Web Intelligence prompts
The character ? is now a reserved prompt value for Web Intelligence
documents in an OpenDocument URL. Setting the prompt value to
lsM[NAME]=? or lsS[NAME]=? in the URL forces the "Prompts" dialog box
to appear for that particular prompt.
OpenDocument syntax
Basic URL syntax
The basic syntax for an OpenDocument URL is as follows:
OpenDocument
OpenDocument syntax
1
http://<servername>:<port>/OpenDocument/opendoc/<platform
Specific>?<parameter1>&<parameter2>&...&<parameterN>
The exact syntax of the <platformSpecific> parameter depends on your
BusinessObjects Enterprise deployment:
• For Java deployments, use openDocument.jsp in place of the
<platformSpecific> parameter.
• For .NET deployments , use opendocument.aspx in place of the
<platformSpecific> parameter.
Note:
Variables are denoted with angle brackets. You must substitute the proper
value for these variables. For example, you must use the name of your
BusinessObjects Enterprise server where OpenDocument is hosted in place
of <servername> and you must use the correct port number in place of
<port> to access the OpenDocument web application.
Viewing Reports and Documents using URLs 9
OpenDocument
1
OpenDocument syntax
URL syntax considerations
Accessing documents
You must include the iDocID or sDocName parameter in your
OpenDocument URL to specify the document to be viewed. Since there may
be multiple documents in the Central Management Server (CMS) with the
same name, and documents can be moved or renamed, it is recommended
that you use iDocID to ensure uniqueness.
Joining parameters
Join parameters with the ampersand (&). Do not place spaces around the
ampersand. For example: sType=wid&sDocName=Sales2003
The ampersand is always required between parameters.
Spaces and special characters in parameter values
Because some browsers cannot interpret spaces, the parameters of the link
cannot contain spaces or other special characters that require URL encoding.
To avoid the misinterpretation of special characters, you can define a
URL-encoded string in the source database to replace the special character
with an escape sequence. This will allow the database to ignore the special
character and correctly interpret the parameter value. Note that certain
RDBMS have functions that allow you to replace one special character with
another.
By creating an escape sequence for the plus sign (+), you can instruct the
database to interpret the plus sign as a space. In this case, a document title
Sales Report for 2003 would be specified in the DocName parameter as:
&sDocName=Sales+Report+for+2003&
This syntax prevents the database from misinterpreting the spaces in the
title.
Trailing spaces in parameter values
Trim trailing spaces at the end of parameter values and prompt names. Do
not replace them with a plus sign (+). The viewer may not know whether to
10 Viewing Reports and Documents using URLs
OpenDocument
Session management
interpret the plus sign (+) as part of the prompt name or as a space. For
example, if the prompt name displays:
Select a City:_
(where _ represents a space), enter the following text in the link:
lsSSelect+a+City:=Paris
where the spaces within the prompt name are replaced with the plus sign,
and the trailing space is trimmed off.
Capitalization
All of the OpenDocument parameters are case sensitive.
URL length limit
OpenDocument may add characters to your URL when it redirects to the
requested document; however, encoded URLs cannot exceed the maximum
character limit for the supported browsers. For example, certain versions of
Internet Explorer limit the URL length to 2083 characters. Therefore, know
the browser character limit to ensure your URL will be within the maximum
limit.
1
Parameter values in links to sub-reports
You cannot pass parameter values to a sub-report of a target Crystal report.
Opening a new window
To force OpenDocument HTML links to open a new browser window, use
the HTML anchor's target attribute or an equivalent. For example:
<a href="http://<servername>:<port>/OpenDocument/open
doc/<platformSpecific>?iDocID=Aa6GrrM79cRAmaOSMGoadKI&sID
Type=CUID" target="_blank">hyperlink text</a>
Session management
Normally when using an OpenDocument link to access password-protected
documents, the user will be prompted for credentials. OpenDocument allows
Viewing Reports and Documents using URLs 11
OpenDocument
1
Session management
Logon tokens
you to pass a logon token directly into the OpenDocument URL. This gives
you control over the duration of the access to the document. OpenDocument
URLs can be set to different languages.
Logon tokens can be used in OpenDocument by inserting the token
parameter into the OpenDocument URL. Logon tokens allow users to access
password-protected files without being prompted for credentials, while also
giving you control on the duration of the access to the file. Creating a new
logon token uses up an additional licence.
Example:
The following example uses the BusinessObjects Enterprise Java SDK to
pass in a logon token to the OpenDocument URL. For more information on
the ILogonTokenMgr.createLogonToken method, see the
BusinessObjects Enterprise Java API Reference.
String openDocumentToken() throws SDKException, Unsup
portedEncodingException
{
IEnterpriseSession sess = CrystalEnterprise.getSession
Mgr().logon ("username", "password", "<cms>:</port>",
"secEnterprise");
String token = sess.getLogonTokenMgr().createLogonTo
ken("",120,100);
String tokenEncode = URLEncoder.encode(token, "UTF-8");
return ("http://<server>:<port>/OpenDocument/open
doc/openDocument.jsp?iDocID=Aa6GrrM79cRAmaOSMGoadKI&sID
Type=CUID&token=" + tokenEncode);
}
Note:
• Replace <server> with the server name and <port> with the port number of
your web server.
• The createLogonToken method allows you to specify the machine that
can use the token (which can be empty to allow any user to use the token),
the number of minutes the token is valid for, and the number of logons that
the token can be used for as parameters.
12 Viewing Reports and Documents using URLs
• Since an OpenDocument URL with a logon token contains the user session,
they must not be shared for security reasons.
User sessions
When OpenDocument is used from InfoView or CMC, it will access the current
user session and the user does not need to enter credentials. When a
document is viewed using an OpenDocument URL, the user will be prompted
for credentials except in the following cases:
• Vintela or Siteminder SSO is configured in the OpenDocument web.xml
file.
• The OpenDocument URL uses a token parameter.
• The OpenDocument application has an existing user session for that
browser session.
If the existing session is different than the session in the token parameter,
the existing session will be closed and a new session will be created. That
is, you can use token parameter to over-ride an existing user session. The
OpenDocument application will look for an existing user session in the Web
application session and in cookies.
OpenDocument
Parameter reference
1
Note:
Only one OpenDocument session can be created from a single browser
session.
If the new token parameter is incorrect and there is an existing user session,
OpenDocument will attempt to open the document using the current user
session. If it can't it will then prompt the user for credentials.
Parameter reference
This section provides details about the available OpenDocument parameters,
their specific uses, and relevant examples.
Note:
The document to which an OpenDocument link points to is referred to as the
target document.
Viewing Reports and Documents using URLs 13
OpenDocument
1
Parameter reference
Table 1-1: Session Management Parameters
DescriptionParameter
token
Table 1-2: Document Identifier Parameters
iDocID
sDocName
sIDType
Specifies a valid logon token for the current
Enterprise session.
DescriptionParameter
Specifies the unique identifier of the viewable
document in the CMS. Use in conjunction with
sIDType.
Specifies the name of the viewable document
in the CMS. Use in conjunction with sPath
and sType.
Specifies the type of object identifier used to
specify the viewable document. Use in conjunction with iDocID.
Specifies the scheduled instance of the target
sInstance
sKind
14 Viewing Reports and Documents using URLs
document to open. Use in conjunction with
sDocName or iDocID.
Specifies the file type of the target Desktop Intelligence document. Use in conjunction with
sDocName and sPath.
sPath
sType
Table 1-3: Input Parameters
lsC
OpenDocument
Parameter reference
DescriptionParameter
Specifies the name of the folder and subfolder
containing the target document. Use in conjunction with sDocName and sType.
Specifies the file type of the target document.
Use in conjunction with sDocName and
sPath.
DescriptionParameter
Specifies a contextual prompt for Web Intelligence documents if there is an ambiguity
during SQL generation.
1
lsM[NAME]
lsR[NAME]
lsS[NAME]
sPartContext
Specifies multiple values for a prompt.
[NAME] is the text of the prompt.
Specifies a range of values for a prompt.
[NAME] is the text of the prompt.
Specifies a value for a single prompt. [NAME]
is the text of the prompt.
Specifies the data context of a Crystal report
part. Use in conjunction with sReportPart.
Viewing Reports and Documents using URLs 15
OpenDocument
1
Parameter reference
sRefresh
sReportMode
DescriptionParameter
Indicates whether a database refresh should
be forced when the target document is
opened.
Indicates whether the link should open the full
target Crystal report or just the report part
specified in.
sReportName
sReportPart
Table 1-4: Output Parameters
NAII
sOutputFormat
sViewer
Specifies the report to open if the target document contains multiple reports.
Specifies the part of the target Crystal report
to open.
DescriptionParameter
Indicates whether to force the display of the
prompt selection page for Web Intelligence
prompts.
Specifies the format in which to open the target document.
Specifies the selected report viewer.
16 Viewing Reports and Documents using URLs
Session management parameters
token
OpenDocument
Parameter reference
ValuesDescriptionSyntax
1
token
Specifies a valid logon token
for the current Enterprise session.
Contains the logon token for the current user. This can be entered into an
OpenDocument URL to allow users to access files without being prompted
for credentials. Creating a new logon token uses up an additional licence.
Example:
The following example uses the BusinessObjects Enterprise Java SDK to
pass in a logon token to the OpenDocument URL. For more information on
the ILogonTokenMgr.createLogonToken method, see the
BusinessObjects Enterprise Java API Reference. You can create logon
tokens in a similar fashion using other BusinessObjects Enterprise SDK
platforms such as .NET and Web Services.
String openDocumentToken() throws SDKException, Unsup
portedEncodingException
{
IEnterpriseSession sess = CrystalEnterprise.getSession
Mgr().logon ("username", "password", "<cms>:<port>",
"secEnterprise");
String token = sess.getLogonTokenMgr().createLogonTo
ken("",120,100);
String tokenEncode = URLEncoder.encode(token, "UTF-8");
The logon token for the current
Enterprise session.
return ("http://<server>:<port>/OpenDocument/open
doc/openDocument.jsp?iDocID=Aa6GrrM79cRAmaOSMGoadKI&sID
Type=CUID&token=" + tokenEncode);
}
Viewing Reports and Documents using URLs 17
OpenDocument
1
Parameter reference
Note:
• Replace <server> with the server name and <port> with the port number
of your web server.
• The createLogonToken method allows you to specify the machine that
can use the token (which can be empty to allow any user to use the token),
the number of minutes the token is valid for, and the number of logons
that the token can be used for as parameters.
• Since an OpenDocument URL with a logon token contains the user
session, they must not be shared for security reasons.
Document identifier parameters
iDocID
ValuesDescriptionSyntax
Specifies the unique identifier
iDocID
You must include the iDocID or sDocName parameter in your
OpenDocument URL to specify the document to be viewed. Since there may
be multiple documents in the CMS with the same name, it is recommended
that you use iDocID to ensure uniqueness.
You can see identifier values for a document within the Central Management
Console (CMC) or InfoView applications. The properties page for each
document contains the document ID and the CUID. You can also obtain the
identifier programmatically using the BusinessObjects Enterprise SDK. For
example, in the Java SDK the com.crystaldecisions.sdk.occa.in
fostore.IInfoObject interface contains getID and getCUID methods
which you can pass to an OpenDocument URL.
18 Viewing Reports and Documents using URLs
of the viewable document in
the CMS. Use in conjunction
with sIDType.
A numerical identifier associated with the document in the
CMS.
sDocName
OpenDocument
Parameter reference
Note:
If you pass in an InfoObject ID rather than a CUID, you do not need to specify
the sIDType parameter. However, InfoObject IDs are changed when
migrating documents from one CMS to another. It is recommended that the
CUID be used, which is preserved during migration.
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?iDocID=2010
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?iDocID=Aa6GrrM79cRAmaOSMGoadKI&sID
Type=CUID
ValuesDescriptionSyntax
1
sDocName
Specifies the name of the
viewable document in the
CMS. Use in conjunction with
sPath and sType.
You must include the iDocID or sDocName parameter in your
OpenDocument URL to specify the document to be viewed. Since there may
be multiple documents in the CMS with the same name, and documents can
be moved or renamed, it is recommended that you use iDocID to ensure
uniqueness.
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?sDocName=Sales+in+2003&sPath=[Sales+Re
ports]&sType=rpt
Viewing Reports and Documents using URLs 19
The title of the document in the
CMS.
OpenDocument
1
Parameter reference
sIDType
ValuesDescriptionSyntax
sIDType
sInstance
Specifies the type of object
identifier used to specify the
viewable document. Use in
conjunction with iDocID.
Note:
If you pass in an InfoObject ID as a value to iDocID rather than a CUID,
you do not need to specify the sIDType parameter. However, InfoObject
IDs are changed when migrating documents from one CMS to another. It is
recommended that the CUID be used, which is preserved during migration.
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?iDocID=Aa6GrrM79cRAmaOSMGoadKI&sID
Type=CUID
• InfoObjectID
• ParentID
• CUID
ValuesDescriptionSyntax
Specifies the scheduled in-
sInstance
20 Viewing Reports and Documents using URLs
stance of the target document
to open. Use in conjunction
with sDocName or iDocID.
•
User (Latest instance
owned by current user)
•
Last (Latest instance of
the document)
•
Param (Latest instance of
the document with matching parameter values)
sKind
sKind
OpenDocument
Parameter reference
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?sDocName=Sales+in+2003&sPath=[Sales+Re
ports]&sType=rpt&sInstance=User
ValuesDescriptionSyntax
Specifies the file type of the
target Desktop Intelligence
document. Use in conjunction
with sDocName and sPath.
• FullClient
1
Note:
Only mandatory if the target is a Desktop Intelligence document. Otherwise,
use sType.
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?sDocName=Sales+in+2001&sPath=[Sales+Re
ports]&sKind=FullClient
Viewing Reports and Documents using URLs 21
OpenDocument
1
Parameter reference
sPath
sPath
ValuesDescriptionSyntax
Specifies the name of the
folder and subfolder containing
the target document. Use in
conjunction with sDocName
and sType.
sPath is used only with subfolders of the Public Folders folder. If your
document is outside of the Public Folders folder, for example in the My
Favorites folder, use the iDocID parameter instead of sPath and
sDocName.
Do not add [Public+Folders] to the path; start with the name of the first
subfolder within Public Folders.
Folder and/or subfolder:
[folder],[subfolder]
Public Folders
folder 1
folder 1.1
folder 1.1.1
If your document were in folder 1.1.1, you would set sPath to: [fold
er+1],[folder+1.1],[folder+1.1.1].
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?sDocName=Sales+in+2003&sPath=[Sales+Re
ports]&sType=rpt
22 Viewing Reports and Documents using URLs
sType
sType
OpenDocument
Parameter reference
ValuesDescriptionSyntax
•
Specifies the file type of the
target document. Use in conjunction with sDocName and
sPath.
Note:
This parameter is ignored for agnostic documents.
Example:
http://<servername>:<port>/OpenDocument/opendoc/<plat
formSpecific>?sDocName=Sales+in+2003&sPath=[Sales+Re
ports]&sType=rpt
wid
•
rpt
•
car
1
Input parameters
lsC
lsC
Specifies a contextual prompt
if there is an ambiguity during
SQL generation.
Note:
Only supported by Web Intelligence documents.
Viewing Reports and Documents using URLs 23
ValuesDescriptionSyntax
A prompt value that resolves
the ambiguity in the SQL generation.
Loading...