IBM Cognos Content Manager QueryStudio - Import - 7.1

Talend Data Catalog Bridges

author
Talend Documentation Team
EnrichVersion
7.1
EnrichProdName
Talend Big Data Platform
Talend Data Fabric
Talend Data Management Platform
Talend Data Services Platform
Talend MDM Platform
Talend Real-Time Big Data Platform
EnrichPlatform
Talend Data Catalog

Bridge Requirements

This bridge:
  • requires the tool to be installed to access its SDK.

Bridge Specifications

Vendor IBM
Tool Name Cognos Content Manager QueryStudio
Tool Version C8 v8.3 to C11
Tool Web Site http://www.ibm.com/software/analytics/cognos/
Supported Methodology [Business Intelligence] Metadata Repository, BI Report (Dimensional Source, Expression Parsing, Report Structure) via Java API
Incremental Harvesting
Multi-Model Harvesting
Remote Repository Browsing for Model Selection
Data Profiling

BRIDGE INFORMATION
Import tool: IBM Cognos Content Manager QueryStudio C8 v8.3 to C11 (http://www.ibm.com/software/analytics/cognos/)
Import interface: [Business Intelligence] Metadata Repository, BI Report (Dimensional Source, Expression Parsing, Report Structure) via Java API from IBM Cognos Content Manager QueryStudio
Import bridge: 'CognosRnReportRepositoryImport.CognosRnQueryStudioReportRepository' 10.1.0

BRIDGE DOCUMENTATION
See bridge parameters for details on configuring this bridge.

WARNING: In order to access the Cognos Content Manager its web services must be fully operational, which may involve networking proxy and firewall setup. Make sure you first try connecting to 'http://localhost/c8/cm_tester.htm', or 'http://localhost:9300/p2pd/cm_tester.htm' in Cognos 10.2, where localhost is substituted with the appropriate IP name and port, a utility provided by Cognos before attempting any use of this bridge. Please read the 'Dispatcher URL' parameter documentation for more details, and contact your Cognos administrator or Cognos support, if necessary. This bridge will not work if the cm_tester is not fully operational.


FREQUENTLY ASKED QUESTIONS (FAQs)
Q: Why are there multiple versions of a given package extracted from Content Manager?

A: Any given Cognos design model may be edited/updated in Cognos Framework Manager (FM), and then published as a new version of an FM Package in Content Manager (CM). The full Cognos development life cycle process requires one to then migrate any related reports to use this new version of the FM package in CM. If that migration is not completed for all such reports, some reports may still use an old version of a package, some old versions of a package may no longer be used (and therefore should be removed), and /or some new versions of a package may not be used yet by any version. If so, multiple versions of a package might still be used by different reports and thus imported.

Q: How can I extract only the latest version of a package from Content Manager?

A: One may extract only the latest version of a package by selecting a single package in the 'Content' parameter (e.g. '/content/package[@name='GO Sales and Retailers']/model), and by setting the 'Add dependent objects' parameter to 'False'. In such a case, only the latest version of that package will be extracted.

In addition, one may use the FM Package bridge, which imports only one package at a time. In this case, only the latest version of that package will be imported.

Q: If the import log shows warnings 'Could not get model reference for Report XXX', what does it mean?

A: It is possible that repository report metadata may not have a valid reference to the report's or query's model.
It may help to open that report or query in Report or Query Studio and simply re-save it without making any changes.
That will update the metadata references in the repository. After re-saving, try to import the report or query in question again.
It is also possible that the model which the report or query is based upon is no longer accessible (i.e. got deleted, renamed etc.).
In this case try to have the report or the query fixed to refer to the correct model.

Q: What Cognos Java libraries are necessary at runtime?

A: The bridge uses Java libraries located in folder: MIMB_HOME/java/CognosRepository
Starting with Cognos version 10.2.x, the Java libraries are no longer mixed-version compatible: they must exactly match the Cognos server version.
In case the default provided libraries do not work for your particular version of Cognos server, you should replace them:
* Download the 'IBM Cognos Software Development Kit' software package from the IBM web site, and make sure to select the exact version matching your server (e.g. 11.0.5)
* Install the Cognos SDK software package on the machine running the bridge
* Locate the Java libraries in the SDK, for example: /ibm/cognos/sdk/sdk/java/lib
* Configure the bridge parameter 'Cognos SDK directory' to point to this directory path.
Starting with Cognos version 11.1, the Software Development Kit is now installed by default with Cognos Analytics server.

SUPPORT

Q: How do I provide IBM Cognos metadata to support team to reproduce an issue?
A: You need to export your metadata from IBM Cognos 8.4 or IBM Cognos 10 server into a ZIP archive following these steps:
1) Connect to the IBM Cognos Connection using Web browser.
2) Click 'Launch'->'IBM Cognos Administration'.
3) Click 'Configuration'.
4) Click 'Content Administration'.
5) Click on the 'New Export' icon. The New Export wizard appears.
6) Type a unique name and an optional description and screen tip for the deployment specification. Select the folder where you want to save it and click Next.
7) Choose whether to export the entire content store or to do a partial export of specific folders and directory content.
Note: please avoid exporting the whole content store as generally it is not needed, and because restoring this type of export may erase the destination server content store.
To export specific folders and directory content, click Select public folders and directory content, and then click Next.
8) In the Select the 'Public folders' content page, click Add.
9) In the Select entries page, in the 'Available Entries' box, select the packages or folders that you want to export.
You can browse the 'Public Folders' hierarchy and choose the packages and folders you want.
Click the right arrow button to move the selected items to the 'Selected entries' box, and click 'OK'.
10) Under 'Options', select whether you want to include the report output versions (not required), run history (not required), and schedules (not required) and what to do with entries in case of a conflict. Click 'Next'.
11) In the 'Select the directory content' page, select whether you want to export Cognos groups and roles, distribution lists and contacts, and data sources and connections and what to do with the entries in case of a conflict. It is not required to export Cognos groups and roles and distrtibution lists and contacts.
12) Click Next.
13) In the 'Specify the general options' page, select whether to include access permissions and references to namespaces other than IBM Cognos, and who should own the entries after they are imported in the target environment.
It is highly recommended NOT to include access permissions and references to namespaces other than IBM Cognos.
It is also recommended that Entry ownership is set to the user performing the import.
14) Specify the Recording Level for the deployment history. Default is Basic. 'Trace' saves all deployment details but requires the most memory. Click Next
15) In the Specify a deployment archive page, under Deployment archive, select an existing deployment archive from the list, or type a new name to create one.
If you are typing a new name for the deployment archive, IBM Cognos recommends that you do not use spaces in the name.
If the name of the new deployment specification matches the name of an existing deployment archive, the characters _1, _2, _3, etc. are added to the end of the name.
16) Click Next.
17) Review the summary information and click 'Next'. If you want to change information, click 'Back' and follow the instructions.
18) Once you are ready to export the archive, select the action you want:
To run now or later, click Save and run once and click Finish. Specify the time and date for the run. Then click Run. Review the run time and click OK.
To schedule at a recurring time, click Save and schedule and click Finish. Then, select frequency and start and end dates. Then click OK.
To save without scheduling or running, click Save only, and then click Finish.
19) After you run the export, send the produced ZIP archive to support team. The export can result in a single ZIP file or a multi-volume ZIP archive
The exported archive is usually located on the server in 'C:\Program Files\cognos\c8\deployment' directory
Please read IBM Cognos documentation for more details about exporting metadata from your version of Cognos.


