Sie sind auf Seite 1von 16

Guideline

Upgrading JavaScript
Applications from Cognos
ReportNet 1.x and Cognos
8.1/8.2 BI to Cognos 8.3/8.4
BI
Revision 10, 11 March 2010

Product(s): Cognos 8.3/8.4 BI

Area of Interest: Upgrade/Migration


Upgrading JavaScript Applications from Cognos ReportNet 1.x 2
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to
cscogpp@ca.ibm.com.

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 3
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

Revision History

15 June 2008 Initial Release

02 July 2008 Section 2 has been renumbered. Section 2.2 CheckData has been
extended. New sections 2.5 and 2.6 have been added.

10 July 2008 New section 2.8 onLoad and onBeforeLoad Events added. Section
2.2 checkData ( ) Function Replaced has been corrected

17 July 2008 Minor edits and corrections. No material changes.

18 July 2008 Added knowledge base article references, defect numbers and new
issues encountered and resolved. New sections 2.9 through to
2.13, and section 4.

24 July 2008 Added section 2.14

5 August 2008 Added sections 3.7 and 3.8

18 August Added section 3.9 (Rev 8)


2008

17 September Modified sections 2.2, 2.3 and 2.14 (Rev 8)


2008

22 September Fixed typo in 2.13 heading – first change for (Rev 9)


2008

23 September Added section 2.15 (Rev 9)


2008

11 March 2010 Added section 2.16 (Rev 10)

11 March 2010 Added section 3.10 (Rev 10)

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 4
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 5
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

Contents
1INTRODUCTION............................................................................................5
1.1WHY DO THESE UPGRADE ISSUES EXIST?.........................................................................5
1.2PURPOSE..............................................................................................................5
1.3APPLICABILITY........................................................................................................5
2KNOWN ISSUES............................................................................................6
2.1AUTOSUBMIT( ) FUNCTION REPLACED..............................................................................6
2.2CHECKDATA ( ) FUNCTION REPLACED..............................................................................6
2.3REFERENCE TO THE FORMWARPREQUEST HAVE CHANGED......................................................... 7
2.4CHECKBOXLIST*.UPDATESELECTED( ) NO LONGER REQUIRED...................................................7
2.5REMOVEATTRIBUTE(“HASLABEL”) FUNCTION ADDED.............................................................. 8
2.6PROMPT OBJECT NAMING CONVENTION............................................................................8
2.7ATTACHEVENT() FUNCTION..........................................................................................8
2.8ONLOAD AND ONBEFORELOAD EVENTS.............................................................................9
2.9CANSUBMITPROMPT ( ) FUNCTION ADDED.........................................................................9
2.10THE REFERENCE TO LISTBOX SELECTALL HAVE CHANGED........................................................ 9
2.11RUNREPORT () FUNCTION HAS CHANGED.........................................................................9
2.12TO DE-SELECT AN OPTIONAL DATE PROMPT CHECKBOX REQUIRES A FIREEVENT................................10
2.13ONLOAD PAGE EVENT IS NOT ALWAYS CALLED.................................................................. 10
2.14PAGENAVIGATIONOBSERVERARRAY NEEDS PREFIX...............................................................10
2.15CHANGE IN HOW TO DETERMINE THE NAME OF A VALUE PROMPT AND CHECK IF IT IS REQUIRED............ 11
2.16OUTPUT FORMAT CANNOT BE CHANGED IN A RUNNING REPORT................................................ 11
3TIPS............................................................................................................12
3.1LEARN JAVASCRIPT................................................................................................12
3.2JAVASCRIPT APPLICATION MAINTENANCE.........................................................................12
3.3COMMON JAVASCRIPT MODULES..................................................................................12
3.4REPORT TEMPLATES................................................................................................12
3.5USE STANDARD PROMPT BUTTONS...............................................................................12
3.6DYNAMIC REPORTSPEC UPDATER (DRU).......................................................................12
3.7PROBLEMS USING WINDOW EVENTS...............................................................................13
3.8OBFUSCATION......................................................................................................13
3.9DOCUMENT.WRITE.................................................................................................13
3.10DIFFERENCES IN RERUN BETWEEN 8.3 AND 8.4..............................................................13
4KNOWN DEFECTS....................................................................................... 14
4.1599023 – UNABLE TO GRAB THE TREE PROMPT CONTROL USING JAVASCRIPT IN IBM COGNOS 8.3......14
1INTRODUCTION............................................................................................5
1.1WHY DO THESE UPGRADE ISSUES EXIST?.........................................................................5
1.2PURPOSE..............................................................................................................5
1.3APPLICABILITY........................................................................................................5
2KNOWN ISSUES............................................................................................6
2.1AUTOSUBMIT( ) FUNCTION REPLACED..............................................................................6
2.2CHECKDATA ( ) FUNCTION REPLACED..............................................................................6
2.3REFERENCE TO THE FORMWARPREQUEST HAVE CHANGED......................................................... 7
2.4CHECKBOXLIST*.UPDATESELECTED( ) NO LONGER REQUIRED...................................................7
2.5REMOVEATTRIBUTE(“HASLABEL”) FUNCTION ADDED.............................................................. 8
2.6PROMPT OBJECT NAMING CONVENTION............................................................................8
2.7ATTACHEVENT() FUNCTION..........................................................................................8

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 6
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

