IBM Cognos Content Manager - 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:
  • is only supported on Microsoft Windows.

  • requires the tool to be installed to access its SDK.

Bridge Specifications

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

BRIDGE INFORMATION
Import tool: IBM Cognos Content Manager RN to C11 (http://www.ibm.com/software/analytics/cognos/)
Import interface: [Business Intelligence] Multi-Model, Metadata Repository, BI Design (RDBMS Source, OLAP Source, Dimensional Target, Transformation Lineage, Expression Parsing), BI Report (Relational Source, Dimensional Source, Expression Parsing, Report Structure) via Java API from IBM Cognos Content Manager
Import bridge: 'CognosRnRepository' 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      
Content browsing mode Specifies what will be retrieved when browsing for available content in the Cognos repository.
'Packages only' - The tree of Packages and Folders is retrieved. No reports are retrieved.
'Connections only' - The list of Connections is retrieved.
'All' - The tree of Packages, Folders, Queries and Reports is retrieved. This mode requires more time to complete on large repositories. This is the default.
ENUMERATED
Packages only
Connections only
All
All  
Personal folders Specify whether the personal folders, and the models and reports located in them should be browsed and imported.
Retrieving metadata from personal folders may be slower on some servers.
BOOLEAN
False
True
True  
Content Allows to reduce import scope to a set of objects smaller then the whole server content. The scope can be controlled by object type (e.g. Report) and location (e.g. Folder). The following object types are supported: Package, Folder, Model, Report, Query, Shortcut. The content string is a semicolon-separated list of individual Cognos search paths used to retrieve objects from Cognos. See the Cognos Documentation for full search path syntax.
Note that search paths that are trying to retrieve everything under a certain folder or even content root, are inefficient and may run for long time or even cause errors on Cognos server. It is recommended to use more specific search paths, like "//*[@objectClass='query' or @objectClass='report' or @objectClass='model']" instead of "//*".
Note that all path items in the list have all ';' and '\' characters replaced with '\;' and '\\' respectively to make sure that these special characters will not interfere with the list parsing.

Models may be retrieved using their package name. In case of multiple published versions the latest will be imported (e.g. '/content/package[@name='GO Sales and Retailers']/model').

Reports may be retrieved using their complete search path. A report path can be found using the 'View the search path' link on the report properties page.
Useful multi-query examples:
'//report' all reports
'/content/package[@name='GO Sales and Retailers']//report' all reports in package
REPOSITORY_SUBSET   //*[@objectClass='query' or @objectClass='report' or @objectClass='model'] Mandatory
Add dependent objects Add dependent objects to the initial selection of Cognos objects defined in Content.
'None' - Only the selected Cognos objects are imported.
'Packages referenced by selected reports' - When a report is selected, its source package is imported.
'All' - When a report is selected, its source package is imported; and when a package is selected, its dependent reports are imported. Note that this requires a complete scan of reports dependencies on the Cognos server.
ENUMERATED
None
Packages referenced by selected reports
All
Packages referenced by selected reports  
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  
Folder representation Specify how the folders from Cognos Framework Manager should be represented.
'Ignore' - The folders are ignored - this is the default selection.
'Flat' - The folders are represented as Diagrams. Their hierarchy is not preserved.
'Hierarchical' - The folders are represented as Diagrams and their hierarchy is preserved.
ENUMERATED
Ignore
Flat
Hierarchical
Ignore  
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      
Multiple threads Number of worker threads to harvest metadata asynchronously.
Leave the parameter blank to have the bridge compute the value, between 1 and 6, based on JVM architecture and number of available CPU cores.
Specify a numeric value greater or equal to 1 to provide the actual number of threads.
If the value specified is invalid, a warning will be issued and 1 will be used instead.
If you experience out of memory conditions when harvesting metadata asynchronously, experiment with smaller numbers.
If your machine has a lot of available memory (e.g. 10 Gb or more), you can try larger numbers when harvesting many documents at once.
Note that setting the number too high can actually decrease the performance due to resource contention.
NUMERIC      
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"
Metamodel
CognosRnRepository
Mapping Comments
     
ClassifierMap   The Mapping Models use many ClassifierMaps to connect QuerySubjects and Filters defined in FM models with QuerySubjects and Filters used in reports
Connection   Used to store stitching mappings between report models and FM package models
DirectoryStructureModel Repository  
Name name  
FeatureMap   The Mapping Models use many ClassifierMaps to connect QuerySubjects and Filters defined in FM models with QuerySubjects and Filters used in reports
Folder Folder, Package  
Name name  
NativeId searchPath  
MappingVersion   Used to store stitching mappings between report models and FM package models
ModelVersion Report, Package  
MultiModelVersion Repository  
StoreContent Report, Package  
Name name  
NativeId searchPath  
StoreModel FrameworkManager Model, ReportStudio Report All reports and models are imported using the FM and ReportStudio import bridges. See the respective bridges specification for details on metadata mapping of each tool.
Name name