Bridge Parameters

Parameter Name Description Type Values Default Scope
Version Select the version of Cognos server you want to import from. ENUMERATED
Auto detect
Cognos 11.x
Cognos 10.x
Cognos 8.4
Cognos 8.3
Cognos 8.1 to 8.2
Cognos ReportNet 1.x
Auto detect  
Dispatcher URL Enter the URI used by the Framework Manager, Metrics Designer or SDK to send requests to Cognos.

This URI typically corresponds to the External dispatcher URI of one of the dispatchers in your installation. It must use the real network host name or IP address instead of localhost. If Framework Manager, Metrics Designer or SDK clients connect to Cognos through an intermediary like a load balancer or proxy, specify the host and port of the intermediary. Cognos must be able to locate a gateway or dispatcher running on a Web server that supports chunking and attachments to handle large volumes of data. If there is no firewall between users and Cognos, components use the default setting. If there is a firewall, you must have access to at least one Web server that supports chunking outside of the firewall. The http or https protocol prefix indicates if SSL is required. You can find the real value in the Cognos installation directory in configuration\cogstartup.xml file.

Example:
<crn:parameter name='sdk'>
<crn:value xsi:type='xsd:anyURI'>http://localhost:9300/p2pd/servlet/dispatch</crn:value>
</crn:parameter>

