8
Starting Discoverer using URL parameters

8.1 Starting Discoverer using URL parameters

This chapter explains how to use Oracle9iAS Discoverer with URL arguments, and contains the following topics:

• Section 8.2, "Why use Discoverer with URL arguments"

• Section 8.3, "What is the URL parameter syntax?"

• Section 8.4, "Examples of using URL parameters"

• Section 8.5, "Generic Discoverer URL arguments"

• Section 8.6, "Discoverer Plus URL arguments"

• Section 8.7, "Discoverer Viewer URL arguments"

8.2 Why use Discoverer with URL arguments

Discoverer end users usually start Oracle9iAS Discoverer by manually choosing a Discoverer connection, opening a workbook, and optionally selecting parameter values. To speed up this process, you can create a URL to start Oracle9iAS Discoverer with specific settings (e.g. which workbook to open, which parameter values to use). For example, you might want to provide a URL to Discoverer end users that automatically logs into Discoverer and opens a particular workbook.

Using a URL to automatically start Discoverer saves your end users time by enabling them to quickly log in and run queries. You can also embed URL links in a Web page, which enables Web users to link to Discoverer workbooks.

Having created a URL that meets your requirements, you can:

• give the URL to end users to enter in their Web browser address box

• add the URL as a link to your organization's Intranet site so that end users can start Discoverer with a single click

8.3 What is the URL parameter syntax?

URL parameters must conform to the following syntax:

http://hostname.domain[port number]/application name?arg1=value1...&argN=valueN

where:

• hostname.domain is machinename.myorganization is the hostname and domain on which the Oracle HTTP Server is installed

• port number is the port number on which the Oracle HTTP Server is installed if the default port number (i.e. port 80) has been changed

• application name is one of the following (depending on whether you want to start Discoverer Plus or Discoverer Viewer):
  • discoverer/plus

  • discoverer/viewer

• ? - the question mark tells Discoverer that the remaining text contains URL parameters

• arg1=value1 is the first argument and the value specified for it. Note that subsequent URL parameters are prefixed with an ampersand character (&)

Notes:

• URL parameters are not case-sensitive. For example, 'Locale=' is the same as 'locale='.

• URL parameter values are case-sensitive. For example, 'workbooksource=Database' is not the same as 'workbooksource=DataBase'.

• The order of the URL arguments is not important.

• If the following mandatory arguments are not specified on the URL, end users are prompted for them:
  • username

  • password

  • database

  • workbook name

  • worksheet name

  • parameters

• Where names contain spaces, concatenate the words with a plus symbol (+). For example, if a workbook is called 'January Analysis 2003', the URL parameter is &wb=January+Analysis+2003

