IBM Cognos BI Reporting - Content Manager bridge reference

About this bridge

The IBM Cognos BI Reporting - Content Manager bridge supports Cognos BI Reporting Content Manager functionality in Cognos ReportNet and Cognos versions 8 to 8.4 and 10, including 10.2. The bridge imports a complete package of business intelligence (BI) models, BI reports, and related implemented data resources, such as database tables and columns.

You use the Assets to import parameter to import models, reports, and implemented data resources. You can also import cube-related metadata from Cognos PowerPlay Transformer by using the Transformer import configuration parameter. You can view data lineage for all the imported assets in InfoSphere® Information Governance Catalog.

Prerequisites

Ensure that the following prerequisites are met before you run the bridge:

To use the latest version of the bridge, you must install the prerequisite software.

Connectivity

Before you can access Cognos Content Manager, its web services must be operational. Setting up these web services might require working with the networking proxy and firewall.

To test the connection, connect to Cognos Content Manager by using a web browser to make sure that it is accessible from the client computer. An example URL is http://localhost:9300/p2pd/servlet. If Cognos Content Manager is running and accessible, you can see a status page. The state of the server must be running.

Before you use the bridge for imports, test if your authentication parameters work by using the web client tool from Cognos to verify the availability of the connection and authentication. Connect to http://localhost:port_number/c8/cm_tester.htm or, for Cognos 10.2, http://localhost:9300/p2pd/cm_tester.htm, substituting the appropriate IP name and port number. The bridge does not work if connection and authentication are not available at those addresses.

Cognos must be able to locate a gateway or dispatcher that is 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 whether SSL is required. You can find the value in the Cognos installation directory in the file configuration\cogstartup.xml file. For example:

<crn:parameter name="cdk"
<crn:value xsi-Type="xsd:anyURI">
http://localhost:9300/p2pd/servlet/dispatch</crn:value>
</crn:parameter>

Contact your Cognos administrator or Cognos support if necessary.

For more information on connecting to Cognos by using SSL, see the following technote http://www.ibm.com/support/docview.wss?&uid=swg21679093.

Permissions for users

IBM Cognos has five types of permissions: Read, Execute, Traverse, Write, and Set Policy. These permissions can be assigned or restricted for a user, group, or role.

Ensure that the user has the Read, Execute, and Traverse permissions assigned for all entries that are included in the import, (not just Execute and Traverse, as often recommended by the IBM Cognos documentation). Such entries include folders, reports, queries, analysis, packages, and connections. These permissions are read-only and do not change the Cognos contents. Many entries depend upon others. For example, packages use connections, reports use packages, and so on.

Data sources in IBM Cognos can be secured against multiple namespaces. In some environments, the namespace that is used to secure the data source is not the primary namespace that is used for access to IBM Cognos Connection. The bridge might need to access a report or other entry that is associated with a data source that secured against multiple namespaces. In such cases you must specify a user that has permissions for the required primary namespace. See the IBM Cognos documentation on permissions and security for more details.

Frequently asked questions

Why are multiple versions of a package extracted from Content Manager?

You can edit or update any design model in Cognos Framework Manager and publish it as a new version of a Framework Manager package in Content Manager. The Cognos development lifecycle requires that you then migrate any related reports to use this new version of the package in Content Manager. If you do not complete that migration for all such reports, some reports might still use an old version of a package. Remove old versions of a package that are longer be used. Some new versions of a package might not be used yet by any version. In such cases, multiple versions of a package might be used by different reports and thus imported.

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

Select a single package to import, and set the Add dependent objects parameter to False. Only the latest version of the package is extracted.

What should I do about import log warnings such as Could not get model reference for Report XXX?

The report metadata might not have a valid reference to the model that is based on the report or query. Open the report or query in Report Studio or Query Studio and save it without making changes, then reimport the report or query. Saving the report or query updates the references in the repository.

It is also possible that the model the report or query is based upon is no longer accessible, perhaps because it was deleted or renamed. In this case, fix the report or the query to refer to the correct model.

Troubleshooting

Import parameters

The Cognos BI Reporting - Content Manager bridge uses the following import configuration parameters.

Version

Required. Select the version of Cognos server that you want to import from. Select Cognos 10 to import from Cognos 10.1 or 10.2.

Options

• Cognos 10
• Cognos 8.4
• Cognos 8.3
• Cognos 8.1 and 8.2
• Cognos ReportNet 1

Dispatcher URL

Required. Type the URI that is used by the Framework Manager, Metrics Designer, or SDK to send requests to Cognos.

The value typically corresponds to the External dispatcher URI of one of the dispatchers in your installation, for example http://Server:9300/p2pd/server/dispatch. You must use the specific network host name or IP address instead of localhost. If the Framework Manager, Metrics Designer, or SDK clients connect to Cognos through an intermediary such as a load balancer or proxy, specify the host and port of the intermediary. For more information, see the bridge prerequisites.

Namespace

Leave blank if Cognos authentication is not configured.

A namespace defines a collection of user accounts from an authentication provider. See Authentication Providers in the Cognos ReportNet Installation and Configuration Guide.

User name

Type the user name to use if Cognos authentication is configured. Leave blank if Cognos authentication is not configured.

This import bridge is read-only and never affects the IBM Cognos contents. It is safe to attempt the initial metadata import as Administrator in order to ensure that the entire content is extracted without access permission issues. Eventually, the administrator can set up a read-only user or group. For more information, see the bridge prerequisites.

Password

Type the password if Cognos authentication is configured. Leave blank if Cognos authentication is not configured.

Content browsing mode

Specify what types of objects are retrieved when you browse the Cognos repository. To see all available content, select the default, All, which retrieves the tree of packages, folders, queries, and reports.