To test the connection please first connect to the Cognos Content Manager via a Web browser to make sure it is accessible from the client machine. If Cognos Content Manager is running and accessible, you will see a status page. The state of the server must be 'running'. Example of the test URL: http://localhost:9300/p2pd/servlet

To test if your authentication parameters work use the Web client based tool from Cognos which allows one to verify the connection and authentication availability. Sample URL is:
for version 8.x: http://localhost/c8/cm_tester.htm
for version 10.x: http://localhost:9300/p2pd/cm_tester.htm
for version 11.x: http://localhost:9300/p2pd/cm_tester.htm


Accessing Cognos via SSL/HTTPS.

In order to connect to Cognos via SSL you need to import SSL certificate from Cognos server onto the machine where MIMB is run.
The procedure below provides the necessary steps.
1. Export SSL certificate from Cognos server machine using ThirdPartyCertificateTool.
On the Cognos server machine, go to <cognos_install>/bin directory and find ThirdPartyCertificateTool.bat on Windows machine, or ThirdPartyCertificateTool.sh on UNIX.
<cognos_install> is the directory where Cognos server is installed, e.g. for Cognos 10 it would be C:\Program Files\ibm\cognos\c10.
The examples below are for Windows machine, for UNIX use equivalent commands.
2. Run the tool to export certificate with the following command line:
ThirdPartyCertificateTool.bat -E -T -r cogcert.cer -k "<cognos_install>\configuration\signkeypair\jCAKeystore" -p password
As value for the password provide the password which is defined in Cognos Configuration for 'Certificate Authority key store password'.
If you have not changed this value, the default is "NoPassWordSet" (without quotes).
If you can't remember the password you can do an export of your configuration (described in KB 1030350) and open the exported configuration file in an editor.
Search for 'certificateAuthorityKeyFilePassword' and you will find the value for this password.
The cogcert.cer will contain the certificate we need. So copy it over to the machine where MIMB is run.
3. On the MIMB machine, using the java keytool, create a private keystore by importing the certificate exported above:
keytool -importcert -file cogcert.cer -alias Cognos10 -keystore "${MODEL_BRIDGE_HOME}\jre\lib\security\cognos" -storepass cognos
When you are asked if you want to trust this certificate, confirm with 'yes'.
The new keystore will be created under "${MODEL_BRIDGE_HOME}\jre\lib\security" and named cognos.
You can import multiple certificates into that same keystore (e.g. from multiple servers), and even from different versions of Cognos.
Just give each new certificate a unique alias within that keystore.
4. Now you should be able to run MIMB and connect to Cognos via SSL.


Testing HTTPS/SSL connections.

Connectivity to Cognos BI server can be tested with GUI-based Content Manager Browser diagnostic tool.
The tool is available for download from IBM site free of charge:
https://www-304.ibm.com/connections/blogs/basupportlink/entry/ibm_cognos_bi_content_manager_browser_diagnostic_tool2?lang=en_us
The tool provides detailed information about all objects and properties in the Content Manager database and can work over both secure and non-secure HTTP connections.

How to enable HTTPS/SSL in CM Browser.
a. Download the CM browser archive according to your machine version (32bit or 64bit) and extract it into a separate directory (for example, you can name the directory CM_Browser).
b. In the CM_Browser directory find the file that reads like this: IBMCognosBI_CMBrowser.ini
c. Inside that file, below any existing lines, add 2 properties as follows - place each property on a new line:
-Djavax.net.ssl.trustStore=<mimb_home>jre\lib\security\cognos
-Djavax.net.ssl.trustStorePassword=cognos

See p.3 in the above description regarding the creation of the client certificate store.
The first added property should simply point to that store.
d. Run IBMCognosBI_CMBrowser.exe, click on the first yellow key icon and set up connection parameters for your Cognos server:
Content Manager URL, Namespace, Username and Password.
e. When you are done press Login button to connect to the server.
If login is successful you will be able to browse the contents of the Content Manager database.
If login failed correct any errors reported by the tool and try again.

