Report URL Parameters
The i-net Clear Reports report engine executes report templates designed with the report designer and returns the executed report in the format requested by the user (e.g. PDF, RTF, XLSX or as preview in the HTML or Java report viewer). The client can request a report by passing the report URL to i-net Clear Reports.
The following parameters can be appended to the report URL on the client or can be changed on the server side in the method com.inet.report.PropertiesChecker.checkProperties(...)
. These parameters will be passed to the engine of i-net Clear Reports.
The following parameters are passed to the HTML page and the Java report viewer reads them and passes them on to the report engine. In the report engine the parameters are finally stored in the engine.UserProperties object. These parameters pass the following checkpoints where they can be modified:
com.inet.report.PropertiesChecker.checkHtmlPageProperties(java.util.Properties) com.inet.report.PropertiesChecker.checkProperties(java.util.Properties, java.lang.Object) com.inet.report.PropertiesChecker.checkProperties(com.inet.report.Engine, java.util.Properties, java.lang.Object)
For security reasons, only some parameters are allowed by default in the report URL. To use other parameters in the report URL, like "datasource", it is necessary to unlock them in the Configuration Manager.
It is always possible to set values for all parameters in the checkProperties method on the server side.
Since Version: | 7.0 |
---|---|
API Method: | Datasource.setup(String) |
Allowed by Default: | No |
Set the name of the data source configuration that will be used to create a connection to the database instead of the data source contained in the rpt file.
A Data Source Configuration contains all information needed to create a database connection.
You need to set a value for this parameter only if you like to use another data source configuration as saved in the *.rpt file.
Since Version: | 7.0 |
---|---|
API Method: | Datasource.setup(String) |
Allowed by Default: | No |
Like the datasource parameter but with multiple sources:
You can use this parameter with an index to overwrite a single datasource in a report with several datasources in the mainreport or in the subreports. For example, the parameter datasource0 specifies the datasource that will be used as first datasource in the main report. The following parameters datasource1, datasource2, etc. will be used in the first sub report or in the mainreport, if it has more than one datasource.
Since Version: | x |
---|---|
API Method: | Datasource.setPassword |
Allowed by Default: | No |
Specifies the password for logging on to password protected databases used by the report and all of his sub reports. Use this parameter instead of password# if you use the same password for the main report and all sub reports.The password parameter for the users you only need to set if the password is not empty. You don't need to set an empty password like ...&password0=.
Since Version: | x |
---|---|
API Method: | Datasource.setPassword |
Allowed by Default: | No |
Specifies one or more passwords for logging on to SQL, ODBC, or password protected databases used by the report, e.g.: user0=scott&password0=wood&user1=steven&password1=car.
Since Version: | x |
---|---|
API Method: | Engine.setPrompt |
Allowed by Default: | Yes |
Syntax: | prompt<Name>=<Value> |
Specifies the value for the parameter field (prompt) with the specified name. (API: com.inet.report.Engine.setPrompt(java.lang.String, int)
)
Parameter field values are assigned by name to the parameter fields. For example:
You can set the value for the parameter field "Field1" with: ...&promptField1=test.
Since Version: | x |
---|---|
API Method: | Engine.setPrompt |
Allowed by Default: | Yes |
Syntax: | prompt<Number>=<Value> |
Specifies the values for parameter fields in the report. (API: com.inet.report.Engine.setPrompt(java.lang.String, int)
)
Parameter field values are assigned to parameter fields in the order the parameter fields exist in the report. For example: prompt0=car&prompt1=drive. To pass multiple parameters, you need to use the syntax prompt#=[val1, val2, ...]
. For example: prompt0=['Audi', 'Chrysler']
.
In the following example prompt0 is a Date prompt, prompt1 is of type array of DateTime, prompt4 is an integer and prompt5 a string.
prompt0=Date(2001,01,01)&prompt1=[DateTime(2001,01,01),DateTime(2001,01,01)]&prompt2=42&prompt3='42'
Since Version: | 8.0 |
---|---|
API Method: | Engine.setPrompt |
Allowed by Default: | Yes |
Syntax: | prompt#<subreportID>#<Name>=<Value> |
Specifies the value for the parameter field (prompt) with the specified name in the subreport with the index given. Parameter field values are assigned by name to the parameter fields.
The special characters need to be encoded in the report URL. For the character '#' you need to use %23 and for the character '@' (included in the parameter field name if it is a stored procedure parameter) you need to use %40.
For example:
You can set the value for the parameter field "Field1" in the first subreport and "Field2" in the third subreport with: ...&prompt#1#Field1=1234&prompt#3#Field2=5678
The encoded report URL: ...&prompt%231%23Field1=1234&prompt%233%23Field2=5678
You can see the order of the subreports in the parameter field request dialog.
Since Version: | x |
---|---|
API Method: | Engine.setSF |
Allowed by Default: | No |
Specifies the Record selection formula. (API: com.inet.report.Engine.setSF(java.lang.String)
)
Please note: If you want to use a database field in the new record selection formula that was not part of the the report at design time or that was not used in the record selection formula specified at design time, then you have to add it into your report design.
Since Version: | x |
---|---|
API Method: | Engine.setGF |
Allowed by Default: | No |
Specifies the Group selection formula.
Since Version: | 15.0 |
---|---|
API Method: | EngineBundle.addReportFile |
Specifies a list of multiple reports you want to render as one, separated by semi-colon.
The following features are not supported with the reports parameter:
-
"Page N of M"
-
Interactive sorting
-
Subreport on Demand
-
DrillDown
-
Output formats: Java, XLS, ODS
-
Report URL parameters: sf, gf, datasource, password, prompt# (use promptName)
Since Version: | 2.0 |
---|---|
API Method: | new Engine(String) |
Allowed by Default: | Yes |
Specifies the output format in which the executed report will be returned to the client and how the report should be displayed in the browser, e.g.: init=pdf. If the Plug-In is not installed or not available then it is possible to save the exported report on the disk.
You can find a list of supported export formats in the documentation.
Alternatively you can also use report file extension. For example report.pdf is equals report.rpt&init=pdf. Report file extensions are valid for all formats without XML and DATA. Report file extensions can be used with the report URL. They can not be used with the API.
Please note that it is not possible to change or add this parameter in one of the checkProperties() callbacks. This parameter must be set before any of the callbacks is run, for example in the servlet service() method or in the method afterPropertiesStoredHook (see sample: MyReportServlet_setExportFormat.java).
Since Version: | 9.2 |
---|---|
API Method: | Engine.setUserProperties |
Specifies the filename that is used for the exported file. If the provided filename has no extension, the default extension of the chosen export format is appended.
This gives the browser a hint for the SaveAs dialog. This only affects the HTTP Content Disposition header.
Since Version: | 11.0 |
---|---|
API Method: | Engine.setUserProperties |
Specifies if browser will show SaveAs dialog or open the exported file inline, if a plugin is available (e.g. PDF) or the browser can display it directly (e.g. TXT). Possible values:
-
inline (Default): Browser will open the exported file inline, if possible. If it is not possible then it will show SaveAs dialog.
-
attachment: Browser will show SaveAs dialog, also if a browser plugin exists for the file type.
Since Version: | 5.2 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | HTML |
Specifies the format of the HTML file created if export us used.
If this property is used then the report will be exported in one HTML file.
This property sets the layout of the created HTML page. The following values are possible:
-
single: one Page Header and Page Footer per report
-
concat: one Page Header and Page Footer per report page.
If this property is not used (default) then one HTML file will be created for each report page.
Since Version: | 5.2 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | CSV & Data |
Specifies the delimiter that separates the fields.
If the property is not used then a comma will be used (default). If you use "...&delimiter=" in the report URL then a white space will be used and if you use "...&delimiter=%09" then a tab will be used as delimiter.
Since Version: | 5.2 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | CSV & Data |
Specifies the character that will be used as text qualifier.
If the property is not used then a quotation mark will be used (default). If you use ""echar=&" in the report URL no text qualifier will be used.
Since Version: | 8.1 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Data |
Specifies if the exported CSV file contains column names in the first row.
The default value is: true.
Since Version: | 3.3 |
---|---|
API Method: | Engine.stopAfterPage |
Allowed by Default: No
Specifies the upper bound for the number of pages to be rendered. If your report has n pages and you set stopAfter=100 then only MIN(100, n) pages will be rendered.
* In the server configuration you can switch the usage of this parameter On or Off
* Additionally a default value for stopAfterPage can be set in the server configuration (Configuration Manager –> Performance –> Report –> Stop After Page). Note that this Report URL Parameter will override the server default value.
Since Version: | 2.02 |
---|---|
API Method: | Engine.setClientLocale |
Specifies the Locale (language) that will be used for language independent reports. By default the locale from the server is used. This parameter requires that on server side the option "Use Client Locale” is set to true. Than by default the report is rendered with the locale from the client (HTTP header) unless you set this locale parameter specifically.
The formatting of system values (no user defined formats) of the report will be done automatically. The translation can either be done by global ResourceBundles or directly within the report. If a report is requested with a locale that is not supported the default locale of the report will be used.
Locale definitions:
locale = Language_Country # e.g. locale=de_DE # locale=en_US
Please note: The locale will not be used for the value of the currency. The currency value defined in the i-net Clear Reports will be used. Only the labels for currency values might be translated. E.g. 10€ to 10EUR
Since Version: | 10.0 |
---|---|
API Method: | Engine.setUserProperties |
Specifies the timezone of the client that will be used to format date and time values in the report. The formatting depends on the language and is used only for display, not for grouping. It is necessary to pass the timezone using this URL parameter for all output formats, expecting the Java report viewer.
Since Version: | 6.0 (txt) 12.1 (csv) |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Plain Text, CSV and Data |
Specifies the characters used for line breaks in txt or csv file. The default value is the server default value. If you set it in the URL then it must be encoded. For example for Windows newline=%0D%0A
Since Version: | 6.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Plain Text |
Specifies the page delimiter for plain text format. The default is a line of '='. If the last character is not a control character (lesser as white space) then a new line was added.
Since Version: | 6.0 (txt) 9.1 (csv) |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Plain Text, CSV, Data |
Specifies the encoding for the txt or csv file. The default value is the server default encoding.
Since Version: | 9.2 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | CSV, Data |
Specifies a comma separated list of fixed column widths, e.g. 3,5,5 or 5,5,,4. The following default values will be used for columns without specified width:
-
String: 8 characters
-
Number: 10 characters
-
Currency: 11 characters
-
Boolean: 6 characters
-
Date: 11 characters
-
Time: 9 characters
-
DateTime: 21 characters
If this parameter is specified the exported csv file will not contain column delimiters and text qualifier.
Since Version: | 9.1 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Excel |
Determines how to distribute text to Excel cells if the text does not fit a simple cell. The default value can be changed for a specific report during the export. For details about cell distribution check out the export documentation
The following values are possible:
-
staticlayout
-
oneline
-
linebreak
-
multicells
-
mergecells
-
fullmerge
-
singlecell
Since Version: | 7.6 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Excel |
Specifies whether strings which are too long for their cell will be truncated or not.
The default value is: true.
Since Version: | 7.6 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Excel |
Specifies whether a new sheet will be created for every instance of the top-most group or not.
The default value is: false.
Since Version: | 7.6 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | Excel |
Specifies how many group levels are to be shown in the outline of the excel sheet.
A number between 0 and 7 is valid. The default value is: 0.
Since Version: | 7.6 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: |
Specifies the panel that will be displayed in the navigation panel of the PDF viewer.
Valid values are "bookmarks" and "pages".
Since Version: | 9.2 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: |
Specifies if the PDF file will be created according to the PDF/A-1b standard. PDF/A standard does not support Fast Web View and encrypted PDF files.
The default value is: false.
Since Version: | 13.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: |
Specifies if Fast Web View will be enabled for the created PDF file. Fast Web View is not supported in PDF/A standard and encrypted PDF files.
The default value is: false.
Since Version: | 13.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: |
Specifies whether PDF tags should be added to the created PDF file to make them useable for screenreaders. Examples for PDF tags are PDF alternative text for images or other commands integrated into the PDF file. This overrides the default value of report server that is set in the configuration.
The default value is: server default.
Since Version: | 11.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: |
If the user and/or owner password is specified, the created PDF file will be encrypted with the symmetric AES algorithm (128 or 256 bit). With the user password it is possible to open and read the PDF file and with the owner password it is possible to open the PDF file, read it and change it's properties. PDF file encryption is not supported in PDF/A standard and with Fast Web View.
To encrypt the PDF file it is necessary to specify at least one of these passwords.
-
AES algorithm with 128 bit (default) - This algorithm is supported since Adobe Reader version 7. The passwords can consist of latin and some additional characters, like TM and €.
-
AES algorithm with 256 bit - This algorithm is supported since Adobe Reader version 9. The passwords can consist of (almost) any Unicode characters. Not allowed are control-, private-use-, non-character-, surrogate-, change-display-properties- und tagging-characters. The password should not contain characters with left to rigth direction and rigth to left direction.
To use this algorithm instead of the default algorithm with 128bit, it is necessary to download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6" from the URL: http://www.oracle.com/technetwork/java/javase/downloads/index.html. The files local_policy.jar' and
Us_export_policy.jar' in the directory runtime\lib\security
of the used Java VM need to be replaced with the downloaded files.
Example report URL: http://localhost:9000/?report=...rpt&upass=abcd&opass=xyz&init=pdf
Since Version: | 14.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | RTF |
This parameter specifies whether an editable RTF file will be created. A non-editable RTF file contains frames for text positioning.
Since Version: | 9.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | PNG, JPG, GIF and BMP |
Specifies the size of the image. You can only set one of it. zoom can be set in percent or as floating point number. width and height are set in pixel.
Since Version: | 9.0 |
---|---|
API Method: | Engine.setUserProperties |
Valid for Format: | PNG, JPG, GIF and BMP |
Specifies the color of transparent parts of the image. The color is in ABGR format and can be set as decimal or hexdump number. For example 255 or 0xFF are red.
Since Version 14.1 the parameter accepts an RGB hex value as well, e.g. #123456
. Please note: you have to encode the parameter properly.
Since Version: | x |
---|---|
API Method: | Engine.getPage |
Valid for Format: | PNG, JPG, GIF, BMP and HTML |
Specifies the number of the requested page. This is only valid for export formats that have a separate file for every page like images or HTML.
Applet Parameters
Additionally you can pass applet parameters in the URL string. These parameters are used by the i-net Clear Reports - Java Viewer. Note that these parameters are not stored into the user properties object in the report engine. Instead these parameters are only used when creating the HTML page for the i-net Clear Reports - Java Viewer and can only be modified in the com.inet.report.ReportServlet.checkHtmlPageProperties(java.util.Properties)
callback.
Note: If you create your own HTML pages containing the code for an applet using the Java Viewer, don't set the applet parameters as URL parameters for the report name.
Since Version: | x |
---|
Title of HTML page that contains the Java Viewer applet. The default value is "i-net Clear Reports Java Client".
Since Version: | x |
---|
Background color of the HTML page that contains the Java report viewer applet. The default value is: "C6C6C6" (light gray).
Since Version: | x |
---|
Which applet code should be used? The default value is com.inet.viewer.ViewerApplet
.
Since Version: | x |
---|
Location from that the archive file CC-Viewer.jar will be loaded. The default value is: "http://<hostname>:<port>/core
" for the ReportSocket and "http://<hostname:<port>/<servlet-context>/core
" for a servlet engine.
Since Version: | 5.3 |
---|
Enable/Disable the status bar of the Java report viewer (default "true").
Since Version: | 5.3 |
---|
Enable/Disable the toolbar of the Java report viewer (default "true").
Since Version: | x |
---|
Enable/Disable the export button of the Java report viewer (default "true").
Since Version: | x |
---|
Enable/Disable the refresh button of the Java report viewer (default "true").
Since Version: | x |
---|
Enable/Disable the print button of the Java report viewer (default "true").
Since Version: | x |
---|
Enable/Disable the search text field and button of the Java report viewer (default "true").
Since Version: | 5.3 |
---|
Enable/Disable the zoom drop down box of the Java report viewer (default "true").
Since Version: | x |
---|
Enable/Disable the group tree in the Java/HTML report viewer (default "true").
Note: Make sure that the server side option "Has Group Tree" in Configuration Manager is set to "true" if you would like to show group trees in general.
Since Version: | 18 |
---|
Expand/Collapse the group tree entries the HTML report viewer (default "false").
Since Version: | 15 |
---|
Enable/Disable the permanent link in the export menu of the HTML Viewer
Since Version: | x |
---|
Defines if a prompt dialog should be opened with a click on the Reload Button within the Viewer. If set to "0" or "false" a prompt dialog will not be opened. If set to "1" or true the prompt dialog will be opened. Works with the Java Viewer and HTML Viewer. (Default "false").
Since Version: | 9 |
---|
(For the Java report viewer only): Specifies an auto-refresh cycle in milliseconds, e.g. "autorefresh=30000" would specify an auto-refresh of 30 seconds. This causes the report to be automatically refreshed in the Java report viewer, unless the report is currently being loaded anyways.
Since Version: | 3.x |
---|
Enable/Disable the logging output of the Java report viewer (default "true").
Since Version: | 9.1 |
---|
Specifies a default zoom factor for Java and HTML report viewer. Additionaly to the percent value the following values are possible:
-
a positive number meaning percent (e.g 70 → 70%)
-
PAGE_FIT
- fit the whole report page -
PAGE_WIDTH
- zoom to fit the width of the page -
PAGE_HEIGHT
- zoom to fit the height of the page
Since Version: | x |
---|
Location from that the archive file CC-Viewer.jar will be loaded.
The default value is the value of the codebase parameter with "/CC-Viewer.jar"
appended.
If you want to load the viewer from the different location use:
http://<servername>:<port>/?report=...rpt&archive= http://<serverName>:<port>/crystalclear_2/CC-Viewer.jar
Samples
The following sample URLs showing the usage of the parameters when you request a report:
To use the sample URLs on your system replace:
-
<serverName> - with the name of the server on that the i-net Clear Reports Servlet is running
-
<port> - with the port number on that the Servlet engine is listening
-
<servletcontext> - with the Servlet context specified in the setup (default: crystal)
-
MyReports/sample1.rpt - with the path of your report template
The following sample URLs showing the request of a report from the i-net Clear Reports servlet: In these cases the report sample1.rpt is located in a virtual directory called: MyReports.
-
http://<serverName>:<port>/<servletContext>/ReportServlet?report=MyReports/sample1.rpt&password=pwd
-
http://<serverName>:<port>/<servletContext>/ReportServlet?report=MyReports/sample1.rpt
-
http://<serverName>:<port>/<servletContext>/ReportServlet?report=MyReports/sample1.rpt&prompt0=Test
Note that the MyReports/sample1.rpt resource in the examples above is located via "servletContext.getResource()". Where exactly MyReports/sample1.rpt is located depends on the servlet engine. To be portable across servlet-engines, please use a full URL path for example: report=file:c:/MyReports/sample1.rpt.
In the following example the report sample1.rpt is located in the directory: C:\Reports
.
-
http://<serverName>:<port>/<servletContext>/ReportServlet?report=file:C:/Reports/sample1.rpt
The following sample URLs showing the request of a report from the i-net Clear Reports server application:
-
http://<serverName>:9000/MyReports/sample1.rpt&password=pwd
-
http://<serverName>:9000/?report=http://<serverName>/MyReports/sample1.rpt
-
http://<serverName>:9000/?report=file:C:/Reports/sample1.rpt
Changing or setting URL parameters so that the client can't see them.
It is also possible to set the report URL parameters on the server-side. For example it is usually not a good idea to pass the password for the database as a report URL parameter. In short you use either the method com.inet.report.ReportServlet.checkHtmlPageProperties(java.util.Properties)
to change the applet parameters, the com.inet.report.ReportServlet.checkProperties(java.util.Properties, java.lang.Object)
callback to change the path to the report template or the com.inet.report.ReportServlet.checkProperties(com.inet.report.Engine, java.util.Properties, java.lang.Object)
callback to change the default values read from the report template using RDC.