Upgrading Javascript Applications

I BM
Guideline
Upgrading JavaScript
Applications from I BM Cognos
ReportNet version 1.x and I BM
Cognos 8 BI versions 8.1, 8.2
to I BM Cognos BI versions 8.3,
8.4
Revision 9, 27 October 2008
Product(s): IBM Cognos 8 BI versions 8.3,8.4
Area of Interest: Upgrade/ Migration
Upgrading JavaScript Applications from I BM Cognos ReportNet 2
version 1.x and I BM Cognos 8 BI versions 8.1, 8.2 to I BM
Cognos BI versions 8.3, 8.4
Copyright
These Diagnostics and Troubleshooting Tools ("Software Tools") have been developed to
assist you in diagnosing and troubleshooting issues you may be experiencing with your use of
IBM Cognos Software.
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 IBM

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

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

1 I ntroduction
Various people have created JavaScript applications which interact with
undocumented and unsupported application programming interfaces (API)
and objects in the IBM® Cognos® Viewer such as prompt controls, buttons,
and functions. Despite the undocumented and unsupported nature of these
Sun® Microsystems® JavaScript ® (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 IBM 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
IBM 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 I ssues Exist?

For the most part, JavaScript applications written in IBM Cognos ReportNet
version 1.x upgraded well to IBM Cognos 8 BI versions 8.1, 8.2 as there were
few changes in IBM Cognos Viewer to account for. In IBM Cognos 8 BI
version 8.3 IBM Cognos Viewer was re-architected to allow it to run within
IBM Cognos 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 IBM Cognos
development, the detrimental effect of the IBM Cognos Viewer changes were
unknown until IBM Cognos 8 BI version 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 IBM Cognos 8 BI version 8.3 and IBM Cognos
8 BI version 8.4. But as we have no definitive list of issues we are unable to
either document all of them in IBM Cognos 8 BI versions 8.3 or 8.4 nor to
guarantee 100% compatibility between IBM Cognos 8 BI version 8.3 and IBM
Cognos 8 BI version 8.4.
1.2 Purpose
This document provides advice and guidance on for upgrading JavaScript
applications which run in the IBM Cognos Viewer from IBM Cognos ReportNet
version 1.x or IBM Cognos 8 BI version 8.1 or 8.2 BI to IBM Cognos 8 BI
version 8.3 or 8.4.

1.3 Applicability
This document applies equally to IBM Cognos 8 BI version 8.3 BI and IBM

2 Know n I ssues
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 IBM Cognos Viewer are such that a JavaScript application
cannot be modified to work.
IBM Cognos 8 BI version 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: General Search for IBM Cognos resources.
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 Hyper
Text Markup Language (HTML) item
A bulk search/ replace utility such as Dynamic Report Specification Updater

Diagnostic (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.

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 IBM Cognos 8 BI version
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.

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 IBM Cognos 8 BI version
8.3 report 1041204 - Javascript: Running report with JavaScript in IBM
Cognos Viewer Portlet
Note: IBM Cognos 8 BI version 8.3 SP1 and IBM Cognos 8 BI version 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.

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 IBM
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 IBM Cognos 8 BI
version 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 Group _oLstChoices<prompt 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
frm._oLstChoicesXXXX.onChange = doSomething;

version 1.x and I BM Cognos 8 BI versions 8.1, 8.2 to I BM 0
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.

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 an IBM Cognos viewer object. This object is different
between IBM Cognos Report Studio and IBM Cognos Connection and you
must determine where the report is being run from to determine which object
to use.

1036610 – JavaScript: Setting reports to auto refresh in IBM Cognos Report
Viewer with Microsoft® Internet® Explorer® version 6 or 7

2.12 To deselect 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.

1027921 JavaScript: How to make an optional date prompt default to
Disabled in IBM Cognos Report Studio
2.13 Onload page event is not alw ays 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 IBM Cognos 8 BI version 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 IBM Cognos Connection)
< Namespace> is RS if the report is run from the IBM Cognos 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;
}
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 IBM Cognos Viewer
Portlet
2.142.15 Change in how to determine the name of a value prompt and

check if it is required
Pre IBM Cognos 8 BI version 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 IBM Cognos 8 BI version 8.3.
You can use the global objects listBox* to figure out the name rather than
going through the < select> box.

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

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 IBM 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 IBM Cognos 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 IBM Cognos
8 content. DRU allows the user to select a set of reports in IBM Cognos 8
(IBM Cognos Report Studio, IBM Cognos Query Studio, IBM Cognos Analysis
Studio or IBM Cognos PowerPlay) 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.
DRU is available from the IBM Cognos Customer Support site in the IBM
Cognos Diagnostic Tools section via the following link: IBM Cognos
Diagnostic Tools and Utilities

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 HTML Item 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.

4 Know n Defects
4.1 599023 – Unable to grab the tree prompt control using Javascript in
I BM Cognos 8 BI version 8.3
Fix available in hotsite 8.3.82.1066 which includes prompt toolkit 8.3.720
The listed trademarks

• Java and all Java-based trademarks and logos are trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
• Microsoft, Windows, Windows 2000, Windows NT, and the Windows logo are
trademarks of Microsoft Corporation in the United States, other countries, or
both.

Upgrading Javascript Applications

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Upgrading Javascript Applications

Uploaded by

Copyright:

Available Formats

I BM

Proprietary Information IBM

Proprietary Information IBM

Proprietary Information IBM

1.1 Why do these Upgrade I ssues Exist?

Proprietary Information IBM

Proprietary Information IBM

2.1 autoSubmit( ) Function Replaced

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

A bulk search/ replace utility such as Dynamic Report Specification Updater

2.2 checkData ( ) Function Replaced

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

Proprietary Information IBM

2.3 Reference to the formWarpRequest have changed

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

/ / use the function whenever available

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

2.4 checkBoxList* .updateSelected( ) No Longer Required

Proprietary Information IBM

2.5 removeAttribute( “hasLabel”) Function Added

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

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

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

2.6 Prompt Object Naming Convention

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

2.7 attachEvent( ) Function

For example, replace this

Proprietary Information IBM

2.8 onLoad and onBeforeLoad Events

2.9 canSubmitPrompt ( ) Function Added

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

2.10 The reference to listBox selectAll have changed

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

2.11 RunReport ( ) function has changed.

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

Proprietary Information IBM

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

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

2.13 Onload page event is not alw ays called.

2.14 pageNavigationObserverArray needs prefix

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

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

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

Proprietary Information IBM

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

2.142.15 Change in how to determine the name of a value prompt and

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

Proprietary Information IBM

3.2 JavaScript Application Maintenance

3.3 Common JavaScript Modules

3.4 Report Templates

3.5 Use Standard Prompt Buttons

3.6 Dynamic ReportSpec Updater ( DRU)

Proprietary Information IBM

3.7 Problems using Window events

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

Solution #1 is the recommended option.

Proprietary Information IBM

The listed trademarks

Proprietary Information IBM

You might also like