MIMB uses a similar mechanism to enable HTTPS/SSL connectivity, so if the CM Browser connection succeeds then MIMB will likely to be able to connect as well.
STRING   http://localhost:9300/p2pd/servlet/dispatch Mandatory
Namespace A namespace defines a collection of user accounts from an authentication provider. See 'Authentication Providers' in the Cognos ReportNet Installation and Configuration Guide. Leave this parameter blank if Cognos authentication has not been configured. STRING      
User Enter the username which the bridge will use to log in. Be sure this user name has permissions to the objects you wish to import. Leave blank if Cognos authentication has not been configured.

This import bridge is warrantied to be read only and will never affect the IBM Cognos contents. It is therefore safe to attempt the initial metadata harvesting as 'Administrator' in order to ensure that the entire IBM Cognos content is extracted without any access permission issue. Eventually, the administrator can set up a 'read only' user or group as defined below.

IBM Cognos has five types of permissions (Read, Execute, Traverse, Write and Set Policy) which may be assigned or restricted for a given user, group or role. Of these, it is necessary to assure that the userid has the three permissions (Read, Execute and Traverse) assigned for all entries (folders, reports, queries, analysis, packages, connections,etc.) which are included in the import. Such permissions are indeed 'read only' and will not make any changes to the Cognos contents. Remember, many entries depend upon others, e.g., packages use connections, reports use packages, and so on.

Note, the common recommendation in the IBM Cognos documentation (Execute and Traverse) is not sufficient.

Data sources in IBM Cognos can be secured against multiple namespaces. In some environments, the namespace used to secure the data source is not the primary namespace used for access to IBM Cognos Connection. When the bridge tries to access an entry, such as a report, a query, or an analysis, that is associated with a data source secured against multiple namespaces, you must have specified a userid which has permissions for the required primary namespace.

Refer to the IBM Cognos documentation on permissions and security for more details.
STRING      
Password Enter the password associated with the username which the bridge will use to log in. Leave blank if Cognos authentication has not been configured. PASSWORD      
Report Specify the search path to a single report object. Example:
/content/package[@name='GO Data Warehouse']/report[@name='Current Assets']
REPOSITORY_MODEL     Mandatory
Incremental import Specifies whether to import only the changes made in the source or to re-import everything (as specified in other parameters).

True - import only the changes made in the source.
False - import everything (as specified in other parameters).

An internal cache is maintained for each metadata source, which contains previously imported models. If this is the first import or if the internal cache has been deleted or corrupted, the bridge will behave as if this parameter is set to 'False'.
BOOLEAN
False
True
True  
Transformer import configuration XML file that describes mappings between Cognos Content Manager data sources and PowerPlay Transformer models.
Multiple Content Manager data sources may refer to the same PowerCube which is generated from a signle Transformer model.
The bridge assumes 1:1 mapping between a PowerCube and the Transformer model.
Each <Model> element corresponds to a single Transformer model (.mdl or pyj) file and lists all Content Manager data sources that refer to that model's PowerCube.
Optionally it may list Impromptu Query Definition data sources (<iqd> child elements) that require specific database type other than the default.
The configuration file may have multiple <Model> elements.

XML format example:

<ImportConfiguration database="Teradata" dbVersion="1.0.0">
<!-- database: specifies default database for Impromptu Query Definition (IQD) SQL statements-->
<!-- dbVersion format: major version.minor version.release-->

<Model path="some directory\some model.mdl">
<!--Transformer model (.mdl or .pyj) -->
<cmDataSource name="some Cognos datasource name" />
<!-- List IQD data sources for databases other than default -->
<iqd name="Customers" database="Oracle" dbVersion="11.1.0"/>
<iqd name="Products" database="MS SQL Server" dbVersion="8.0.0"/>
</Model>

</ImportConfiguration>
FILE *.xml    
Cognos SDK directory Specify here the directory location of the Cognos SDK where to load Java libraries from.
For example:
C:\Program Files\ibm\cognos\sdk\sdk\java\lib
DIRECTORY      
Miscellaneous Specify miscellaneous options identified with a -letter and, if applicable, a value.
-r to remove the report pages and their graphical structure
STRING      

 

