IBM Support

Configure datasource to IBM Planning Analytics 2.0.x in IBM Cognos Analytics 11.0.6+

Troubleshooting


Problem

Configuring a connection against IBM Planning Analytics might fail with XTR-ERR-0007 Failed to retrieve the resource /api/v1/Configuration from host or Planning Analytics cube can´t be opened in Authoring or Dashboarding.

Symptom

Types of failures that can occur:
XTR-ERR-0007 Failed to retrieve the resource /api/v1/Configuration from host <host>
Planning Analytics cube can´t be opened in Authoring or Dashboarding
XQE-PVD-0003 An error occurred while loading provider instance "NGTM1":

XTM-JAP-0001 An attempt to initialize the TM1 API failed. The TM1 error code is: CannotInitializeAPI. The TM1 error message is: "Could not load tm1api.dll due to: .".

Cause

Incorrect configuration

Environment

IBM Cognos Analytics 11.0.6+
IBM Planning Analytics 2.0+

Resolving The Problem

Steps to configure a datasource connection to IBM Planning Analytics 2.0.x (available as of IBM Cognos Analytics 11.0.6)

  1. Open Administration Console through Manage and go to Configuration > Data Source Connections
  2. In the upper right corner, select New Data Source
  3. Enter a name. Select Next.
  4. As Type choose Planning Analytics
    .
    Select Next.
  5. For TM1 Host (11.0.6) / Host (11.0.7 +), enter the Planning Analytics TM1 server's host name or IP address.
  6. For TM1 server port (11.0.6) / Port (11.0.7 +), enter the HTTPPortNumber. If you are unsure of the value, check tm1s.cfg of the TM1 server you want to connect to.
  7. Check Use HTTPS (11.0.6) / Use SSL (11.0.7 +) when UseSSL=T is set in the tm1s.cfg of the TM1 Server you want to connect to.

    See the additional required steps when this option is selected.

  8. Enter the username and password, or if using IntegratedSecurityMode=4 or 5 select No authentication (11.0.6) / Integrated Security (11.0.7 +)
  9. Test the connection and select Finish to save.

Example entry:

Known errors and how to resolve them

 
  • XTR-ERR-0007 Failed to retrieve the resource /api/v1/Configuration from host <host>. Cause: Connect to <host>:<port> [/<host>] failed: Connection refused: connect

    Root Cause: The Use HTTPS (11.0.6) / Use SSL (11.0.7 +) does not match the UseSSL value in tm1s.cfg of the TM1 Server
  • XTR-ERR-0007 Failed to retrieve the resource /api/v1/Configuration from host <host>. Cause: com.ibm.jsse2.util.h: PKIX path building failed: java.security.cert.CertPathBuilderException: unable to find valid certification path to requested target

    Root Cause: The TM1 Server certificate has not been imported into the Cognos Analytics keystore.

    See the additional required steps below.

 

 

Additional steps for UseSSL=T

Note: If Use HTTPS is checked, the tm1server certificate needs to be imported into the appropriate keystore of the used jre in Cognos Analytics. Depending on the configuration of Planning Analytics there might be different certificates per TM1 Server, as well as depending on the configuration of Cognos Analytics, there might be different keystores to import the certificate to.

By default the used keystore for the Query Service is cacerts.

  1. Locate the tm1server certificate in the Planning Analytics installation. By default the certificate file is ibmtm1.arm located in <Planning Analytics Install>\bin64\ssl.
    If custom internal SSL is configured, the file name and location is defined as SSLCertificate parameter in tm1s.cfg.
    Copy the file to the Cognos Analytics installation
  2. There are multiple ways to import the certificate in the cacerts keystore. This document will describe a way through command line and through the ikeyman utility.
  • Option 1: Command line
      • cd <Cognos Analytics installation>\jre\7.0\bin
        (Note: For Linux/Unix): cd $JAVA_HOME/bin)
      • keytool -import -trustcacerts -file "<path to the certificate>\ibmtm1.arm" -keystore ..\lib\security\cacerts -storepass changeit -alias TM1ServerCert
        (Note: The -alias TM1ServerCert can be any given text to identify the certificate in the keystore)
    Option 2: ikeyman
      • Go to <Cognos Analytics installation>\jre\bin and execute ikeyman.exe
        (Note: For Linux/Unix): cd $JAVA_HOME/bin)
      • Select Open a key database file, and navigate to the cacerts keystore located in <Cognos Analytics installation>\jre\lib\security.
      • Select Key database type: JKS
      • On prompt enter password changeit
      • In the drop-down switch from Personal Certificates to Signer Certificates
      • On the right select Add
      • Browse for the copied certificate
      • On prompt enter an alias for the certificate in the keystore, ie. TM1ServerCert. This can be any given text to identify the certificate in the keystore.

After making changes restart the CA server to activate the changes.

In a multi-server environment these steps should be performed on each dispatcher, dedicated or combined with other role (for example, dispatcher+CM).

It is not required to make these changes on dedicated content managers or gateways that do not act as dispatchers.

Additional information on the support of IBM Planning Analytics in IBM Cognos Analytics can be found here.

NOTE:  As of Cognos Analytics 11.1.5+ release, the default shipped IBM JRE location <Cognos Analytics installation>\jre no longer exists. IBM JRE changed to new location <Cognos Analytics installation>\ibm-jre\jre.
Refer to Changed location of JRE files documentation.

[{"Line of Business":{"code":"LOB10","label":"Data and AI"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSTSF6","label":"IBM Cognos Analytics"},"ARM Category":[{"code":"a8m50000000Cl6nAAC","label":"Installation and Configuration-\u003EData Sources"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"11.0.6;11.0.7;11.0.8;11.0.9;11.1.0;11.1.1;11.1.3;11.1.4;11.1.5;11.1.6;11.1.7"}]

Document Information

Modified date:
05 August 2022

UID

swg22000885

Page Feedback