Cognos Pp Development Dynamic Report Spec Updater User Guide

Dynamic ReportSpec Updater

User Guide

2

Copyright © 2008 Cognos ULC (formerly Cognos Incorporated), an IBM Company. All rights reserved.

Copyright Your use of this document is subject to the Terms of Use governing the Cognos software products and related services which you have licensed or purchased from Cognos. The information contained in this document is proprietary information of Cognos Incorporated and/or its licensors and is protected under copyright and other applicable laws. You may use the information and methodologies described in this document 'as is' or you may modify them, however Cognos will not be responsible for any deficiencies or errors that result from modifications which you make. Copyright 2008 (c) Cognos Incorporated. All Rights Reserved. You can print selected pages, a section, or the whole book. Cognos grants you a non-exclusive, non-transferable license to use, copy, and reproduce the copyright materials, in printed or electronic format, solely for the purpose of providing internal training on, operating, and maintaining the Cognos software. This document is maintained by the Diagnostic Tools team. You can send comments, suggestions, and additions to [email protected].

3


Contents 1 INTRODUCTION............................................................................................ 4 1.1 DISCLAIMER ..........................................................................................................4 1.2 PURPOSE ..............................................................................................................4 1.3 REQUIREMENTS ......................................................................................................5 1.4 APPLICABILITY .......................................................................................................5 1.5 PRECAUTIONS ........................................................................................................5 2 THE DRU USER INTERFACE........................................................................... 6 2.1 THE DISPATCHER SECTION ........................................................................................6 2.2 THE CONTENT FOLDER SECTION .................................................................................7 2.3 THE TRANSFORMATION SECTION.................................................................................9 2.4 THE EXECUTION AND DISK LOCATION FOR SPECIFICATION SECTION ................................... 11 2.5 THE LOGOUTPUT SECTION ...................................................................................... 12 3 BUILDING A TRANSFORMATION XML FILE ................................................ 13 4 DOING A TRANSFORMATION FROM BEGINNING TO END.......................... 17 4.1 INSTALLING AND LAUNCHING DRU ............................................................................ 17 4.2 CREATING THE REQUIRED TRANSFORMATION FILE.......................................................... 19 4.3 APPLYING THE TRANSFORMATION TO EXISTING CONTENT................................................. 22 5 WRITING JAVA REGULAR EXPRESSIONS AND USING DRU ....................... 27 6 APPENDIX A: SAMPLE STYLE TRANSFORMATION..................................... 29 7 APPENDIX B: SAMPLE IMAGE TRANSFORMATION.................................... 30 8 APPENDIX C: SAMPLE TEXT TRANSFORMATION....................................... 31 9 APPENDIX C: SAMPLE JAVASCRIPT TRANSFORMATION........................... 32

4


1 Introduction

The Dynamic ReportSpec Updater (“DRU”) is a powerful global find and replace tool which allows a user to search for any XML elements of Report Studio, Query Studio, Analysis Studio and Power Play 8 report specifications and update them with a new XML element. DRU does this by traversing the IBM Cognos 8 content path, retrieving the XML specifications one by one and applying the search and replace attributes identified within a user defined transformation file. The transformations are applied in a user defined order with the resultant output being written either directly to the Content database or to a locally designated drive. Although the possibilities are endless, some sample uses for this utility are:

• Update image references to update the reports with a new company logo.

• Update embedded JavaScript elements that may have changed after an upgrade.

• Update the report title text to reflect a new project owner. The latest version of this utility can be downloaded form: http://support.cognos.com/en/support/diagnostics/index.html

1.1 Disclaimer The Dynamic ReportSpec Updater (“DRU”) has been developed to assist you in resolving issues you may be experiencing with your use of Cognos Software. This Software Tool is provided free of charge and are subject to the following terms: 1. Except for running the Software Tools, you are not permitted to make any alterations to the Cognos Software as delivered by Cognos. 2. The Software Tools may only be used within your organization on validly licensed copies of Cognos Software. You may not distribute the Software Tools to any other third party, company or entity. 3. The Software Tools are provided “as is”. Cognos makes no warranties, express or implied. 4. The Software Tools are provided as a convenience only. Cognos may cease to provide the Software Tools and any updates at any time without notice. 5. The Software Tools and any related trade mark, trade secret or copyright are, and will remain, the exclusive property of Cognos. You will not disassemble or otherwise attempt to reverse engineer the Software Tools. Your rights are limited to those specifically granted in these Terms of Use.