• To include other special characters in a URL, you must replace those characters with the equivalent ASCII (or in some cases UNICODE) codes. This process is known as URL encoding. For example, to replace a vertical bar ('|') you replace it with ~7c. Any characters not in the following lists must be URL encoded:
  • capital letters (i.e. A B C D E F G H I J K L M N O P Q R S T U V W X Y Z)

  • lower case letters (i.e. a b c d e f g h i j k l m n o p q r s t u v w x y z)

  • numerals (i.e. 0 1 2 3 4 5 6 7 8 9)

  • certain special characters (e.g. _ ! ~ ( ) * ' )

  For more information about URL encoding, refer to any standard HTML guide.

• The maximum number of characters you can put in a URL depends on which Internet browser you are using, as follows:
  • Internet Explorer 4 and later - 2048 characters

  • Netscape Navigator 4 and later - no known limit.

    Note: The Apache Web server has a limit of 8192 characters.

8.4 Examples of using URL parameters

This section contains examples of using URL parameters with Discoverer.

8.4.1 Example 1: To start Discoverer Viewer using URL parameters

To start Discoverer Viewer, connect automatically as jchan, and open a worksheet called 'January Analysis' in a workbook called 'Monthly Analysis', you might use the following URL:

http://hostname.domain/discoverer/viewer?us=jchan&pw=3829382&db=sales&wb=Monthly+Analysis&ws=January+Analysis

8.4.2 Example 2: To start Discoverer Plus using URL parameters

To start Discoverer Plus, connect automatically as jchan to the 'Sales' End User Layer, open a worksheet called 'January Analysis' in a workbook called 'Monthly Analysis', and enter the parameter value 'East', you might use the following URL:

http://hostname.domain/discoverer/plus ?us=jchan&pw=3829382&db=sales& eul=Sales&wb=Monthly+Analysis&ws=January+Analysis&param_regionparam=East

8.4.3 Example 3: To start Discoverer without exposing a password in the URL

You might want to end users to start Discoverer without being able to see the password in the URL that you supply. Typically, you would do this using a public connection.

To start Discoverer without exposing a password in the URL:

1. Find out what is the connection key of the public connection:
   1. Start a Web browser.

   2. Navigate to the Discoverer Connections page that contains the connection for which you want to look at the connection key.

   3. Select the Show XML link at the bottom of the Discoverer Connections page.

      You will see a list of XML tags, including tags for each Discoverer connection in the connections list.

   4. Locate the connection for which you want to look at the connection key.

   5. Identify the value of the connection's key tag.

      For example, you might see key="cf_m2". In this example, the key is cf_m2.

2. Create a URL using the following as an example:

   http://myserver.com/discoverer/viewer/viewer?cn=<connection key>

   Where <connection key> is the connection key that you looked at in the previous step (for more information about connection keys, see the cn= parameter in Section 8.5, "Generic Discoverer URL arguments").

Notes:

• You can create public connections using Oracle9iAS Configuration Manager (for more information about creating public connections, see Oracle9iAS Discoverer Administrator Administrator's Guide).

8.5 Generic Discoverer URL arguments

This table defines generic URL parameters that can be used with Discoverer Plus and Discoverer Viewer.

Argument and Values	Description	Example
con_name=<connection_name>	Specifies the name for the connection being added / updated. Can be blank.	con_name=Weekly+Report
con_desc=<connection_description>	Specifies a description for the connection being added / updated. Can be blank.	con_desc=Weekly+performance+reports+by+region
con_db=<database>	Specifies the database the connection being added / updated should connect to.	con_db=Sales
con_us=<username>	Specifies the database username the connection being added / updated should use when connecting to the database.	con_us=jchan
con_pw=<password>	Specifies the database password the connection being added / updated should use when connecting to the database.	con_pw=382939382
con_eul=<eul>	Specifies the EUL the connection being added / updated should open once connected to the database.	con_eul=VIDEO
con_lm=<discoverer or applications>	Specifies the login method that should be used when connecting to the database. Can be either "discoverer" or "applications".	con_lm=discoverer
con_rs=<responsibility>	Specifies the Applications Responsibility the connection being added / updated should open once connected to the database. (Only valid with Applications logins).	con_rs=Power+User
con_sg=<security_group>	Specifies the Applications Security Group the connection being added / updated should open once connected to the database. (Only valid with Applications logins).	con_sg=Marketing
con_nlsl=<locale>	Specifies the default locale that should be associated with the connection being added / updated.	con_nlsl=es_ES The language is Spanish, the country is Spain.
condel=<connection_key>	Deletes the connection specified by <connection_key>. For more information about connection keys, see "Notes:" section below).	condel=cf_m2
con_key=<connection_key>	Specifies a connection to update. For more information about connection keys, see "Notes:" section below).	con_key=cf_m2
cn=<connection_key>	Specifies a connection to open (for more information, see "Notes:").	cn=cf_m2
newpw1=<new password>	Specifies the password you want to change your database password to. Note: Associated connections will be updated accordingly if the change-password operation is successful. You identify which database account you want to change password on using either a "cn" or "con_key" URL parameter.	newpw1=3837282
newpw2=<new password>	Re-specifies the password you want to change your database password to.This password must match that given with newpw1 before the change password operation will be attempted.	newpw2=25363523

Notes:

• Connection keys are unique codes that are used to identify Discoverer connections. Connection keys are generated automatically by Discoverer. To find out what a Discoverer connection's key is:
  1. Start a Web browser.

  2. Navigate to the Discoverer Connections page that contains the connection for which you want to look at the connection key.

  3. Select the Show XML link at the bottom of the Discoverer Connections page.

     You will see a list of XML tags, including tags for each Discoverer connection in the connections list.

     Note: If the Show XML link is not visible, contact the Discoverer administrator or Discoverer Services manager.

  4. Locate the connection for which you want to look at the connection key.

  5. To see the connection key, look at the key tag value.

     For example, a connection entry might have key="cf_m2".

8.6 Discoverer Plus URL arguments

This table defines URL parameters that can be used with Discoverer Plus.