Bridge Mapping

Meta Integration Repository (MIR)
Metamodel
(based on the OMG CWM standard)
"IBM Cognos Content Manager QueryStudio"
Metamodel
CognosRnReportStudio
Mapping Comments
     
Attribute Column When a query uses a TabularSQL object, the Columns in use can be inferred by parsing the SQL statement
Name name  
BaseType   No datatype information is available in ReportStudio
Class Table When a query uses a TabularSQL object, the Tables in use can be inferred by parsing the SQL statement
CppClassType   Set to ENTITY
CppPersistent   Set to True
Name name  
ClassifierMap   ClassifierMap objects are used to hold the lineage of Query DataSets, ReportDataSets
Operation expression text can be a Cognos native expression or a SQL statement
Condition FrameworkManager Filter Condition are used to hold the lineage of Filters and WhereClauses for tabular DataSets
Name name  
DataAttribute QueryItem The QueryItems of each TabularSet, TabularModel, TabularSQL and TabularReference are imported as DataAttribute
Name name  
Position position  
DataSet Queries, Tabular Sets The query TabularSets, TabularModels, TabularSQL and TabularReference objects are imported as DataSets
Name name  
DatabaseSchema Database Schema When a query uses a TabularSQL object, such DatabaseSchemas can be inferred by parsing the SQL statement
Name name  
DerivedType   No datatype information is available in ReportStudio
DesignPackage FrameworkManager Namespace, ReportStudio Folder DesignPackages reflect the reporting objects organization hierarchy as in the ReportSudio Query Explorer panel, as well as the organization hierarchy of objects used from the FrameworkManager model as in the ReportStudio Model Explorer panel
Name name  
UserDefined   set to FALSE
Dimension FrameworkManager QuerySubject The QuerySubjects used by the report queries are imported as Dimension
Name name  
DimensionAttribute FrameworkManager QueryItems  
Name name  
FeatureMap   FeatureMap objects are used to hold the lineage of QueryItems DataAttributes, ReportDataAttributes
Operation expression text can be a Cognos native expression or a SQL statement
Filter FrameworkManager Filter The Filters used by the report queries are imported as Filters
Name name  
Hierarchy FrameworkManager Hierarchy Inferred from QueryItems expressions used in the report Queries
Name Name  
HierarchyLevelAssociation FrameworkManager Hierarchy and Level Inferred from QueryItems expressions used in the report Queries
Name Name  
Level FrameworkManager Level Inferred from QueryItems expressions used in the report Queries
Name Name  
LevelAttribute FrameworkManager LevelAttribute Inferred from QueryItems expressions used in the report Queries
Name Name  
Measure FrameworkManager QuerySubject measures Inferred from QueryItems expressions used in the report Queries
Name Name  
OlapSchema FrameworkManager Namespace An OlapSchema is created to represent all namespaces from FrameworkManager used in the report
Name name  
Report Report  
Name file name The report name can be retrieved from the Cognos Repository if the bridge runs via the Repository bridge
ReportAttribute Query Item The QueryItems actually used on the report pages
Name name  
Position position  
ReportAxis CrossTab axis available since Cognos version 8
Role horizontal or vertical axis  
ReportChart Chart Legacy charts (Cognos 8 and earlier), enhanced charts (Cognos 10)
ReportDataSet Query A query used by a report page
Name name  
ReportField Report Field display of a Query Item on a report page
Name name if available
ReportMatrix CrossTab  
ReportPage Report Page  
Name name  
ReportPageBody Report Page Body  
ReportPageFooter Report Page Footer  
ReportPageHeader Report Page Header  
ReportRectangle   Rectangles are generic objects used to represent various layout html structures such as Tables, Blocks, Images
ReportTable List  
ReportText Text, Label  
Value textual value  
StoreConnection Database Catalog When a query uses a TabularSQL object, such DatabaseCatalogs can be inferred by parsing the SQL statement
Name name  
StoreModel Report XML File The model is built using the elements contained in the report XML file
Name file name The report name can be retrieved from the Cognos Repository if the bridge runs via the Repository bridge