1.2 Purpose This document will provide the following:

• An overview of the DRU user interface • An overview of a sample transformation file.

5


• Step by step instructions for applying a style transformation to a set of sample reports.

1.3 Requirements DRU requires an installation of Java Runtime Environment (JRE) 1.4.2 or higher.

1.4 Applicability The techniques and behaviours outlined in this document were validated using Cognos 8.3.116.12 against the reports and packages imported with the Cognos_Samples.zip sample deployment.

1.5 Precautions This utility has the ability to corrupt all reports within an IBM Cognos 8 environment if used incorrectly. It is mandatory that all IBM Cognos 8 content is backed up, through a supported and proven method prior to the use of this utility. Depending on the matching criteria identified in the transformation file, along with the number of report objects in the content path, performing transformations may be resource and Central Processing Unit (CPU) intensive. For these reasons, DRU is not recommended for use on production systems.

6


2 The DRU User Interface

The following section provides an explanation of the individual elements which comprise the DRU user interface (UI). The following is an image of the UI in its entirety.

2.1 The Dispatcher Section The Dispatcher section contains the fields required to make a connection to the IBM Cognos 8 dispatcher.

Dispatcher: This is the URI for the dispatcher that the utility will connect to. This setting can be ascertained from the Environment\External dispatcher URI property within IBM Cognos Configuration. User Name: This is the namespace user name that is going to be used to connect to the IBM Cognos environment. Only objects that are visible to this user ID will be displayed as transformable content. Password: This is the password for the user specified in the User Name field.

7


Namespace: This is the NamespaceID for the namespace the user specified in the User Name will log on to. This setting can be obtained from the NamespaceID property under Security\Authentication within Cognos Configuration. Anonymous: If no security has been applied to the IBM Cognos 8 environment, an anonymous logon can be achieved by selecting this checkbox. Un-checking this select box will activate the User Name, Password and Namespace input fields. Connect: This button will attempt to connect to the specified dispatcher anonymously or using the specified credentials. Help: Help is a link to this document.

2.2 The Content Folder Section Once a successful connection to the dispatcher has been established, the utility will display all content that is visible to the credentials provided for the connection.

8


Content Folders: This is a tree representation of the IBM Cognos 8 content. Public content will be displayed under Public Folders. MyFolder content is displayed under the Namespace name as illustrated below.

Name: This is the name of the object as it is displayed within Cognos Connection. Type: This is the type of object displayed. Although all types are displayed, transformation will only be done on Report Studio, Query Studio, Analysis Studio and PowerPlay 8 reports. SearchPath: This is the searchpath as it is displayed in Cognos Connection. The searchpath can be used to validate the source location of the object.

9


2.3 The Transformation Section This section allows a user to load, order, and remove the transformations that will manipulate the IBM Cognos 8 report objects. This area also allows a user to select which type of report objects the specified transformations are going to be applied to.

Load: Clicking this button will allow a user to browse to, and load the desired XML file which represents the transformation to be performed. Remove: This button allows a user to remove an undesired transformation from the Selected Transformations & Order of Execution window. Up: This button allows a user to move a transformation up higher in the execution order. Transformations are processed in the order that they appear in the Selected Transformations & Order of Execution window. Down: This button allows a user to move a transformation down lower in the execution order. Transformations are processed in the order that they appear in the Selected Transformations & Order of Execution window. Selected Transformation & Order Of Execution: This windows displays all the transformation names and the order in which they are going to be executed. Content Type: These checkboxes allow a user to specify which report object the transformations listed in the Selected Transformations & Order of Execution window will be applied to. Report: These are Report Studio Reports Query: These are Query Studio Reports Analysis: These are Analysis Studio Reports PowerPlay: These are PowerPlay Studio Reports

