Creating custom URLs to display and run Cognos Analytics content

You can create URLs that open or run IBM® Cognos® Analytics content objects, such as reports, dashboards, stories, and data modules. This feature extends the Share > Link command that creates a URL to display Cognos Analytics content objects to provide more control over the actions that are taken when the content object is displayed or run.

When you link to saved content, you create a URL that opens or runs Cognos Analytics content objects. You can create these URLs if you require more control over the actions invoked by them.

The following report types are supported in custom URLs: standard reports, report views, active reports, data sets, Query Studio reports, Analysis Studio reports, and their saved outputs.

If the content object is a report that has saved output, the saved output may be displayed, depending on the chosen URL parameters. Otherwise, the content object is run. If the content object is saved output, it is displayed. An error message is displayed if the saved output has been deleted.

Syntax

The syntax of the custom URLs takes one of the following two forms.

http://<servername>:<port>/bi/?pathRef=<path>&<option1>=<value1>&<option2>=<value2>...
http://<servername>:<port>/bi/?objRef=<id>&<option1>=<value1>&<option2>=<value2>...

pathRef or objRef identify the content object to use.

pathRef: Specifies the location of the object. This value does not change if the version of Cognos Analytics is changed or if the object is exported or imported in a deployment.
The easiest way to determine the value of pathRef is to create a URL by using the Share command. This URL contains the value of pathRef.
objRef: Specifies the id of the object. This value does not change if the content object is moved to a different location in My content or Team content.
The value of objRef is the ID value in the properties pane of the object.
perspective: Specifies which perspective to use: classicViewer or authoring. This parameter should normally not be specified, as the system will determine it based on properties of the object referenced by the URL.

A number of optional parameters can be appended to the URL. The following two options can be used in any perspective:

ui_appbar: Specifies whether to display the Application bar (true) or not (false). The default value is true.
ui_navbar: Specifies whether to display the Navigation bar (true) or not (false). The default value is true.

The following options can be used if the content object is a report.

action: Specifies whether to view saved output, run a report, or author an object. The following values are supported: viewOutput, run, edit. The default value depends on the object type, the object's default action as defined by its properties, and whether it has saved output, current security settings, and users' capabilities. When viewOutput is specified and there is no saved output, the object is run.
a11y: When running a report, specifies whether to include accessibility features (true) or not (false). The default value is false.
bidi: When running a report, specifies whether to enable bidirectional support (true) or not (false). The default value is false.
contentLocale: Specify the locale in which the report output is created when running or which locale to view when the report output was saved using multiple locales. The default is determined from the user’s preferences. Use an ISO country code for the value. For example, for German, specify contentLocale=de.; For this parameter to work, you must have a multilingual reporting environment. For more information, see Setting up a multilingual reporting environment.
format: When running a report, specifies the output format. When viewing saved output, specifies which of the available formats to view.
The possible values are: HTML, PDF, spreadsheetML, xlsxData, CSV and XML, layoutDataXML, XLWA, rawXML, XHTML, singleXLS, and HTMLFragment. The default value is determined from the object’s properties or the user’s preferences.

Note: Any format other than HTML, PDF, spreadsheetML, xlsxData, CSV, or XML will end up running the classicviewer , even for interactive reports. If you do specify a different format, it will be used, but may result in incorrect behaviour. For example, if you point to an interactive report with a viz or custom control and specify perspective=classicviewer, then the report will run in the classic viewer. However, the viz and custom control will not work. This is expected because the wrong perspective was specified.
productLocale: Specify the product locale to use. The default is determined from the user’s preferences.
prompt: When running a report, specifies whether to show the prompt page (true) or not (false). The default value depends on the report settings.
p_<prompt_name>: When running a report, specifies the value to use for the parameter named <prompt_name>.
promptParameters: When running a report, specifies prompt parameters as a JavaScript Object Notation (JSON) object. You can pass more complex parameter values to use when you run a report. For more information, see promptParameters option syntax.

The easiest way to create a custom URL is to use the Share command for the content object that you want to create a custom URL for, and then to modify the options in this URL.
Custom URLs can be long and your Cognos Analytics server environment might impose a length limit on the query portion of the URL You can work around this limitation by using the URL fragment identifier (#) in the URL. Here are some examples.
- http://<servername>:<port>/bi/#pathRef=<path>&<option1>=<value1>&<option2>=<value2>...
- http://<servername>:<port>/bi/?pathRef=<path>&<option1>=<value1>#<option2>=<value2>...
If you use a custom URL in an HTML item in a report, replace instances of & with &.

Note: You can either specify a URL or use the HTTP POST method to send the options to the Cognos Analytics server. However, you must specify all parameters using the same method: either URL or HTTP POST.

Example

The following example uses the HTTP POST method to specify a customized URL.

<html>
<body>
<div class="acordion">
   <div class="submit">
      <form method="POST" id="cognosPost" accept-charset="UTF-8" 
         action="http://cognos_analytics_IP_address:9300/bi/">
         <input type="hidden" name="pathRef" value=".public_folders/folder1/report1" 
            style="display: none">
         <input type="hidden" name="promptParameters" id="promptParameters" 
            value='{"name":"p_Line","value":{"use":"Camping Equipment"}}' 
            style="display: none">
         <input type="hidden" name="format" value="HTML" style="display: none">
         <input type="hidden" name="Download" value="false" style="display: none">
         <input type="submit" name="btn" value="Run report with Camping Equipment">
      </form>
   </div>
</div>
</body>
</html>