Cognos Resource Configuration

Before you configure your scanner, make sure you meet the prerequisites. Read our guide on Cognos integration requirements to double-check.

Source System Properties

This configuration can be setup by creating a new connection on Admin UI > Connections tab or editing an existing connection in Admin UI > Connections > Reporting & BI > Cognos > specific connection. New connection can also be created via Manta Orchestration API.

One connection for Cognos corresponds to one Cognos Analytics server and its content store. Reports, Framework Manager models, and database connection information that are stored in the content store will be analyzed.

This automatic extraction requires a connection via Cognos SDK libraries, which use the Content Manager service internally. The service and the Cognos Analytics server need to be running.

Common Source System Properties

Property name	Description	Example
cognos.extractor.server	Name of a resource representing this Cognos Analytics server also known as a dictionary ID, used as an output subdirectory name for extracted definition files for reports and other objects	Cognos1
cognos.extractor.version	Version of Cognos — note that it should match both the server version and Cognos SDK version; choose between V10 for Cognos BI 10 and V11 for Cognos Analytics 11 and newer	V10 V11
cognos.extractor.dispatcherUrl	Gateway URL of Cognos server as specified in the Cognos configuration. You should always include the protocol (http/https), hostname or IP, port number, and endpoint assigned to the gateway (usually /bi/v1/disp). If there seem to be issues using the hostname, use the IP of the server instead.	`http://example.com:9300/bi/v1/disp`
cognos.extractor.anonymous	Value of true or false indicates if anonymous access has been allowed in the Cognos configuration	true false
cognos.extractor.searchpath	Cognos search path used to define reports extracted from the Cognos content store. If all reports should be extracted, leave this blank. In this case, the default `//report\|//interactiveReport` will be used. For the options and search path syntax check the Cognos documentation. It's also important to include the `report` or `interactiveReport` element in the path as the last element. This is shown in the example on the right. In this particular case, the extractor will download all reports and interactive reports located in the `/content/Samples` folder and its child folders.	/content/folder[@name='Samples']//report \| /content/folder[@name='Samples']//interactiveReport
cognos.extractor.include	Search patterns as individual entries, which will determine the reports to be extracted. The search pattern can be a regular expression or simply a report name or the name of a folder. See Cognos Include/Exclude Options for details.	`My Best Report, .Sales./ReportJanuary, My Folder, Sales(US\|DE)/my report 2022_.`
cognos.extractor.exclude	Search patterns as individual entries, which will exclude the reports from extraction. The search pattern can be a regular expression or simply a report name or the name of a folder. See Cognos Include/Exclude Options for details.	`Unfinished Report, .Sales.*/ReportDecember, Irrelevant Folder, Sales(US\|DE)/my report 2022_1`
cognos.extraction.method	Set to Agent:default when the desired extraction method is the default Manta Extractor Agent, set to Agent:{remote_agent_name} when a remote Agent is the desired extraction method, set to Git:{git.dictionary.id} when the Git ingest method is the desired extraction method. For more information on setting up a remote extractor Agent please refer to the Manta Flow Agent Configuration for Extraction documentation. For additional details on configuring a Git ingest method, please refer to the Manta Flow Agent Configuration for Extraction:Git Source documentation.	default Git agent
cognos.extractor.primaryLocale	Identifier of the main locale (language) that you want IBM Automatic Data Lineage to show you objects in. If you leave this property blank, the content language locale of the user account will be used.	en
cognos.extractor.otherLocales	Comma-separated identifiers of other locales your Cognos environment uses. It's best NOT to include the locale specified as `primaryLocale`. If you leave this blank, only the `primaryLocale` will be processed. Do NOT put spaces after the commas when entering this property.	de,cs-cz,fr
cognos.input.encoding	Encoding of the provided Cognos files. This is only necessary if the input has been served manually by the client. See Encodings for applicable values.	UTF-8

Using a Non-Anonymous Connection (User-Based Connection)

Each of the following properties is needed only if Cognos is configured to use a user-based connection instead of anonymous access.