2.4 The Execution and Disk Location For Specification Section This area allows users to manage the output behaviour of the transformed reports.

Overwrite Existing Reports: This feature is only valid if the Do NOT update CM feature is unchecked. If this feature is checked, the utility will overwrite all the original report specified to be transformed with the transformed reports. If this feature is un-checked, the utility will leave the original report in Cognos Connection in place. The transformed report will be written to the same location, with the same name suffixed with a –new. Do NOT Update CM: If this feature is checked, the report objects to be transformed will be written to the OriginalSpecification location specified in the Disk Location For Specifications area. The transformed objects will be written to the location specified in the Updated Spec location. Run: This button starts the execution of the transformations specified in the Selected Transformations & Order of Execution window. Stop: This button stops the execution of the transformations specified in the Selected Transformations & Order of Execution window. Search: This button searches the IBM Cognos 8 content, starting at the level specified in the Content Folders section, for the search criteria specified in the transformation file. Any matches are recorded in the RSULog<date_time>.txt located in the utility working directory. Original Spec: This is the location of the report objects to be transformed. Report specifications are written to this location regardless of whether the Do NOT update CM feature is checked or unchecked. By default the Original Spec location is ..\OriginalSpecifcations. An alternative path can be specified using the appropriate Browse button. Updated Spec: This is the location of the report objects that were transformed when the Do NOT update CM feature is checked. By default the Updated Spec location is ..\UpdatedSpecifcations. An alternative path can be specified using the appropriate Browse button.

12


2.5 The LogOutput Section The LogOutput section is gives a user a visual representation of what is being written to the logs. The output log is written to the utility working directory under the name RSULog<date_time>.txt.

13


3 Building a Transformation XML File

In its most basic form the transformation file uses XML tags to specify the item to be searched for and the item to be replaced. The overall structure of the file can be broken down into:

• A header tag • A transformations tag

o An transformation tag A search tag A replace tag

The following section will provide the steps required to create a transformation file which changes any text references of “Great Outdoors” to “Super Fantastic Outdoors”.

1. Open Notepad by tying Notepad and clicking Enter within the windows Start\Run Menu

2. Copy the following header tag into the file. This header will be the same for

all files.

<?xml version="1.0" encoding="UTF-8"?>

3. Copy the following transformations tag and paste it into the Notepad file under the header line. These start and end tags are also common to all files. <Transformations>

</Transformations>

The file should now look as follows. <?xml version="1.0" encoding="UTF-8"?>

<Transformations>

</Transformations>

14


4. Insert the following lines in between the transformations tags created in the previous step.

<Transformation id="Convert 'Great Outdoors' to 'Super Fantastic

Outdoors'">

</Transformation>

The Transformation id can be any text used to describe what the transformation does. In this case, the transformation has been called Convert Great Outdoors to Super Fantastic Outdoors. The file should now look as follows. <?xml version="1.0" encoding="UTF-8"?>

<Transformations>


Outdoors'">

</Transformation>

</Transformations>

5. Insert the following line in between the transformation tags created in the previous step.

<Search><![CDATA[<staticValue>Great Outdoors</staticValue>]]></Search>

The text in bold italics is the text that is going to be searched for in the report specification. In report studio, text items such as titles are stored in the report specification between <staticValue> tags. So by including these tags in the search criteria only text items will satisfy the search criteria. Without these tags all references to Great Outdoors will match the search criteria, including data items. This is why it is important to identify the proper search string prior to attempting a transformation. The search tag also has a multi line attribute. Setting this attribute will cause the search to ignore line separators, allowing for better search. <Search multiline=”yes” ><![CDATA[<staticValue>Great

Outdoors</staticValue>]]></Search>

15


However, the multiline attribute is not needed for this example, so the file should now represent the following: <?xml version="1.0" encoding="UTF-8"?>

<Transformations>


Outdoors'">


</Transformation>

</Transformations>

6. Insert the following line after the search tags created in the previous step.

<Replace><![CDATA[<staticValue>Super Fantastic

Outdoors</staticValue>]]></Replace>

