Creating a data server connection

A data server connection specifies the parameters that are needed to connect to the database or the cube that the connection represents.

Each data server can have one or more connections. The connection names must be unique.

Before you begin

Most data server connections require a database vendor-supplied JDBC driver. Use a version of the JDBC driver that is compatible with Java™ Runtime Environment version 8. Copy the driver to the Cognos® Analytics installation_location\drivers directory, and restart the query service. Restarting the full IBM Cognos service is not necessary.

To create data server connections, you need the Data Source Connections administration capability. Certain roles, such as Analytics Explorers and Analytics Users, have this capability by default. For more information, see Setting access to user capabilities.

Note: If you want to connect to a data server using an SSL certificate that is located on the cloud, see Securing your data server connection using a cloud-based certificate.

Procedure

  1. Click Manage > Data server connections.
  2. In the Data server connections page, click New > Data server.
  3. Define the data server type.
    1. Add a name and description (optional) for the connection.
    2. In the Connection type field, select a data server type or start typing to quickly find the connection type that you want.
    3. If you are a System Administrator, you can select a tenant.
    4. Click Next.
  4. Enter the connection details.

    For most connections, you must specify the JDBC URL. You can view the syntax and example URL under connection details. You might need to ask the database administrator for more details, or check the database vendor documentation.

    In the Connection properties box, type the supported property name. For information about the supported JDBC properties, see Cognos-specific connection parameters.

    For IBM Planning Analytics connections, specify the TM1 database host and HTTP port number. To use an SSL connection, select the Use SSL check box.

    If you are connecting to a data server using an SSL certificate in a Cloud Object Storage location, read about how to specify S3 header information.

    1. Select an isolation level from the list.
    2. For relational databases, expand the Local sort section, and specify the Collation sequence setting.

      This setting is required only in rare cases where there might be sorting discrepancies between Cognos Analytics and a database.

    3. Under Authentication method, specify how to access the data server.
      You can select one of the following options.
      Connect anonymously or Integrated security

      Choose the Connect anonymously option when anonymous access to the data server is allowed.

      Choose the Integrated security option when the TM1 database is configured for Integrated Security mode 4 or 5. This option is applicable for IBM Planning Analytics connections only.

      Prompt for the user ID and password

      Choose this option when the user must be prompted for database credentials with each use.

      Use an external namespace

      Choose this option to secure the connection against a namespace that is configured for Cognos Analytics. Use the drop-down menu to select one of the available namespaces.

      Cognos Analytics logs on to the data server with the credentials that are used to authenticate to the selected namespace. The namespace must be active, users must be logged on prior to accessing the data server connection, and the authentication credentials that are used for the namespace must be relevant for the data server authentication.

      Typically, this authentication method is used in the following situations:
      • You want Cognos Analytics to pass through to the database the user ID and password that is presented to the portal during authentication.
      • You want Cognos Analytics to use Kerberos authentication.
      • You want Cognos Analytics to use JSON Web Token (JWT) authentication.

      The query server determines the credential information that is provided by the external namespace, and chooses which connection method to attempt.

      Use the following signon

      Choose this option to assign a signon for the connection.

      Select the signon from the drop-down list, or create a new signon by clicking the add icon add icon. In the New data server connection window on the Credentials tab, type a user ID and password.

      To restrict the signon to particular users, roles, or groups, on the Permissions tab, click the add icon add icon, and specify the access permissions for the signon.

    4. Click Test connection to verify that the data server connection works.
      Tip: If the test fails, click View result.You can copy the error details to the clipboard to help you troubleshoot the cause.
    5. Click Next.
      The Commands page appears.
  5. If you want, you can select commands that you want the database to execute. For more information, see Command blocks.
  6. Click Create.

Results

The new connection name is displayed on the Data server connections page. To edit the data server connection, including adding or modifying its signon, click the connection name.

Note: The following message may appear:

MSR-GEN-0026 The schema "schema_name" is either empty, or not accessible using the current signon

This message could mean, as stated, that the schema is empty (has no objects) or that the user does not have access to it. However, the message could also mean that the schema simply has no TABLE objects, such as TABLE, VIEW, or a SYNONYM to a TABLE/VIEW object, yet still contains other object types. In this scenario, the produced message is incorrect.

What to do next

To use a data server as a source for reports, dashboards, explorations, and other Cognos Analytics content, create data modules that are based on the connection.

For relational data server connections, you must preload the schema metadata to make the schema available to create data modules in the modeling component. For more information, see Loading relational metadata.

For IBM Planning Analytics connections, you can create data modules directly from the connection user interface. For more information, see Creating data modules from OLAP cubes (Cognos Analytics 12.0.2 and earlier versions).