2.8ONLOAD AND ONBEFORELOAD EVENTS.............................................................................9


2.9CANSUBMITPROMPT ( ) FUNCTION ADDED.........................................................................9
2.10THE REFERENCE TO LISTBOX SELECTALL HAVE CHANGED........................................................ 9
2.11RUNREPORT () FUNCTION HAS CHANGED.........................................................................9
2.12TO DE-SELECT AN OPTIONAL DATE PROMPT CHECKBOX REQUIRES A FIREEVENT................................10
2.13ONLOAD PAGE EVENT IS NOT ALWAYS CALLED.................................................................. 10
2.14PAGENAVIGATIONOBSERVERARRAY NEEDS PREFIX...............................................................10
2.15CHANGE IN HOW TO DETERMINE THE NAME OF A VALUE PROMPT AND CHECK IF IT IS REQUIRED............ 11
3TIPS............................................................................................................12
3.1LEARN JAVASCRIPT................................................................................................12
3.2JAVASCRIPT APPLICATION MAINTENANCE.........................................................................12
3.3COMMON JAVASCRIPT MODULES..................................................................................12
3.4REPORT TEMPLATES................................................................................................12
3.5USE STANDARD PROMPT BUTTONS...............................................................................12
3.6DYNAMIC REPORTSPEC UPDATER (DRU).......................................................................12
3.7PROBLEMS USING WINDOW EVENTS...............................................................................13
3.8OBFUSCATION......................................................................................................13
3.9DOCUMENT.WRITE.................................................................................................13
4KNOWN DEFECTS....................................................................................... 14
4.1599023 – UNABLE TO GRAB THE TREE PROMPT CONTROL USING JAVASCRIPT IN IBM COGNOS 8.3......14

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 7
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

1 Introduction

Various people have created JavaScript applications which interact with


undocumented and unsupported APIs and objects in the Cognos Viewer such
as prompt controls, buttons, and functions. Despite the undocumented and
unsupported nature of these JavaScript applications and APIs, we understand
that there is business value our customers are deriving from these
applications and we are committed to assisting in the upgrade process to the
extent of providing high level guidance.

These people have reverse engineered the Cognos Viewer source code and
built JavaScript applications that are dependant on that source code. As these
JavaScript applications have been developed without the knowledge of
Cognos development, we are unable to anticipate the full extent of the
changes required to upgrade a given JavaScript application. Therefore, this is
intended to be a living document in which we will add additional information
as it becomes available.

1.1 Why do these Upgrade Issues Exist?


For the most part, JavaScript applications written in Cognos ReportNet 1.x
upgraded well to Cognos 8.1 or 8.2 as there were few changes in Cognos
Viewer to account for. In Cognos 8.3 Cognos Viewer was re-architected to
allow it to run within Report Studio to provide the live data view for Express
Authoring Mode. This necessitated major changes to the source code
resulting in JavaScript applications not upgrading cleanly. As These JavaScript
applications had been developed without the knowledge of Cognos
development, the detrimental effect of the Cognos Viewer changes were
unknown until Cognos 8.3 was released and customers started to feel the
impact.

Now that we are aware of these issues, we have tried to ensure that known
areas are not changed between Cognos 8.3 and Cognos 8.4. But as we have
no definitive list of issues we are unable to either document all of them in
Cognos 8.3 or 8.4 nor to guarantee 100% compatibility between Cognos 8.3
and Cognos 8.4.