The text in bold italics is the text that is going to replace every report specification occurrence of the text specified by the search tag added earlier. Again, if the replace value is incorrect, there is potential to apply an unwanted change to all the report objects that were selected to be transformed.

16


The replace tag also has an escape attribute. Setting this attribute will cause the replace to escape the text to be replaced. This attribute is useful when attempting to update JavaScript embedded into the report specification. <Replace escape=”yes” ><![CDATA[<staticValue>Super Fantastic


However, the escape attribute is not needed for this example, so the

file should now represent the following:


<Transformations>


Outdoors'">


<Replace><![CDATA[<staticValue>Super Fantastic


</Transformation>

</Transformations>

7. The transformation file is now complete, save the file with a .xml extension and close Notepad.

17


4 Doing a Transformation from Beginning to End

The following section will step a user through an example that changes the great outdoors logos for all the report located under the Report Studio Report Samples Folder imported with the Cognos_Samples.zip sample deployment. Prior to beginning the steps in this section, it is mandatory that a valid backup of the existing IBM Cognos 8 content is taken via a supported and proven method.

4.1 Installing and Launching DRU The section below will step a user through the install and configuration procedure required to use DRU.

1. Unzip the utility to a physical location on the disk. For this example the location will be D:\Utilities.

2. After a successful unzip, using windows explorer, browse into the D:\Utilities\

ReportSpecUpdater location.

18


3. Make a backup copy and then open the runme.bat file in Notepad. Prefix the JAVA command with the path of the JRE bin. For this example, the path is going to be: "D:\Apps\Program Files\cognos\c83_116_12\bin\jre\1.5.0\bin\" The completed runme.bat file should represent the following: @echo off

"D:\Apps\Program Files\cognos\c83_116_12\bin\jre\1.5.0\bin\"java -jar

ReportSpecUpdater.jar

4. Save the changes and close the Notepad application. 5. Launch DRU by double clicking the runme.bat file.

19


4.2 Creating the Required Transformation File This section will step a user through identifying the search criteria for a transformation file from within a Report Studio specification. This section will also provide the transformation file syntax required perform the image transformation.

1. Within Cognos Connection traverse to the following location: Public Folders\Go Data Warehouse (query)\Report Studio Samples.

2. Open the Bursted Sales Performance Report in Report Studio.

3. Click on the Great Outdoors image at the top left hand side of the report to display the image properties.

20


4. Within the bottom left hand Properties pane, locate the URL property under

the URL Source section.

5. Record the URL property, ..\samples\images\logo_great_outdoors.gif for later use.

6. From the Tools menu, select Copy Report to Clipboard. 7. Open Notepad, and paste the contents of the clipboard. 8. Using the Edit\Find command from the Notepad menu, locate the

logo_great_outdoors.gif entry. This image reference will become the search criteria of the transformation file.

21


9. Create a new Notepad file with the following content:


<Transformations>

<Transformation id="Change Outdoors Image">

<Search><![CDATA[logo_great_outdoors.gif]]></Search>

<Replace><![CDATA[yellow.jpg]]></Replace>

</Transformation>

</Transformations>

10. Save the contents out as

D:\Utilities\ReportSpecUpdater\MyTransformations\ImageChange.xml. As per the requirement at the beginning of this section, this transformation will replace all references to logo_greate_outdoors.gif with yellow.gif.

22


4.3 Applying the Transformation to Existing Content Now that the transformation file is complete, it can be used to alter the existing IBM Cognos Connection content. Within DRU:

1. Enter the appropriate Dispatcher URI, for this example the URI will be http://localhost:59300/p2pd/servlet/dispatch

2. The IBM Cognos 8 environment being used in this example is secured. So the Anonymous check box needs to be unchecked. Uncheck the Anonymous checkbox.

3. Enter the valid credentials for an existing namespace. For this example the user name will be Administrator. The password will be admin and the Namespace will be Default. The completed Dispatcher setting should display as follows.

23


4. Click the Connect button. The application will connect and populate the

Content Folders section as follows.

5. Traverse the left hand tree structure to the following location: Public Folders\Go Data Warehouse (query)\Report Studio Samples.

6. Ensure the Report Studio Samples Folder is selected within the left hand tree.

7. Click the Load button and browse to the D:\Utilities\ReportSpecUpdater\MyTransformations\ImageChange.xml created in the previous step.

24


8. Uncheck the Do NOT write to CM check box and leave the Overwrite Existing

Reports unchecked. With these settings, the original reports will be left in tact and the updated reports will be written to the same location with the original name suffixed with a –new. This approach is only suggested for a small number of reports. When updating a large number of reports, it is recommended that the reports are written to disk first and validated prior to removing the Do NOT write to CM checkbox.

9. Uncheck all checkboxes under Content type except Report. 10. Press the Run button.

25


When the transformation run completes successfully the LogOutput should display the following output:

Using Log File: RSULog20080421_082039.txt

Connecting to: http://localhost:59300/p2pd/servlet/dispatch

Logging in as: Default: Administrator

connected

Starting Transformation Run: 2008/04/21 08:21:08

Traversing: /content/package[@name='GO Data Warehouse

(query)']/folder[@name='Report Studio Report Samples']...

Transformation Run Complete: 2008/04/21 08:21:09

Statistics for last run

Execution Time (seconds): 1

Transformation Time (seconds): 0

Number Of Specifications Processed: 8

Number Of Reports: 8

Number Of Queries: 0

Number Of Analysis: 0

Number Of Transformations Performed: 8

Number Passed: 8

Number Fail: 0

At this point, the original reports under the Report Studio Sample folder should remain unchanged. The reports with the updated images, should be visible in the same folder, with the original name suffixed with a – new as illustrated below.

26


The image change can be verified by executing the Bursted Sales Performance Report –new.

27


5 Writing JAVA Regular Expressions and Using DRU

Before you can create your own Transformations, an understanding of JAVA1 regular expressions is required. Suggested Web Sites for understanding include:

• http://java.sun.com/docs/books/tutorial/essential/regex/ o Highly recommended intro

• http://java.sun.com/j2se/1.4.2/docs/api/index.html o Java Doc

• http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html o Especially this page for a discussion of pattern match

characters • http://www.regular-expressions.info/java.html

o Interesting web site As transformations are written in an xml document, the CDATA element is used to contain the search and replace strings. A CDATA section starts with <![CDATA[ and ends with ]]>, the syntax and structure of which must be preserved.

1 There may be differences between regular expression rules between various programming languages. Ensure your information sources deal specifically with JAVA regular expressions.

28


Also, ensure you have a clear understanding of the xml report specification you are changing. While DRU allows you to modify the report specifications from Report Studio, Query Studio, Analysis Studio and PowerPlay, only the report studio specification is documented so you need to be careful before modifying existing reports. You should thoroughly test your transformations by saving modified reports to the local file system before overwriting existing reports and of course, you must backup your Content Store lest a problem arises. The following appendixes show some sample transformations. These are intended for education purposes only as they have not been fully tested.

29


6 Appendix A: Sample Style Transformation

This set of 3 transformations will change the styling in a report by changing all occurrences of

• “:tea” (teal) to “:red” • Adding a style to the ListColumnBody object • Adding a style to the ListColumnTitle object

These transformations assume that the string “:tea” appears in no other context in the report and that no styles have been applied to these ListColumnXXX objects. <?xml version="1.0" encoding="UTF-8"?>

<Transformations>

<Transformation id="Convert the color Teal to Red">

<Search><![CDATA[:teal]]></Search>

<Replace><![CDATA[:red]]></Replace>

</Transformation>

<Transformation id="Make all columns Blue">

<Search><![CDATA[<listColumnBody><style>]]></Search>

<Replace><![CDATA[<listColumnBody><style><CSS value="background-

color:blue"/>]]></Replace>

</Transformation>

<Transformation id="Make all columns Headings Yellow">

<Search><![CDATA[<listColumnTitle><style>]]></Search>

<Replace><![CDATA[<listColumnTitle><style><CSS value="background-

color:yellow"/>]]></Replace>

</Transformation>

</Transformations>

</xml>

30


7 Appendix B: Sample Image Transformation

This set of 3 transformations will change the image references in a report by changing all occurrences of

• “.jpg” to “.png” • “.png” to “.jpg” • “.gif” to “.png”

These transformations assume that the strings “.jpg”, “.png” and “.gif” appear only in valid contexts such as images names (xxx.jpg) The search predicate uses \. To escape the period “.” . Otherwise, it would be interpreted as Any Character by the Java Regular Expression parser.


<Transformations>

<Transformation id="Convert .jpg to .png">

<Search><![CDATA[\.jpg]]></Search>

<Replace><![CDATA[.png]]></Replace>

</Transformation>

<Transformation id="Convert .png to .jpg">

<Search><![CDATA[\.png]]></Search>

<Replace><![CDATA[.jpg]]></Replace>

</Transformation>

<Transformation id="Convert .gif to .png">

<Search><![CDATA[\.gif]]></Search>

<Replace><![CDATA[.png]]></Replace>

</Transformation>

</Transformations>

</xml>

31


8 Appendix C: Sample Text Transformation

This set of 3 transformations will change the string objects in a report by changing all occurrences of

• “<staticValue>Cognos” to “<staticValue>IBM” • “<staticValue>My Report” to “<staticValue>Your Report” • “<staticValue>Great” to “<staticValue>Good”

These transformations assume that the strings “jpg”, “png” and “gif” appear in no other context in the report. These transformations are designed to operate on static text values found in a report such as a title. The xml report specification would appear as so: <textItem> <dataSource> <staticValue>Cognos</staticValue> </dataSource> </textItem> With the Bolded portion being replaced by the first transformation to: <textItem> <dataSource> <staticValue>IBM</staticValue> </dataSource> </textItem>


<Transformations>

<Transformation id="Convert 'Cognos Internal' to 'IBM Internal'">

<Search><![CDATA[<staticValue>Cognos]]></Search>

<Replace><![CDATA[<staticValue>IBM]]></Replace>

</Transformation>

<Transformation id="Convert 'My Reports' to 'Your Reports'">

<Search><![CDATA[<staticValue>My Report]]></Search>

<Replace><![CDATA[<staticValue>Your Report]]></Replace>

</Transformation>

<Transformation id="Convert 'Great Outdoors' to 'Good Outdoors'">

<Search><![CDATA[<staticValue>Great]]></Search>

<Replace><![CDATA[<staticValue>Good]]></Replace>

</Transformation>

</Transformations>

32


9 Appendix C: Sample JavaScript Transformation

This first of these 2 transformations has the search predicate “for.*?pageNavigationObserverArray.*?\n” which will match:

• The string “for” o for

• Followed by any number of characters o .*?

• Followed by pageNavigationObserverArray o pageNavigationObserverArray

• Followed by any number of characters o .*?

• Followed by a new line o \n

And replace this content with an entirely new JavaScript script. In the second transformation, the \s is used to match white space such as Tab, Space, Multiple Spaces etc.


<Transformations>

<Transformation id="Remove the for-loop with a function to enable

the ValidatePage onclick event">

<Search><![CDATA[for.*?pageNavigationObserverArray.*?\n]]></Search>

<Replace escape="yes"><![CDATA[function initValidatePageInt()

{

var aButtons = document.getElementsByTagName("button");

if (aButtons && aButtons.length)

{

for (var i=0; i<aButtons.length; i++)

{

if (aButtons[i].onclick.toString().indexOf('finish')>0)

{

aButtons[i].onclick=ValidatePage;

}

}

}

}

setTimeout(initValidatePageInt, 250);

]]></Replace>

33


</Transformation>

<Transformation id="Change the with document.formRequest to oForm =

getFormWarpRequest">

<Search><![CDATA[with.{1,5}\(document.formWarpRequest\)\s*\n]]></Sea

rch>

<Replace escape="yes"><![CDATA[var oFORM =

getFormWarpRequest();\nif (oFORM)\n]]></Replace>

</Transformation>

</Transformations>

Date post:	07-Apr-2015
Category:	Documents
Upload:	raymund-prieto
View:	140 times
Download:	5 times

Cognos Pp Development Dynamic Report Spec Updater User Guide

Documents