This parameter is used only if you browse for assets in the Assets to import field. It is not used if you type a content string that specifies search paths.

Assets to import

Required. Browse to select the assets that you want to import, or type a content string that specifies one or more search paths. Always select a smaller set of objects than the whole server content, which is the default.

Once you specify a selection, you can return to the previous page of the import wizard and test the data connection again, if desired, to make sure that you have permission to import all the assets that you selected.

A content string is a semicolon-separated list of individual Cognos search paths that are used to retrieve objects from Cognos. The following object types are supported: package, folder, model, report, query, and shortcut. See the Cognos documentation for the full search path syntax.

Search paths that attempt to retrieve everything under a certain folder or content root are inefficient. The import might run for a long time or cause errors on the Cognos server. Instead of using //*, use more specific search paths, such as these search paths:

• //*[@objectClass='query'
• @objectClass='report'
• @objectClass='model']

Use a backslash character (\) to escape each semicolon (;) and or backslash character in the content string. You can retrieve models by package name, for example /content/package[@name='GO Sales and Retailers']/model. If there are multiple published versions, the latest is imported.

You can retrieve reports by using the complete search path. To find the complete search path in Cognos, click View the search path on the properties page for the report. An example is /content/package[@name='GO Sales and Retailers']/folder[ @name='Documentation Report Samples']/report[@name='Create a Prompt'].

If a query returns multiple models or reports, only the last model or report is imported. The following queries return multiple reports:

• //report returns all reports
• /content/package[@name='GO Sales and Retailers']//report returns all reports in a package

Add dependent objects

Select whether to add dependent objects to the initial selection of Cognos objects that you selected with the parameter Cognos assets to import.

Options

None

No dependent objects are added.

Packages referenced by selected reports

The default. For each report you select, the source package is also imported.

All

When a report is selected, its source package is imported; and when a package is selected, its dependent reports are imported. This requires a complete scan of report dependencies on the Cognos server, which takes more time to complete on large repositories.

Incremental import

Keep this parameter selected. When you reimport from the same source, the bridge uses cached information to determine which objects did not change since the previous import. Only changed objects are retrieved from Cognos. Using the cached information can increase performance for large imports.

For new imports, or when the cache is deleted or corrupted, the bridge imports all objects from the source regardless of the selection that is specified.

Folder representation

Accept the default value, Ignore, which ignores folders from Cognos Framework Manager. The default automatically captures the Cognos server and the package or folder location of the report.

Transformer import configuration

To import cube-related metadata from Cognos PowerPlay Transformer, you can supply an XML file that describes mappings between Cognos Content Manager data sources and PowerPlay Transformer models. Choose whether to import the file from the metadata interchange server or the local computer. The bridge uses the connection information provided in the XML file to import the cube-related metadata. On import, relationships are established in the metadata repository between the cube assets and the related assets that you import by using the Assets to import parameter. You can view the data lineage of these assets in InfoSphere Information Governance Catalog

Multiple Content Manager data sources can refer to a PowerCube that is generated from a single Transformer model. The bridge assumes a one-to-one mapping between a PowerCube and the Transformer model.

Each <Model> element corresponds to a single Transformer model file with either .mdl or .pyj file extension. The <Model> element lists all Content Manager data sources that refer to the PowerCube for that model. Optionally, you can list Impromptu Query Definition data sources, which are <iqd> child elements that require a specific database type other than the default. The configuration file can have multiple <Model> elements.

XML format example:

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

  <Model path="directory_name\model_name.mdl">

  <!--Transformer model (.mdl or .pyj) -->
  <cmDataSource name="A_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>

Import from personal folders

Specify whether to import the models and reports that are in personal folders. Retrieving metadata from personal folders might take longer on some servers.

Worker threads

Specify the number of worker threads to retrieve metadata asynchronously from the source. For the most reliable performance, leave the parameter blank to have the bridge compute the default value based on JVM architecture and the number of available CPU cores.

If you need to experiment with increasing retrieval speed, specify a number from 1 to 6 to provide the actual number of threads. If the value specified is invalid, a warning is issued and the number 1 is used instead. If you experience out-of-memory conditions when importing metadata asynchronously, experiment with smaller numbers. If your computer has a large amount of available memory, for example, 10 GB or more, you can try larger numbers when retrieving many documents. However, setting the number too high can decrease performance due to resource contention.

Import joins

You can import joins that are defined in the BI model. By default, joins are not imported.

Import levels

You can import levels and hierarchies. When the option is selected, levels and hierarchies that are defined in the BI model are imported. By default, they are not imported.

Metadata consistency check

Perform a consistency check on the selected metadata before it is imported into the metadata repository. It is possible to save metadata in source tools in ways that cause problems when the assets are imported into the metadata repository or used in other tools. For example, a foreign key might have no connection to a primary key or to an alternate key. In some cases, the metadata might be so semantically inconsistent that the bridge cannot import it.

The metadata consistency check returns warnings and errors in the log file.

Basic check

The default. Performs the minimum consistency checks necessary to validate the metadata, including checking for missing relationships and foreign keys that are not connected to primary or alternate keys.

In some cases, the basic check might be more rigorous than necessary and you can ignore certain errors or warnings.

Detailed check

Performs the basic check plus more advanced semantic checks specific to the type of metadata that is imported. This level can be used when the source tool does not have the ability to validate the metadata.

No check

Use with extreme caution. Selecting this option could result in the import of duplicates or invalid identities and might cause serious problems with your use of suite tools and the metadata repository.

If an asset description already exists

Specify what action to take if an imported asset matches an existing asset in the metadata repository. You can keep the existing description, or overwrite the existing description with the description of the imported asset.

If either description is null, the non-null description is used, regardless of which option you specify. The default behavior is to replace the existing description.