Cognos Include/Exclude Options

There are two ways a user can filter extracted reports in Cognos scanner. Both of them can be used separately, but they can also be combined. We recommend that you learn about both to understand how they work. However, for the most of the use-cases, it can be more convenient to work only with the properties Included Reports ( cognos.extractor.include) and Excluded Reports ( cognos.extractor.exclude).

Important: Note that only report objects can be filtered. Despite the fact that you use the filtering correctly, you can yet see a lot of assets extracted and analyzed and the scans of larger Cognos Analytics environments can still take a few hours to complete.

This is how the scanner determines which reports will actually be extracted.

The scanner contacts the Cognos server and asks for the search paths of all reports that are matched by the Extracted Reports Search Path property. If the property is empty, it will return the search paths for all of them (recommended).
The scanner takes the list from the previous step and translates the search paths to human-readable locations such as GO Sales and Retailers/Documentation Reports/Order Product List Report.
The scanner applies the Included Reports filter and keeps only the paths that match in the list. If the Included Reports property is empty, it doesn’t do any filtering and the list stays the same.
The scanner applies the Excluded Reports filter and keeps only the paths that don’t match. If the Excluded Reports property is empty, it doesn’t perform any filtering and the list stays the same.

For an optimal user experience with the Cognos scanner, we recommend leaving the Extracted Reports Search Path property empty and using the Included Reports property to specify the folders or specific reports that you are interested in. You can also exclude some reports using the Excluded Reports property.

If you are interested in all the reports, leave all three properties empty.

Cognos Search Path

This section describes how the Extracted reports search path property (technical name cognos.extractor.searchPath) works.

Every Cognos report has its unique path that can look like this:

/content/package[@name='GO Sales and Retailers']/folder[@name='Documentation Reports']/report[@name='Order Product List Report']

Apart from the names of the folders in the folder hierarchy that the report is placed in, you can also see object types (package, folder, report) and the top-level location (content, which stands for the shared team content).

The search path mechanism is a Cognos feature for selecting specific reports whose path will match the search path. The Cognos scanner internally uses Cognos SDK. The endpoints that are directly responsible for returning report definitions take search path as one of the parameters. This means that the exact extracted reports search path that you provide will be sent to the Cognos server to be evaluated and will directly influence which reports will be extracted and analyzed.

You can find examples, and even the syntax, in the IBM documentation.

You’ve seen that the report’s search path is determined by its location in the Cognos server, but finding it is not straightforward. IBM Cognos Connection users can follow previously mentioned IBM Cognos documentation to find it. There is not much IBM Automatic Data Lineage can do to help with that, but at least the Cognos extraction textual logs list all the paths of the reports that were extracted. Those are all the reports matching the given extracted reports search path.

Included and Excluded Reports

Search Patterns

We realize that the search path mechanism is not optimal and wanted our users to specify the targeted reports in a more convenient way, which is why there are two additional properties that can be used for this purpose: Included Reports (cognos.extractor.include) and Excluded Reports (cognos.extractor.exclude).

The following example shows the format of these textual properties:

search_pattern1,search_pattern2,search_pattern3

This means that you can chain multiple search patterns separated by commas to try and match reports' paths. But this is not everything. We realized that search paths are quite complicated and that users often want to be able to specify parts of their folder hierarchy instead. For example, if a report Order Product List Report is placed in a folder named Documentation Reports and that folder is itself placed in another folder named GO Sales and Retailers in the team content space, the search path might look like this.

/content/package[@name='GO Sales and Retailers']/folder[@name='Documentation Reports']/report[@name='Order Product List Report']

But we, users, would expect something like:
GO Sales and Retailers/Documentation Reports/Order Product List Report

Or similarly, if the report was in a private user space (as in the following example, where a user named cognos is in a namespace called LDAP), the search path can look like this.

CAMID("LDAP:u:cn=cognos")/folder[@name='My Folders']/folder[@name='my reports']/report[@name='cubeBased1']

And the human-readable path we might expect would be LDAP/cognos/My Folders/my reports/cubeBased1.

That is why instead of trying to match the Cognos search paths of the reports, the search pattern tries to match these human-readable locations, like this.

Finds reports whose human-readable locations contain the search pattern
(Advanced) Treats the search pattern like a Java regular expression and finds reports whose human-readable locations are matched by it.

Regular expressions are a powerful matching mechanism that you can explore in more depth and are recommended for technically advanced users. Note that if the names of your folders or reports contain characters that are considered special in regular expressions (such as ., \ (, ), [, ], *, ?, “, ', and others) and you do intend to use the search pattern as a regular expression, you need to escape the characters in the report or folder names by placing a backslash character ("\) in front of all of them. See the following examples for more details.

Important: In the filter expression, mention only the names of folders and reports visible in Cognos Analytics under team content folder or under personal space. Do not use words such as "team content", "content", usernames or any other higher-level asset names for example: a connection name or a data source definition name.

Examples

Here are some examples of what you can type in the Included Reports and Excluded Reports properties:

GO Sales—Will match any reports which have “GO Sales” either as part of their name or part of some of the parent folders.
GO Sales,Measures—Will match any reports which have “GO Sales” or “Measures” either as part of their name or part of some of the parent folders.
GO Sales , Measures—Will match exactly the same reports as the previous one because spaces (and other non-printable characters) in the beginning and at the end of search patterns are trimmed before the pattern is used.
go sALEs, MEASURES—Will match exactly the same reports as the two previous examples because matching is case-insensitive just like the Cognos folder hierarchy. (You can't create two folders or reports whose name differs only in size.)
Sales/ReportJanuary,Sales/MyReports—Will match what is presumably a report called “ReportJanuary” in the folder “Sales” and also all reports that are in (what is likely) a folder “MyReports”, which is also in “Sales”. If there are additional subfolders of “Sales/MyReports” containing reports, it will match them as well (recursively—going as deep into the hierarchy as possible). Note that you should always use forward slash “/” character as a folder separator.
.*GO Sales.*—Will match any reports which have “GO Sales” either as part of the name or part of some of the parent folders. The .* sequences will be interpreted by the regular expression engine as “anything before” and “anything after”, respectively.
.*/Sales.*/ReportJanuary—Will match any reports named “ReportJanuary” that have any folder whose name starts with “Sales” in the location. This means, for example, that all these would be matched: Somewhere/SalesA/ReportJanuary, Sales/ReportJanuary, SalesUSA/abc/def/ReportJanuary.
/Sales.*/ReportJanuary—Will match the same reports as in the previous example. This is to demonstrate that .* is not needed at the beginning or the end of the search pattern that you intend to use as a regular expression. This is because the algorithm tries to find any occurrence of the pattern in the report’s path. (It doesn’t need to match the whole path.) To be 100% correct, this pattern (and the previous one as well) would not only match “ReportJanuary” reports but also any reports in the same folders whose name starts with “ReportJanuary” but is actually something longer.
/Sales(US|DE)/.*—Will match any reports that have a folder whose name is either “SalesUS” or “SalesDE” anywhere in their location. This includes, for example, reports SalesUS/reportA and SalesDE/2022/Q4/reportB.
Sales(US|DE)/My 1\. \(weird\?\) report \[en\]—Will match the report named “My 1. (weird?) report [en]” that is placed in a folder whose name ends with “SalesUS” or “SalesDE”. This example demonstrates the need to escape special regular expression characters (in this case ., (, ?, ), [, ] ), if you intend to use the search pattern as a regular expression (which is implied by the first part Sales(US|DE) ).