Property name	Description	Example
cognos.extractor.anonymous	Set to false to use a user-based connection	false
cognos.extractor.user	User name for a connection to the content store	johnDoe
cognos.extractor.password	Password of the specified user	aPassword123!
cognos.extractor.namespaceID	Namespace ID that the user belongs to. The ID of a namespace can be found in the IBM Cognos Configuration, and the namespace itself can be found in the Administration console. Do not confuse the namespace ID with its name. In default Cognos installation, the Cognos user's namespace is pre-configured and its ID is "CognosEx".	CognosEx

Common Scanner Properties

This configuration is common for all Cognos source systems and for all Cognos scenarios, and is configure in Admin UI > Configuration > CLI > Cognos > Cognos Common. It can be overridden on individual connection level.

Property name	Description	Example
cognos.input.dir	Directory with files extracted from the Cognos Content Store	${manta.dir.temp}/cognos/${cognos.extractor.server}
cognos.manualInput.dir	Directory with inputs provided manually by a user	${manta.dir.input}/cognos/${cognos.extractor.server}

Dynamic Cubes

Providing Dynamic Cube Project Files

Dynamic cube definitions can't be fully extracted from the Cognos Content Store. Instead, Automatic Data Lineage needs Dynamic Cube Designer project files in the FMD format to be able to analyze dynamic cubes and process flows, both from physical sources and to reports. To the best of our knowledge, the project files only contain cube metadata and should not contain any sensitive information unless the tool is used in an unexpected way and the real data is somehow hard-coded into cube definitions, which we haven't encountered yet. These files can usually be found alongside the Dynamic Cube Designer installation files unless the storage settings were explicitly changed in the Designer. The FMD files need to be copied to <MANTAFLOW_INSTALLATION_DIRECTORY>/cli/input/cognos/${cognos.extractor.server}/cubeProject or any subdirectories. The path of the manually-provided files relative to the mentioned directory is important and will be used in a manual mapping, so we recommend keeping it simple for your own benefit. The process of mapping search paths presented by cube-based reports to their Cube Designer project file counterparts might require deeper knowledge and understanding of usage of Dynamic Cubes across cube-based reports.

Cognos scanner supports dynamic cubes (including virtual cubes) that are referenced from Framework Manager models as a dynamic source. There are no extra steps needed for a referenced cube to be registered by a Framework Manager model.

Cognos scanner analyzes dynamic cube projects that are manually provided, even if there is no report built upon them. Keep in mind that for a report to be connected to its dynamic cube projects, they still need to be manually linked as shown later.

Linking Reports with Dynamic Cube Project Files

In a report specification, the dynamic cube used is referenced by its published package's search path in the Cognos Content Store. The search path may look something like this.

/content/folder[@name='CompanyReports']/folder[@name='Data models']/folder[@name='Packages']/package[@name='SALES_US']/model[@name='model']

To ensure a report based on a dynamic cube is properly analyzed, the Cognos scanner needs to know the relation (mapping) between the search path of the dynamic cube and the location of the relevant Dynamic Cube Designer project file provided. This mapping needs to be manually provided as well. The process of setting up all the mappings might be tedious, which is inherently caused by limited Cognos SDK API capabilities. The time needed to set up all the necessary mappings is proportional to the number of cube-based reports.

The following example shows the file: <MANTAFLOW_INSTALLATION_DIRECTORY>/cli/input/cognos/${cognos.extractor.server}/cubeProject/searchPathMappingManual.csv with file contents that would correctly map the search path from the previous example to the manually provided dynamic cube project file named, for example, SalesUSCubes.fmd stored in <MANTAFLOW_INSTALLATION_DIRECTORY>/cli/input/cognos/${cognos.extractor.server}/cubeProject/abc.

SEARCH PATH,RELATIVE FILE PATH
/content/folder[@name='CompanyReports']/folder[@name='Data models']/folder[@name='Packages']/package[@name='SALES_US']/model[@name='model'],abc/SalesUSCubes.fmd

Note that the relative file path values need to use the slash character / as a directory separator independently on the operation system.

