## Set up IBM Cognos Analytics

URL: https://docs.atlan.com/apps/connectors/business-intelligence/ibm-cognos-analytics/how-tos/set-up-ibm-cognos-analytics

> :::warning Who can do this? You must be an IBM Cognos Analytics administrator to complete these steps - you may not have access yourself.

:::warning Who can do this?
 You must be an IBM Cognos Analytics administrator to complete these steps - you may not have access yourself.

:::

Atlan supports the following authentication methods for fetching metadata from IBM Cognos Analytics:

- Basic authentication - this method uses a [username and password](#create-user) to fetch metadata.
- API authentication - this method uses a [username](#create-user) and an [API key](#create-api-key) to fetch metadata.
- OKTA authentication - this method uses a [username and password](#optional-create-user-in-okta) of OKTA to fetch metadata.

## Create user

To [create a new user](https://www.ibm.com/docs/en/cognos-analytics/12.0.0?topic=namespace-creating-managing-users) for [crawling IBM Cognos Analytics](https://docs.atlan.com/llms/connectors/ibm-cognos-analytics/crawl-ibm-cognos-analytics/llms.txt):

1. Log in to your IBM Cognos Analytics instance.
2. Expand the left menu of your homepage and then click **Manage**.
3. From the corresponding menu, click **People** and then click **Accounts**.
4. In _Accounts_, under _Namespaces_, select your Cognos namespace to open it.
5. From the upper right of your namespace page, click the new user icon to add a new user to the selected namespace.
6. In the _New user_ form, enter the following details:
 1. For _Given name_, enter a meaningful name for the new user.
 2. For _User ID_, create a username for the new user.
 3. For _Password_, create a password for the username.
 4. For _Email_, you can leave this blank.
 5. Click **OK** to save your configuration. The new user you created is added to the list of entries in your namespace.

## Create API key

You can also use API authentication for integrating with Atlan. In addition to the username for the new user created in the [Create user](#create-user) section, you need an API key for authenticating the connection.

To [create an API key](https://www.ibm.com/docs/en/cognos-analytics/11.2.0?topic=settings-creating-personal-api-keys) for [crawling IBM Cognos Analytics](https://docs.atlan.com/llms/connectors/ibm-cognos-analytics/crawl-ibm-cognos-analytics/llms.txt):

1. Log in to your IBM Cognos Analytics instance as the new user created in the [Create user](#create-user) section.
2. In the top right of your homepage, click the personal menu icon and then click **Profile and settings**.
3. In the _Profile and settings_ tab, under _Advanced options_, next to _My API keys_, click **Manage**.
4. From the upper right of the _My API keys_ page, click the **Generate API key** button.
5. In the _Generate API key_ dialog, enter the following details:
 1. For _Name_, enter a meaningful name for the API key.
 2. (Optional) For _Description_, enter a brief description.
 3. Click **Next** to proceed.
 4. Once the encrypted key has appeared on the screen, copy and store the value in a secure location.

 :::warning
 IBM Cognos Analytics doesn't store the API key, you must copy and save it.
 :::

 5. Click **Done**. Your new API key appears in the list of keys on the _My API keys_ page.

If you experience any functionality issues with the newly created API key, you can renew your credentials. Navigate to the _Profile and settings_ menu, and then next to the _Credentials_ option, click the **Renew** button to refresh your credentials.

## (Optional) Create user in OKTA

If the IBM Cognos Namespace type is "OKTA" and OKTA is used for login, a
corresponding user must be created in OKTA to enable login to IBM Cognos via
OKTA.

If IBM Cognos is configured to use OKTA as the authentication provider (via the OKTA namespace type), each user must have a valid account in OKTA to successfully log in.

Follow these instructions to [create a new user](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-create-assign-user-type.htm) in OKTA and assign a user type for accessing IBM Cognos Analytics:
1. Log in to your OKTA instance with Admin credentials.
2. From the left menu on the homepage, expand **Directory** and select **People**.
3. Click **Add Person**.
4. In the New User form, fill in the following details:
 - Select the appropriate **User Type**.
 - Enter user's personal details.
 - Assign the user to the relevant group.
 - Click **Save** to complete the process.

## Add user to Cognos role

To add the new user to the Cognos _Reader_ role:

1. Log in to your IBM Cognos Analytics instance.
2. Expand the left menu of your homepage and then click **Manage**.
3. From the corresponding menu, click **Administration console**.
4. From the tabs along the top of the _IBM Cognos Administration_ page, click **Security**.
5. In the _Security_ tab, select the **Cognos** namespace.
6. From the list of standard roles, navigate to **Readers**. In the _Actions_ column for _Readers_, click **More**. This role provides read-only access to IBM Cognos Analytics, refer to the [standard roles documentation](https://www.ibm.com/docs/en/cognos-analytics/11.2.0?topic=roles-standard) to learn more.
7. In the _Perform an action - Readers_ screen, under _Available actions_, click **Set members**.
8. In the _Members_ tab, click **Add** to add a new entry to the list.
9. In the _Select entries (Navigate)_ _\- Readers_ screen, from the _Available entries_, select the namespace where you created the new user.
10. In the corresponding screen, under _Directory_, click the **Show users in the list** checkbox and then select the [new user you created](#create-user).
11. Click the right-arrow button, and when the entry you want appears in the _Selected entries_ box, click **OK**.

## Set permissions

All entries such as folders, reports, modules, and more already have the _Readers_ role assigned to them by default. You only need to set permissions for the new user to data server connections.

To set access permissions for the new user to Cognos entries:

1. Log in to your IBM Cognos Analytics instance.
2. Expand the left menu of your homepage and then click **Data server connections**.
3. On the _Data server connections_ page, to set permissions for each data server connection, click the vertical 3-dot icon and then click **Properties**.
4. From the tabs along the top of the _Properties_ page, click the **Permissions** tab.
5. In the upper right of the _Permissions_ page, click the **+** icon to add a new member.
6. In the _Add member_ form, select the **Cognos** namespace and then search for and select the **Readers** role.
7. Click **Add**.
8. Once you have added the role, click **Save** to save your configuration.

## Find namespace

You must have the name of your namespace where you created the new user for authenticating the connection in Atlan. There are several ways to find the name of your namespace, here is one such method.

To find the namespace details where you created the new user:

1. Log in to your IBM Cognos Analytics instance.
2. Expand the left menu of your homepage and then click **Manage**.
3. From the corresponding menu, click **Administration console**.
4. From the tabs along the top of the _IBM Cognos Administration_ page, click **Security**.
5. In the _Security_ tab, select the namespace where you [created the new user](#create-user). Make sure that the new user is listed in the selected namespace.
6. From the top right of your namespace page, click the **Set properties** chart icon.
7. In the _Set properties (namespace)_ page, next to _Location_, click the **View the search path, ID and URL** link.
8. In the _View the search path, ID and URL_ form, under _Search path_, next to `CAMID`, the name of your namespace is shown enclosed within brackets - for example, `CAMID()`. Copy the value for `` and store it in a secure location.

---