Argument and Values	Description	Example
connect=[APPS_SECURE] <hostname_instancename>	For Oracle Applications end users, you can specify that they connect in secure mode. hostname_instancename refers to the database host name and the instance of the Applications server.	connect=[APPS_SECURE]genledger_ payables
connect=<connection string>	Specify login details with which to connect to Discoverer using the connection details supplied. This argument bypasses the Connection Information dialog for end users.	connect=username/password@ demodb or connect=username/password@ ODBC:demodb for ODBC connections.
database=<database name or alias>	Specify a database to which to connect when Discoverer starts. You can also use the connect= argument to specify a database, username, and password as a single argument.	database=demodb or database=ODBC:demodb for ODBC connections.
framedisplaystyle=<separate>	Specifies that Discoverer's main window is launched as a separate frame from the browser (i.e. from the Discoverer Connections list). The browser window contains a Discoverer image and must remain open while Discoverer is being used. Note: To deploy Discoverer Plus in conjunction with a screen-reader (e.g. JAWS), set the value to 'separate'. For more information about accessibility and Discoverer, see Using the JAWS screen reader with Discoverer).	framedisplaystyle=separate
lookandfeelname=system or oracle or browser	Specifies a browser look-and-feel. For example, a user might need to be able to run Discoverer Plus using the Windows look-and-feel	lookandfeelname=system
password=<string>	Specify a database password to authenticate the username used to connect to Discoverer. You can also use the connect= argument to specify a database, username, and password as a single argument.	password=37282732
username=<database username>	Specify a database username with which to connect to Discoverer. You can also use the connect= argument to specify a database, username, and password as a single argument.	username=video_user
eul=<schema name>	Specifies the name of the database schema which contains the EUL that you want your end users to connect to by default. If you do not use this argument, Discoverer uses other methods to detect the default EUL (for example, from the end user's preference settings.) Note: EUL names are case-sensitive.	eul=VIDEOEUL Discoverer uses the EUL metadata that is found in the VIDEOEUL schema.
locale=<language[_country][_variant]>	Specifies the language (and optionally the country and variant) that end users see when they use Discoverer. This argument overrides the locale setting of the end user's client machine. Use Java naming conventions to specify language, country, and variant.	locale=es_ES The language is Spanish, the country is Spain.
nlsdateformat=<date format>	Formats dates for a specific region. For its value, type a SQL date format mask, such as DD-Mon-YY.	nlsdateformat=DD-Mon-YY
nlsdatelanguage=<date language>	Selects the language for day and month names that end users see when they use Discoverer.	nlsdatelanguage=Spanish
nlslang=<language>	Selects the language, territory, and character set end users see when they use Discoverer. Use Oracle naming conventions to specify language, territory, and character set.	nlslang=Spanish
nlsnumeric_characters= <separator characters>	Selects decimal character and group separator for numbers.	nlsnumeric_characters=.,
nlssort=<sort type>	Specifies a character sort sequence. For more information about the nlssort command, see Oracle9i Globalization Support Guide.	nlssort=XSpanish
opendb=<workbook name>	Gives Discoverer the name of the workbook you want to open and assumes that it is stored in the database (instead of scheduled). If you use the opendb argument more than once in the URL, Discoverer uses the last one. This command is included for backward compatibility. Note: 'opendb=Video+Sales+Workbook' is the equivalent of 'workbookname=Video+Sales+Workbook&workbooksource=Database'. See also workbookname and workbooksource.	opendb=Video+Sales+Workbook Discoverer assumes the workbook is stored in the database and automatically opens it.
opendbid=<unique ID>	Use opendbid= as an alternative to opendb=, to specify the unique ID of the workbook you want to open. For more information about how to find the unique ID of a workbook, see "Notes:"	opendbid=JanuarySales
param_<parameter_name>= <parameter_value>	For workbooks that contain parameters, use this argument to select values. If the workbook does not contain a parameter by that name, Discoverer ignores the argument. Note that param_ must precede the parameter's name.	param_regionparam=East Tells Discoverer to set the parameter named regionparam to the value East.
responsibility= <responsibility name>	For Oracle Applications end users (e.g. Oracle General Ledger), you can specify their responsibility.	responsibility=Manager Discoverer bypasses the Responsibility dialog and assigns the end user an Oracle Applications responsibility of Manager.
sheet=<worksheetname>	Gives Discoverer the name of the worksheet you want to open by default. If you use the Sheet argument more than once in the URL, Discoverer opens the last one.	sheet=Sales+Detail+Sheet Discoverer runs the query for the worksheet named Sales Detail Sheet and displays the results to the end user.
sheetid=<unique ID>	Specifies the unique identifier of the worksheet that you want to open.	sheetid=Lag&LeadAnalysis
windowheight=<pixel width>	Specifies the height in pixels of the Discoverer application frame. If you do not use this argument, Discoverer uses its own default value.	windowheight=600 The Discoverer frame is 600 pixels high.
windowwidth=<pixel width>	Specifies the width in pixels of the Discoverer application frame. If you do not use this argument, Discoverer uses its own default value.	windowwidth=800 The Discoverer frame is 800 pixels wide.
workbookname= <workbookname>	Specifies the name of the Discoverer workbook you want users to open by default. Note: Use this command in conjunction with workbooksource. E.g. 'workbookname=Video+Sales+Workbook&workbooksource=Database' is the equivalent of 'opendb=Video+Sales+Workbook'. See also opendb.	workbookname=Video+Sales+Workbook Discoverer starts and opens a workbook called Video Sales Workbook.
workbooksource=<Databaseor Scheduled>	Specifies the location of the workbook to open: The value 'Database' specifies that the workbook is saved in the database. The value 'Scheduled' specifies that the workbook is a scheduled workbook that is updated periodically.	workbooksource=Database

Notes:

• To find out the unique ID of a workbook in Discoverer Viewer, look at the key XML tag:
  1. Start a Web browser.

  2. Run Discoverer Viewer and open the workbook.

  3. Select the Show XML link at the bottom of the Discoverer Connections page.

     You will see a list of XML tags, including tags for each Discoverer connection in the connections list.

     Note: If the Show XML link is not visible, contact the Discoverer administrator or Discoverer Services manager.

  4. To see the workbook's unique ID, look at the value of the key tag value.

     For example, a workbook entry might have key="wb_02".

• To find out the unique ID of a workbook in Discoverer Plus, look at the workbook properties tab:
  1. Start a Web browser.

  2. Run Discoverer Plus and open the workbook.

  3. Choose File | Manage Workbooks | Properties to display the Workbook Properties dialog.

  4. Look at the Workbook Identifier to find out the unique workbook ID.
     

8.7 Discoverer Viewer URL arguments

This table defines URL parameters that can be used with Discoverer Viewer.

Argument and Values	Description	Example
anlsdf=<date format>	For Oracle Applications end users, you can override the default date format for the session.	anlsdf='MM/DD/YY'
anlsdl=<date language>	For Oracle Applications end users, you can override the language to use for the spelling of day and month names and date abbreviations (AM, PM, AD, BC).	anlsdl=fr
anlsl=<language>	For Oracle Applications end users, you can override the session language	anlsl=en-gb
anlsnc=<separator characters>	For Oracle Applications end users, you can override the default characters to use as the group separator and decimal. You must specify the decimal separator first, followed by the group separator.	anlsnc=',.'
anlss=<sortname or binary>	For Oracle Applications end users, you can override the session collating sequence for ORDER BY queries and string comparisons. Values are: the name of a linguistic sort sequence binary to specify a binary sort	anlss=binary
aow=<true or false>	(Auto Open Worksheet) - Specifies whether to open the default worksheet when opening a workbook (the value can be true or false). Note: You can also use the ws= and wsk= parameters to specify which worksheet to open.	aow=true
arq=<true or false>	(Auto Run Query) - Specifies whether to automatically run a worksheet's query when a worksheet is opened (the value can be true or false).	arq=true
cp_height=<number_of_pixels>	Specifies height of chart in pixels.	cp_height=200
cp_show_legend=<true or false>	Specifies whether a chart title is displayed.	cp_show_legend=true
cp_width=<number_of_pixels>	Specifies width of chart in pixels.	cp_width=300
cs=[APPS_SECURE] <hostname_instancename>	For Oracle Applications end users, you can specify that they connect in secure mode. hostname_instancename refers to the database host name and the instance of the Applications server.	cs=[APPS_SECURE]genledger_ payables
db=<databasename>	Specifies the database to connect to	db=video
eul=<eulname>	Specifies the name of the EUL to connect as. You only need to specify this parameter if you want to override the default EUL. Note: EUL names are case-sensitive.	eul=myEUL
fm=<exportformat>	Specifies one of the following export formats: xml xls (Microsoft Excel) htm (HTML) txt (Text) csv (Comma Separated Values) prn (Formatted Text) dcs (Express) dif (Data Interchange Format) slk (Symbolic Link) wks (Lotus 1-2-3) sql (Structured Query Language) Note: You must run a query before you can use this parameter to export the data.	fm=xls
lm=<applications or discoverer>	Specifies the login method: Set to "applications" to login in as an Oracle Applications user. Set to "discoverer" to login in as a Discoverer user. If this parameter is not present, the default login method (as specified in the ui_config.xml configuration file) is used.	lm=applications
nlsl=<language>	Specifies the language code for the language you want.	nlsl=en-gb
pg=<page_number>	Specifies the page of the worksheet to view.	pg=4
pi_<pageitemname>=<pageitemvalue>	Specifies the name of a page item and the value to set it to.	pi_Region=West The above sets the "Region" page item to "West":
pw=<password>	Specifies the password corresponding to the specified user name for connecting to the specified database	pw=tiger
qp_<parameter_name>=<parameter_value>	Specifies the name of a query parameter and the value you want to set it to.	qp_City=Denver
qpd=<number_of_ seconds>	Specifies the delay in seconds before a query progress page is displayed (or re-displayed). You might use this argument to avoid writing code to handle query progress pages when using the Discoverer Servlet to return data to an application you have written. Note: You can use this parameter to improve accessibility if you use a JAWS screen reader (for more information, see Using the JAWS screen reader with Discoverer). Note: You can also set this value on a global basis (i.e.in the middle tier) using the query_progress_delay parameter (for more information, see Section A.4, "List of configuration settings in configuration.xml").	qpd=60 The above specifies that a query progress page is to be displayed after the query has been running for 60 seconds. The query progress page will be re-displayed every 60 seconds until the query results are available.
rd=<number_of_ seconds>	Specifies the delay in seconds before a browser is redirected to the original URL. Use this argument to prevent the browser timing out during export operations. Note that this argument only applies when a valid value has also been specified for the fm argument.	rd=90 The above specifies that the browser is redirected back to the original URL every 90 seconds until the export operation is complete.
rs=<responsibility>	Specifies the Oracle Applications Responsibility you want to connect with.	Rs=Manager
sg=<securitygroup>	Specifies the Oracle Applications Security Group you want to connect with.	Sg=securityGroup
tsc_d!<index>=<direction>	Specifies the sort direction for the item identified by <index>. <direction> can be either "lh" (low to high) or "hl" (high to low).	tsc_d!namesindex=lh
tsc_g!<index>=<type>	Specifies whether the sort applied to the item identified by <index> is a group sort or a normal sort.<type> can be either 'normal' or 'group'. Note: For more information about group sort, see Oracle9iAS Discoverer Plus User's Guide.	tsc_g!namesindex=normal
tsc_h!<index>=<true or false>	Specifies whether the item identified by <index> is hidden (not visible on the worksheet) or not. <hidden> can be either "true" (hidden) or "false" visible.	tsc_h!namesindex=true
tsc_i!<index>=<item_key>	Specifies an item to be sorted. <index> refers to the order sorts that should be applied. An <index> of "0" will be applied first followed by the item with <index> of "1" and so on.	tsc_i!namesindex=0
tss_s!<index>=<direction>,<type>,<hidden>,<item_key>	Defines a sort on an item using a single URL parameter combining any of the tsc_d!, tsc_g!, tsc_h!, or tsc_i! parameters.	tss_s!namesindex=lh,normal,true,0
us=<connectString>	Specifies the username and database plus further optional connection information. The connect string uses the following syntax: <username>[:<responsibility> [:<securityGroup>]][/<password>] @<database>	us=scott/tiger@disco
us=<username>	Specifies the user name that you want to use.	us=video5
wb=<workbookname>	Specifies the name (or ID) of the workbook that you want to open.	wb=My+Workbook
wbd=<workbookdate>	When opening a scheduled workbook, this parameter specifies the date that the scheduled workbook was run.	wbd=31-OCT-00
wbk=<unique ID>	Specifies the unique identifier of the workbook that you want to open.	wbk=JanuarySales
wbr=<unique ID>	If you the workbook that you specify with the wbk= parameter is for a scheduled workbook, you must specify the unique run identifier of the workbook using wbr=.	wbr=SWB001
wbt=<workbooktime>	When opening a scheduled workbook, the parameter specifies the time that the scheduled workbook was run. If you specified the Scheduled Workbook's ID using the wb parameter, you don't need to use this parameter	wbt=4%3a00+PM The above specifies a time of 4:00 PM.
ws=<worksheetname>	Specifies the worksheet that you want to open.	ws=My+Worksheet
wsk=<unique ID>	Specifies the unique identifier of the worksheet that you want to open.	wsk=Lag&LeadAnalysis