...

Upgrading SDK Applications to IBM Cognos 8 Proven Practice

by user

on
Category: Documents
2

views

Report

Comments

Transcript

Upgrading SDK Applications to IBM Cognos 8 Proven Practice
Proven Practice
Upgrading SDK Applications to
IBM Cognos 8
Product(s): IBM Cognos 8
Area of Interest: Development
Upgrading SDK Applications to IBM Cognos 8
2
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
[email protected] .
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
3
Contents
1
INTRODUCTION ............................................................................................ 4
1.1
PURPOSE ............................................................................................................4
2
WHERE TO START ......................................................................................... 4
3
GENERAL RECOMMENDATIONS.................................................................... 4
4
FUNCTIONALITY CHANGES – REQUIRED CODE CHANGES........................... 5
4.1
4.1.1
4.2
4.2.1
4.3
4.3.1
4.4
4.4.1
UPGRADE THE LIBRARIES .........................................................................................5
Recommendations .............................................................................................5
SDK APPLICATIONS CAN NO LONGER USE THE GATEWAY....................................................5
Recommendations .............................................................................................5
CANUSESDK CAPABILITY HAS BEEN REMOVED. ...............................................................6
Recommendations .............................................................................................6
STRICTER OPTIONS CHECKING ...................................................................................6
Recommendations .............................................................................................6
5
CHANGES TO THE REPORT SPECIFICATION................................................. 6
5.1
5.1.1
XML REPORT SPECIFICATION HAS CHANGED. .................................................................6
Recommendations .............................................................................................7
6
NEW SERVICES ARCHITECTURE – ADDITIONAL CODE CHANGES ............... 7
6.1
6.1.1
6.2
6.2.1
6.3
6.3.1
6.4
6.4.1
6.5
6.5.1
6.6
6.6.1
BIBUSHEADER INFORMATION NEEDS TO BE SHARED AMONG NEW SERVICES .............................8
Recommendations .............................................................................................8
DEPRECATED METHODS ......................................................................................... 10
Recommendations ........................................................................................... 10
SPECIFYING A SEARCHPATH AS A PARAMETER ............................................................... 10
Recommendations ........................................................................................... 10
RETRIEVING REPORT OUTPUT HAS CHANGED. ............................................................... 10
Recommendations ........................................................................................... 10
OUTPUT FORMAT OF OUTPUTPAGES MAY HAVE CHANGED ................................................. 11
Recommendations ........................................................................................... 11
C# (CSHARP) USES DIFFERENT NAMES FOR THE NEW SERVICES......................................... 11
Recommendations ........................................................................................... 11
7
RESOURCES................................................................................................. 11
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
4
1 Introduction
1.1
Purpose
The purpose of this document is to provide SDK developers a guideline for
upgrading existing IBM Cognos ReportNet (CRN) SDK applications to use the
IBM Cognos 8 SDK. It describes the various issues that an SDK developer
needs to be aware of when upgrading. This document is meant to be used in
conjunction with the IBM Cognos 8 SDK documentation, not to replace it. It
provides technical tips, techniques and proven practices that help ease the
upgrade process. The references made to the IBM Cognos 8 SDK and
associated documentation refer specifically to IBM Cognos 8.1 RTM.
2 Where to Start
The IBM Cognos 8 SDK documentation should be used as the starting point
for upgrading, specifically the chapter in the IBM Cognos 8 SDK Developer
Guide titled Upgrading ReportNet SDK Applications. This chapter contains
detailed code changes that are required for upgrading SDK applications. This
chapter is split into two sections. The first section, Required Code Changes,
contains information to get existing CRN SDK applications working in Cognos
8 with minimal code changes. The second section, Additional Code Changes,
introduces the SDK developer to the changes necessary to fully convert a
CRN SDK application to the IBM Cognos 8 model. To begin, it is
recommended the SDK developer make the minimal required code changes to
get SDK applications to run in IBM Cognos 8.
3 General Recommendations
When planning an upgrade of an existing SDK application the following are
some general recommendations to keep in mind.
•
•
•
•
Keep a running copy of existing CRN SDK applications. This includes
the source code.
Use a phased approach, with first phase involving making the
necessary changes described in Required Code Changes. Ensure the
changes made in the first phase are working before moving on to next
phase that will involve the work introduced in Additional Code
Changes. Thorough testing will help make sure the application runs
without run-time exceptions
If possible, upgrade one module or piece of the application at a time.
Use the existing CRN running copy of the SDK application as a
reference. This will help to isolate any upgrade issues that may arise.
Some methods have been deprecated in IBM Cognos 8. It is
recommended that all deprecated methods used in the SDK
application be identified and replaced with methods from the new
APIs and services. For a complete list of methods see the section
Product Suite Name Changes in the appendix Version 8.1 Release
Notes of the IBM Cognos 8 SDK Developers Guide.
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
5
4 Functionality Changes – Required Code Changes
In many instances, only a few administrative changes will be all that is
needed for the required code changes. These code changes include the
namespace update and the service configuration class name change. A
recompile will be necessary after these changes are made. There are
additional changes that may be required depending on the toolkit used for
developing and on the content of the SDK application.
The following details below are further explanation to some of the points that
are contained in the chapter Upgrading ReportNet Applications of the IBM
Cognos 8 SDK Developer’s Guide.
4.1
4.1.1
4.2
4.2.1
Upgrade the libraries
This one is straight forward but is a potential to cause problems if not
followed through properly. Adding the new references is a must but it is
equally important to remove the old CRN references.
Recommendations
• Java toolkit - If an IDE is used to develop the SDK application, the
path to the JAR files has to be changed to point to the new IBM
Cognos 8 jar files. If no IDE is used the CLASSPATH environment
variable must to be changed to include the new IBM Cognos 8 jar files
and the references to the old ones have to be removed.
• .NET – Remove the web reference to ReportNet and add a new
reference to the cognosdotnet.dll and cognosdotnetassembly.dll
needed for IBM Cognos 8. Please note that NET 2.0 is not supported
at this time. If using .NET 1.1 SP1, a Microsoft hot fix must be
applied. See the section titled SDK Installation and Configuration
Issues in the IBM Cognos 8 SDK Readme for more information.
• Visual Basic – The CRN.dll has changed from CRN and will be
deprecated in the next major release of IBM Cognos 8. Therefore we
recommend that the VB project be updated to remove references to
the CRN.dll. Register the new CDK.dll and add this as a reference to
the VB SDK project. In addition, IBM Cognos 8 SDK applications
written in Visual Basic require version 3.0 of the Microsoft SOAP
Toolkit to be installed.
SDK Applications can no longer use the gateway
Existing CRN SDK applications are allowed access to the IBM Cognos
gateway. However, for security reasons, an IBM Cognos 8 SDK application
can no longer connect to the default gateway. SDK applications must use the
internal dispatcher URI or a dedicated gateway. For more information see the
Upgrade Guide mentioned above.
Recommendations
• Connect directly to the dispatcher using the Internal Dispatcher URI
• Connect to a dedicated gateway that is configured to connect to the
dispatcher using the Internal Dispatcher URI
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
4.3
4.3.1
4.4
4.4.1
6
CanUseSDK capability has been removed.
Existing CRN SDK applications were previously secured with the CanUseSDK
capability with-in Cognos Connection. This capability is now obsolete and has
been removed from IBM Cognos 8. SDK applications and all internal SOAP
requests are now directed to the internal dispatcher /servlet/dispatch.
Recommendations
• Connecting to the internal dispatcher in IBM Cognos 8 as described in
4.2 provides the same security as connecting to the dispatcher in
CRN, where all users have the CanUseSDK capability.
Stricter options checking
In IBM Cognos 8 there is a stricter check on options that are passed to
methods. For example, the execute method will verify that the runOptions
passed to it are of the correct type. In CRN, invalid runOptions may have
been ignored. In IBM Cognos 8, calling the execute method with improper
runOptions will cause a fault to be thrown. A typical scenario that would
cause a fault to be thrown would be where IBM Cognos 8 is expecting a
runOptionInt to be passed in the array of runOptions and a
runOptionStringArray was passed instead.
Recommendations
• Fix all unresolved issues by verifying the options.
• Add fault handling code as required.
5 Changes to the report specification
5.1
XML report specification has changed.
In IBM Cognos 8, version 5 (V5) report specifications are used. However,
version 4 (V4) report specifications that were created with CRN will still run
and can continue to be stored in the Content Manager. This means that SDK
applications which currently retrieve, edit and potentially save back V4 specs
will continue to work as they did before. IBM Cognos 8 SDK applications can
run reports that use either the V4 or the V5 specification.
Report Studio will only work with V5 report specifications. Therefore, if a V4
report specification being used by a SDK application needs to be modified, it
will have to be done outside of Report Studio, manually or with a SDK
application that is aware of the V4 report specification.
Continuing to run V4 report specifications will cause IBM Cognos 8 to
automatically perform an internal conversion to a V5 report specification at
run-time just prior to the report being run. In general, this conversion will be
transparent.
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
7
In the IBM Cognos 8 SDK Developer Guide, the chapter titled Using Report
Specifications in the section Working with the SDK and the chapter titled
Report Specification Reference in the section SDK Reference Material contain
detailed information on report specifications.
5.1.1
Recommendations
• Do not upgrade report specifications first if there are SDK applications
that manipulate report specifications. Change the SDK application to
work with V5 before upgrading the V4 reports. It is important to note
that opening a V4 report in Report Studio and saving it in IBM Cognos
8 will automatically upgrade the report to V5.
• Upgrade SDK applications to use V5 report specifications.
• The sample <cognos8>/sdk/java/ReportUpgrade that was installed
with the IBM Cognos 8 SDK provides an example of how to upgrade a
report.
• Determine the version of the report specification is in IBM Cognos 8
before converting it. This must be done with using the SDK since the
IBM Cognos 8 tools will convert and save the report specification
automatically. To extract the report specification, an SDK application
will use the query method of the new ContentManagerService on a
report, query or reportView object to extract the specification
property. The value of the xmlns attribute in the <report> root
element is used to identify the report specification version
o V4 - xmlns=http://developer.cognos.com/schemas/report/1/
o V5 - xmlns=http://developer.cognos.com/schemas/report/2.0/
• An SDK application can convert report specifications by calling the
query method of the new ReportService with the option
reportServiceQueryOption.upgrade set to true.
• Validate the report specification using the validateSpecification
method.
• Compare the XML of the report specifications version in order to see
the changes.
6 New Services Architecture – Additional Code Changes
A new services architecture has been introduced in IBM Cognos 8 to replace
the existing CognosReportNetService. Some of the new services are the
ContentManagerService, the ReportService, the BatchReportService and the
JobService. In order to make use of the new services architecture, additional
and more detailed code changes are required. More information is available in
the chapter Upgrading ReportNet SDK Applications in the SDK Developer’s
guide under the section Additional Code Changes
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
6.1
6.1.1
8
BiBusHeader information needs to be shared among new services
Each of the new individual services contain a BiBusHeader object and the
BiBusHeader object is not automatically shared between services nor is it
inherited from other services. The BiBusHeader object contains among other
things a CAM passport, which is a unique security token that reflects user’s
session.
Unless anonymous access is enabled in IBM Cognos Configuration, the
security information contained in the BiBusHeader object is required in any
service that makes an API method call.
This security information in the BuBusHeader object is created automatically
when the logon method is called. The logon method is only available through
the new ContentManagerService. Once the logon method is called and the
BiBusHeader object is created, this value must then be copied or shared
among other service objects that will make method calls.
Recommendations
There are many ways to share the BIBusHeader. The following are some of
the established techniques,
•
Update each of the service objects that are required by the SDK
application after the logon method of the new ContentManagerService is
called. For example, in Java,
…
cmService.logon( ns, user, pswd );
…
//
//
Get the BiBusHeader from the contentManagerService
//
BiBusHeader CMbibus = null;
CMbibus = (BiBusHeader)((Stub) cmService).getHeaderObject("",
"biBusHeader");
//
//
Set the BiBusHeader of the other services to be the same
//
as the ContentManagerService
//
((Stub) reportService).setHeader("", "biBusHeader", CMbibus);
((Stub) batchReportService).setHeader("", "biBusHeader", CMbibus);
((Stub) jobService).setHeader("", "biBusHeader", CMbibus);
•
Create a “get” method for each service object that can be called before
the method gets called. Each of the new services would have their own
“get” method. The code inside each of the “get” methods would be very
similar to the code above. For detailed examples that implement this
technique, see the SDK samples located under the IBM Cognos 8 install
directory
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
•
•
Java - sdk/java/common/CRNConnect.java
C#- sdk/csharp/SamplesCommon/SamplesConnect.cs
Example of using the “get” method (Java):
…
AsynchReply oReply = getReportService().run( spSingle, parameters,
runOptions );
…
public ReportService_Port getReportService()
{
BiBusHeader bibus = null;
bibus = (BiBusHeader)((Stub) reportService).getHeaderObject("",
"biBusHeader");
//
//
If the reportService does not have a BiBusHeader, get one
//
from the contentManagerService
//
if (bibus == null)
{
BiBusHeader CMbibus = null;
//
//
Get the BiBusHeader from the contentManagerService
//
CMbibus = (BiBusHeader)((Stub) cmService).getHeaderObject("",
"biBusHeader");
//
//
Set the BiBusHeader of the reportService to be the same as
//
the contentManagerService
//
((Stub) reportService).setHeader("", "biBusHeader", CMbibus);
}
return reportService;
}
IBM Cognos Proprietary Information
9
Upgrading SDK Applications to IBM Cognos 8
•
6.2
6.2.1
6.3
6.3.1
6.4
6.4.1
10
A more advanced technique would be to create a wrapper class that
completely isolates the relationship between the BiBusHeader object
and the new services from the SDK application. The “get” methods
described above would likely be methods in this wrapper class. A welldesigned and well-tested wrapper class can be reused in any SDK
application simply by including it and allows for the main SDK
application to be completely unaware about the role of the
BiBusHeader in the new services architecture.
Deprecated methods
Some of the methods in IBM Cognos 8 have been deprecated. These
methods will continue to work for the time being but will be removed in a
later release.
Recommendations
• Deprecated methods should be replaced with the methods that are
part of the new services. For more information see the SDK
developer’s guide.
Specifying a searchPath as a parameter
With the CRN SDK, methods that take a searchPath as a parameter accept
the searchPath as a string. In IBM Cognos 8, the methods of the new
services that have the searchPath parameter require the searchPath to be
either a SearchPathSingleObject or a SearchPathMultipleObject.
Recommendations
• Replace all string references to a searchPath parameter with the
appropriate object.
Retrieving report output has changed.
When using the new run method to run a report, the way that report output
is retrieved has changed. The run method of the new ReportService returns
an asynchReply object and the output pages or output objects will be
contained in the Details property of the asynchReply object.
Recommendations
• Modifications to the way the output pages or output objects are
retrieved are needed. The following code snippet demonstrates how
to access the output.
AsynchReply = reply;
…
if (reply.getDetails()[i] instanceof AsynchDetailReportOutput)
{
AsynchDetailReportOutput oOutput;
oOutput = (AsynchDetailReportOutput)reply.getDetails()[i];
//
Use this if the output is returned directly
String [] reportOutput;
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
11
reportOutput = oOutput.getOutputPages();
//
Use this if the output is accessed via an output object
BaseClass[] outputObjs;
outputObjs = oOutput.getOutputObjects();
}
See the installed SDK samples sdk\java\runreport\reportrunner.java or
sdk\csharp\reportrunner\reportrunner.cs or documents such as KB
1007449 or KB 1005508 in the on-line knowledge base for more
information about running reports and retrieving the report output.
6.5
6.5.1
6.6
6.6.1
Output format of outputPages may have changed
The outputPages property still returns a string but the format of the string
may be different. Binary output such as PDF and XLS are now encoded in
base64 instead of being left in their original binary format.
Recommendations
• The report output may need to be decoded from base64 before it can
be used.
C# (CSharp) uses different names for the new services.
Due to conflicts in naming, the new services in C# will be slightly different
from other toolkits.
Recommendations
• In C#, append the name of the services with 1. For example, use
contentManagerService1 instead of contentManagerService.
7 Resources
IBM Cognos 8 SDK Samples installed with SDK.
On-line knowledge base SDK samples. The on-line knowledge base can be
accessed through the Cognos Software Services website. A login may be
required. Most knowledge base samples have been upgraded to include IBM
Cognos 8 implementations and are structured as follows,
• CRN – existing CRN sample
• cognos8Compatible – updated CRN sample with required code
changes only
• cognos8 – upgraded CRN sample to make use of the new services
architecture.
Comparing the different implementations of one or more samples is an
effective way to see how to transition an existing CRN SDK app into an IBM
Cognos 8 SDK app that makes full use of the new services.
IBM Cognos Proprietary Information
Upgrading SDK Applications to IBM Cognos 8
IBM Cognos Proprietary Information
12
Fly UP