1.2 Purpose
This document provides advice and guidance on for upgrading JavaScript
applications which run in the Cognos Viewer from Cognos ReportNet 1.x or
Cognos 8.1 or 8.2 BI to Cognos 8.3 or 8.4.

1.3 Applicability
This document applies equally to Cognos 8.3 BI and Cognos 8.4 BI.

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 8
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

2 Known Issues

Issues with JavaScript applications tend to fall into two areas:


The JavaScript application must be modified to use a different object or API.
This document discusses known areas and strategies for correction.
The changes in Cognos Viewer are such that a JavaScript application cannot
be modified to work.
Cognos 8.3 Service Pack 1 has resolved all issues of this nature that we are
aware of. Therefore, we recommend that this release (or later) be used.
This section documents specific items that we are aware of. If you come
across issues not covered in this section, please open a call with customer
support.
Many samples have been updated in our Support Knowledge Base. Follow
the below link and search by number to find the most recent document
revision. IBM Cognos Knowledge Base

2.1 autoSubmit( ) Function Replaced


The autoSubmit( ) function no longer exists, having been replaced by the
promptButtonFinish( ) or promptAction(‘finish’) function. References to the
autoSubmit( ) button must be replaced with the new function.

For an example, refer to Knowledge Base (KB) article:


1012254 – JavaScript: Set default value for a value prompt by using HTML
item

A bulk search/replace utility such as DRU may be useful to deal with this
issue.

2.2 checkData ( ) Function Replaced


The obj.checkData( ) function no longer exists in all cases, having been
replaced by the global function canSubmitPrompt( ) function. References to
the checkData( ) button must be replaced with the new function.

For an example, refer to Knowledge Base (KB) article:


1036117 – JavaScript: Sample to automatically select first item in value
prompt

A bulk search/replace utility such as DRU may be useful to deal with this
issue.

Note that any use of checkData currently working in 8.3+ should remain in
the product for the foreseeable future. It is not available on some objects
(such as text items) where it was available in past releases.

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 9
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI

2.3 Reference to the formWarpRequest have changed


The new getFormWarpRequest ( ) replaces several other mechanisms to
access the main form object ‘formWarpRequest’. All references to this such as
document.forms[0], document.forms[‘formWarpRequest’] and
formWarpRequest should be replaced with the getFormWarpRequest( )
function.

Here’s a code snippet that will work in all cases:

// use the function whenever available


var fW = (typeof getFormWarpRequest == "function" ?
getFormWarpRequest() : document.forms["formWarpRequest"]);
// if it’s undefined, check if it is running in a portlet
if ( !fW || fW == undefined) { fW = ( formWarpRequest_THIS_ ?
formWarpRequest_THIS_ : formWarpRequest_NS_ );}

For examples, refer to Knowledge Base (KB) articles:


1037616 – JavaScript: Calling HTML form name in Cognos 8.3 report
1041204 - Javascript: Running report with JavaScript in Cognos Viewer
Portlet

Note: Cognos 8.3 SP1 and Cognos 8.4 both have the refererence to
formWarpRequest reinstated to facilitate upgrades but getFormWarpRequest
() is the preferred mechanism.

2.4 checkBoxList*.updateSelected( ) No Longer Required


The checkBoxList*.updateSelected( ) function was used to indicate that the
prompt value was set or changed. This function is no longer used and all
references to it can simply be deleted. There is no analogous function. The
prompt state is determined using alternate means.

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 0

2.5 removeAttribute(“hasLabel”) Function Added


Scripts that remove the top two lines from a ‘Drop Down List’ now require an
additional line of code in order for the prompt object to work properly. The
additional line removes the ‘label’ attribute, which allows the prompt object to
validate properly.

<form object>.<list object>.removeAttribute('hasLabel');

For an example usage see Knowledge Base (KB) article:


1039231 Javascript: Removing first 2 items from a value prompt in Cognos
8.3.

You should be able to add the removeAttribute() function using DRU.

2.6 Prompt Object Naming Convention


The following prompt objects can be accessed via the 8.2 (and prior) naming
convention:
Text Edit Box _textEditBox<prompt name>
List Box _oLstChoices<prompt
name>
Drop Down List _oLstChoices<prompt
name>
Radio Button _oLstChoices<prompt
Group name>
Check Box Group _oLstChoices<prompt
name>
Date Edit Box txtDate<prompt name>

