How to set up on-premises IBM Cognos Analytics access

In some cases you will not be able to expose your IBM Cognos Analytics instance for Atlan to crawl and ingest metadata. For example, this may happen when security requirements restrict access to sensitive, mission-critical data.

In such cases you may want to decouple the extraction of metadata from its ingestion in Atlan. This approach gives you full control over your resources and metadata transfer to Atlan.

Prerequisites

To extract metadata from your on-premises IBM Cognos Analytics instance, you will need to use Atlan's cognos-extractor tool.

Install Docker Compose

Docker Compose is a tool for defining and running applications composed of many Docker containers. (Any guesses where the name came from? 😉)

To install Docker Compose:

1. Install Docker
2. Install Docker Compose

Get the cognos-extractor tool

To get the cognos-extractor tool:

1. Raise a support ticket to get the link to the latest version.
2. Download the image using the link provided by support.
3. Load the image to the server you'll use to crawl IBM Cognos Analytics:

   sudo docker load -i /path/to/cognos-extractor-master.tar

Get the compose file

Atlan provides you with a Docker compose file for the cognos-extractor tool.

To get the compose file:

1. Download the latest compose file.
2. Save the file to an empty directory on the server you'll use to access your on-premises IBM Cognos Analytics instance.
3. The file is docker-compose.yaml.

Define IBM Cognos Analytics connections

The structure of the compose file includes three main sections:

• x-templates contains configuration fragments. You should ignore this section — do not make any changes to it.
• services is where you will define your IBM Cognos Analytics connections.
• volumes contains mount information. You should ignore this section as well — do not make any changes to it.

Define services

For each on-premises IBM Cognos Analytics instance, define an entry under services in the compose file.

Each entry will have the following structure:

services:
  cognos-example:
    <<: *extract
    environment:
      <<: *cognos-defaults
      EXCLUDE_FILTER: '{}'
      INCLUDE_FILTER: '{}'
    volumes:
      - ./output/cognos-example:/output/process

• Replace cognos-example with the name of your connection.
• <<: *extract tells the cognos-extractor tool to run.
• environment contains all parameters for the tool.
  • EXCLUDE_FILTER and INCLUDE_FILTER — specify a regular expression to filter assets to exclude or include, respectively. For example, to exclude a folder with the ID 76471ff1e0f02c7d3349 in team_content, configure the EXCLUDE_FILTER as follows — '{"team_content": {"76471ff1e0f02c7d3349": {}}'.
• volumes specifies where to store results. In this example, the extractor will store results in the ./output/cognos-example folder on the local file system.

You can add as many IBM Cognos Analytics connections as you want.

Provide credentials

To define the credentials for your IBM Cognos Analytics connections, you will need to provide an IBM Cognos Analytics configuration file.

The IBM Cognos Analytics configuration is a .ini file with the following format:

[CognosConfig]
host=http://cognos-application-host-example.us-east-2.compute.amazonaws.com
port=9300
namespace=CognosEx
# possible values are "basic_auth" and "api_key"
auth_type=basic_auth

# Only required when auth_type = basic_auth
[BasicAuth]
username=user@atlan.com
password=<password>

# Only required when auth_type = api_key
[APIKeyAuth]
key=<yourAPIkey>

Secure credentials

Using local files

To specify the local files in your compose file:

secrets:
  cognos_config:
    file: ./cognos.ini

Using Docker secrets

To create and use Docker secrets:

1. Store the IBM Cognos Analytics configuration file:

   sudo docker secret create cognos_config path/to/cognos.ini

2. At the top of your compose file, add a secrets element to access your secret:

   secrets:
     cognos_config:
       external: true
       name: cognos_config

   • The name should be the same one you used in the docker secret create command above.
   • Once stored as a Docker secret, you can remove the local IBM Cognos Analytics configuration file.

3. Within the service section of the compose file, add a new secrets element and specify the name of the secret within your service to use it.

Example

Let's explain in detail with an example:

secrets:
  cognos_config:
    external: true
    name: cognos_config

x-templates:
  # ...

services:
  cognos-example:
    <<: *extract
    environment:
      <<: *cognos-defaults
      EXCLUDE_FILTER: '{}'
      INCLUDE_FILTER: '{}'
    volumes:
      - ./output/cognos-example:/output/process
    secrets:
      - cognos_config

1. In this example, we've defined the secrets at the top of the file (you could also define them at the bottom). The cognos_config refers to an external Docker secret created using the docker secret create command.
2. The name of this service is cognos-example. You can use any meaningful name you want.
3. The <<: *cognos-defaults sets the connection type to IBM Cognos Analytics.
4. The EXCLUDE_FILTER and INCLUDE_FILTER tells the extractor to filter folders.
5. The ./output/cognos-example:/output/process line tells the extractor where to store results. In this example, the extractor will store results in the ./output/cognos-example directory on the local file system. We recommend you output the extracted metadata for different connections in separate directories.
6. The secrets section within services tells the extractor which secrets to use for this service. Each of these refers to the name of a secret listed at the beginning of the compose file.