The searchPathMappingManual.csv file can also be created even before the analysis is run by a Automatic Data Lineage user, provided the structure of the file follows the expected format. However, for user convenience and better understanding of search paths that couldn't be matched with any Framework Manager model or a Dynamic Cube Designer project, Cognos analysis prints a helper CSV mapping file to the logs. This file is very similar to the searchPathMappingManual.csv file, both in name and format. It contains all the records from searchPathMappingManual.csv (if there were any), but the main benefit is that it also contains records with search paths that couldn't be matched with any of the Dynamic Cube Designer project files provided. Such records in the file look something like this.

/content/folder[@name='CompanyReports']/folder[@name='Data models']/folder[@name='Packages']/package[@name='SALES_US']/model[@name='model'],<empty file path>

There should be a record in the mapping file for each unique search path that points to a dynamic cube package. However, multiple search paths can be tied to a single Cube Designer project file, because the project files often contain multiple definitions of cubes that, when published, act as a separate package identifiable by a search path in the Cognos Content Store.

Recommended Usage Scenario

Defining manual mappings in searchPathMappingManual.csv is eased by using the contents of the autogenerated search path mapping in the logs. Simply copy its contents, and after that, the process of creating a correct mapping file is reduced to going through the records with <empty file path> and assigning the correct dynamic cube project file paths, while ensuring the original records copied from searchPathMappingManual.csv are correct. In the autogenerated mapping, it is possible to find search paths that identify Framework Manager models instead of Dynamic Cube project files. This can happen if, for any reason, the Framework Manager model wasn't successfully extracted, because report definitions don't differentiate between the search paths they use to identify relevant models or cubes. If you find this kind of record, simply erase it.

Copy all the Cube Designer project files used in reports to <MANTAFLOW_INSTALLATION_DIRECTORY>/cli/input/cognos/${cognos.extractor.server}/cubeProject or its subdirectories.
Run a Cognos analysis for the first time. Cube-based reports are NOT properly analyzed, but autogenerated helper file is printed to the logs and provides handy information.
Copy the contents of the helper file from logs to searchPathMappingManual.csv.
Go through the individual records and for each of them provide the correct mapping between the discovered search path and a Cube Designer project file. This step might require additional knowledge about which cubes are located in the project files and where they were published in the Cognos Content Store. If there are any records that identify Framework Manager models, erase them.
When searchPathMappingManual.csv is finalized, run the Cognos analysis again.
Check to see if there are any records in the helper file inside the logs that still have <empty file path>, and if you decide that any of them should be corrected, repeat steps 3 to 6.

Common Configuration Issues

Generally not adhering to searchPathMappingManual.csv structure.
This might lead to input/output errors when Cognos scanner attempts to read the file.
Using a separator other than a slash / for file paths in the searchPathMappingManual.csv file.
Again, IO errors or the files might simply not be found in the specified locations.
Incorrectly assigning a Cube Designer project file to a search path.
The logs will probably be silent until the dataflow analysis tries to match the report items with their cube counterparts. This will produce reports that don't have incoming data flows but have a lot of ReportAnalyzer class log warnings. If this happens, it is necessary to better analyze which cubes are used directly in Cognos by inspecting the particular report.
Using the absolute file path of the Cube Designer project files.
IO errors trying to find non-existent files.

Data Source Connections

Cognos scanner supports most Cognos data source connections. See the section "Known Unsupported Features" for details on which data source connections are not supported.

For most JDBC-based connections, Automatic Data Lineage is able to automatically match the Cognos data source connection to one of the configured databases. For Cognos data sources that don't use a JDBC-based connection (such as ODBC- or OLE-DB-based) and in some cases for JDBC connections, a manual mapping must be specified by the user.

If there are messages in the Cognos dataflow log similar to those in the following example, it means that a manual mapping will indeed need to be specified.
Connection [type=PostgreSQL, connectionString=jdbc:postgresql://192.168.0.16:5432/exampleDB, serverName=null, databaseName=null, schemaName=null, userName=null]

Cognos scanner should always produce a connectionString for the unmapped connection. However, if the data source definition is complicated, the connection string presented by Cognos scanner in the preceding message can be longer. It is always necessary to use the whole connection string (jdbc:postgresql://192.168.0.16:5432/exampleDB in the example) and match it to the connection ID in the manual mapping specification. See (Manual) Connection Mappings Explained for information about other properties and more details.