All other prompt objects need to be accessed using another technique, such
as using a named span tag (<span>) around the prompt object and
accessing the span tag via the getElementById() function and the prompt
object items using the getElementsByTagName() function.

For an example of a checkbox prompt see Knowledge Base (KB) article:


1017271 – Javascript: How to use stored procedure with input parameter
that takes in multiple values

These changes cannot be handled by the DRU application. The changes will
depend on what was originally accomplished by the script.

2.7 attachEvent() Function


The attachEvent( ) function has been removed. In its place, use the objects
onChange event.

For example, replace this


frm._oLstChoicesXXXX.attachEvent("onChange", "doSomething");

With this

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 1

frm._oLstChoicesXXXX.onChange = doSomething;

2.8 onLoad and onBeforeLoad Events


The onLoad and onBeforeUnLoad event aren't called anymore between pages
and autosubmit. There is currently no workaround for this issue.

2.9 canSubmitPrompt ( ) Function Added


This function can be used to validate prompts on a prompt page. For example,
when changing the values of a textbox using JavaScript the keyboard events
are not invoked. This method can be used to simulate an onKeyUp event if the
prompts are valid and will enable the ‘Next’ or ‘Finish’ button(s) on the prompt
page.

For an example, refer to Knowledge Base (KB) article:


1019017 – JavaScript: How to reference a text box prompt via JavaScript.
What is the element name?

2.10 The reference to listBox selectAll have changed


References to the select All and Deselect All links on a prompt page have
changed. They can no longer be accessed or removed by referencing the
javascript:listboxRemoveSelectAllDeselectAll.selectAll(). Alternate methods
must be used to accomplish this.

For an example, see Knowledge Base (KB) article:


1020989 – JavaScript: How to remove the Select All and DeSelect All links
from a multi select value prompt

2.11 RunReport () function has changed.


To submit a report you can no longer just call the runReport function. This
function requires a Cognos viewer object. This object is different between
Report Studio and Cognos Connection and you must determine where the
report is being run from to determine which object to use.

For an example, refer to Knowledge Base (KB) article:


1036610 – JavaScript: Setting reports to auto refresh in Report Viewer with
IE 6 or 7

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 2

2.12 To de-select an optional date prompt checkbox requires a fireevent.


Checkbox references have changed as well and the certain events are no
longer called. In order to disable an existing checkbox on a date prompt a
number of changes were needed including forcing a fireevent.

For an example, refer to Knowledge Base (KB) article:


1027921 JavaScript: How to make an optional date prompt default to
Disabled in Report Studio

2.13 Onload page event is not always called.


You can no longer rely on the onLoad event to trigger JavaScript code. To
ensure that your code gets executed just add the function you wish to call to
a script tag. References where it was called in a
<body onload=myFunction()> could be replaced with <script>myFunction
();</script>

2.14 pageNavigationObserverArray needs prefix


In 8.3 a prefix was added to a number of variables (ie:
pageNavigationObserverArray, promptAction and rvMainWnd) to make them
fragment safe.

The new format is oCV<Namespace>.< variable>

By default <Namespace> is _NS_ (this is the case when the report is run
from the Cognos Connection)
<Namespace> is RS if the report is run from the Report Studio. A
dynamically generated namespace is used when running within a portlet.

To determine the namespace at runtime, use the following code:

var fW = (typeof getFormWarpRequest == "function" ?


getFormWarpRequest() : document.forms["formWarpRequest"]);
if ( !fW || fW == undefined) { fW = ( formWarpRequest_THIS_ ?
formWarpRequest_THIS_ : formWarpRequest_NS_ );}

fW._oLstChoicesMyFieldName.selectedIndex = 0;
var preFix = "";
if (fW.elements["cv.id"])
{
preFix = fW.elements["cv.id"].value;
}

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 3

setTimeout('oCV' + preFix + '.promptAction(\'finish\')', 100);

For examples, refer to Knowledge Base (KB) articles:


1028289 Javascript: How to create a Previous Report link
1041204 JavaScript: Running report with JavaScript in Cognos Viewer Portlet

2.15 Change in how to determine the name of a value prompt and check if
it is required
Pre 8.3, you could use the name attribute of a <select> to find the
associated JavaScript object. There isn't such an explicit link in 8.3.

You can use the global objects listBox* to figure out the name rather than
going through the <select> box.

For an example, refer to Knowledge Base (KB) article:


1041341 Javascript: How to determine the name of a value prompt and
check if it is required

2.16 Output format cannot be changed in a running report


In 8.3 and up, it is no longer possible to change the output format once the
report has been launched. Once you are in the prompt page, there is no way
to change the output format.

As an alternative, use the non-Javascript technique in the following technote:


http://www-01.ibm.com/support/docview.wss?rs=0&uid=swg21406312

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 4

3 Tips

3.1 Learn JavaScript


We find that many customers have used JavaScript applications without
understanding how they operate and therefore, how to fix issues as they
arise. It is recommended that appropriate JavaScript skills be provided to
support these applications.

3.2 JavaScript Application Maintenance


As these JavaScript applications depend on undocumented and unsupported
APIs there are possible future maintenance issue accruing from their use.
While Cognos will make every effort to provide upwards compatibility, it must
be understood that these applications depend on how our source code is
written and we will trade off compatibility for product momentum.

3.3 Common JavaScript Modules


A common error we have found with most of the JavaScript applications we
have seen is that the same JavaScript code is copied and pasted into many
reports resulting in a very difficult maintenance situation. The best practice is
to isolate the shared JavaScript code in a single common JavaScript file with
minimum JavaScript in each report to reference/include the shared code.

3.4 Report Templates


If server access is unavailable, common JavaScript modules can be placed
into Report Templates also. While this does reduce authoring effort, the
server based approach is best to ensure maximum maintainability.

3.5 Use Standard Prompt Buttons


Contrary to popular belief the Report Studio prompt buttons are highly
customizable and in most cases where we see custom buttons being used the
same effect could have been achieved using the documented and supported
customized prompt buttons.

3.6 Dynamic ReportSpec Updater (DRU)


DRU is a search and replace utility for report specifications in the Cognos 8
content. DRU allows the user to select a set of reports in Cognos 8 (Report
Studio, Query Studio, Analysis Studio or PowerPlay 8) and apply one or more
search and replace operations against those reports.

DRU can be useful for any bulk search and replace operations. For example,
references to an obsolete JavaScript function might be replaceable with the
correct function name.

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 5

DRU is available from the IBM Cognos Customer Support site in the Cognos
Diagnostic Tools section via the following link:
http://support.cognos.com/en/support/diagnostics/index.html

3.7 Problems using Window events

General advice: Stay away from using events, especially on the window
object. It not the best way to have your custom scripts run and usually it
makes them IE-specific.

As alternatives for a simple list report, place the HTMLItem containing the
script you want to run every time the page is updated in the footer, and
place it after the table if you want it to run only on the last page.

3.8 Obfuscation

The variables/functions starting with an underscore and then some random


letters are variables/functions we have renamed when packaging our
JavaScript code to hide their true meaning. They are by design unstable and
subject to change with each product release. Therefore, these functions and
variables should never be used or referenced.

3.9 Document.Write

Using document.write() is a bad practice in general and especially when hidden in a


JavaScript file.

In the following example document.write is being used to insert standard HTML into a
number of reports:

document.write("<select name='returnList'>");
document.write("<option value='public'>Public Folder</option>");
document.write("<option value='New'>New Folder</option>");
document.write("<option value='Second' >Second Folder</option>");
document.write("<option value='Third' selected>Third Folder</option>");
document.write("</select>");

Alternative solutions:
1) Use a Layout Component Reference to an htmlItem (which has the desired
<select> as is) in Report Studio rather than using <htmlitem> to include a javascript
file that builds a <select> using document.write. The Layout Component Reference
can point to any existing report, including one used to hold common htmlItems re-
used in many reports.
2) Add a span with an ID in the same htmlItem as the JavaScript include to be used
as a container, then create the <select> using DOM or innerHTML.

Solution #1 is the recommended option.

Proprietary Information
Upgrading JavaScript Applications from Cognos ReportNet 1.x 1
and Cognos 8.1/8.2 BI to Cognos 8.3/8.4 BI 6

3.10 Differences in Rerun between 8.3 and 8.4

See the following technote for details:

http://www-01.ibm.com/support/docview.wss?rs=0&uid=swg21423922

4 Known Defects

4.1 599023 – Unable to grab the tree prompt control using Javascript in
IBM Cognos 8.3
Fix available in hotsite 8.3.82.1066 which includes prompt toolkit 8.3.720

Proprietary Information

Das könnte Ihnen auch gefallen