Connector to IBM Planning Analytics TM1

With the IBM® Planning Analytics® TM1® connector, you can use commands in a chain to interact with IBM Planning Analytics, powered by Cognos® TM1. For example, with this connector, you can:

• Manage chores and their tasks in Planning Analytics
• Manage TM1 cubes and cube views and cells
• Filter message and transaction logs
• Manage processes and their error logs

Note: This connector is built by Workiva and connects to a third-party system. While our Support team can help configure this connector within your workspace, we are unable to troubleshoot or otherwise assist with any issues that originate outside of the Workiva platform.

Prerequisites

To enable the connection, the connector uses the IBM Planning Analytics REST API. Note: The connector supports IBM Planning Analytics version 10.2 or higher.

To set up the connection, you'll need:

• The full URL for the TM1 instance to connect to, such as https://TM1-url.com/api/v1
• A designated service account set up in the TM1 instance for the connector
• The service account's username and password
• Additional authentication credentials for the TM1 server, if Integrated Windows@ authentication (IWA) or Cognos Authentication Manager (CAM) is enabled
  • If IWA is enabled, its authentication token
  • If CAM is enabled, its lightweight directory access protocol (LDAP) namespace
• To connect to an on-premise TM1 server, the GroundRunner to perform the commands

  Note: To connect to a cloud instance of TM1, use the default CloudRunner.

Set up the IBM Planning Analytics TM1 connector

Note: To make the connector available for use in your organization's chains, an org security administrator first enables it from Configuration.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under Connector Connection, select IBM Planning Analytics TM1 and the runner to use with the connector.
   
3. Under Basic Info, enter a unique name and description to help identify the connection.
4. Under Properties, enter the connection's details:
   
   

   Property	Details
   TM1 API Url	Enter the full URL to the TM1 instance to connect to, such as https://TM1-url.com/api/v1.
   Username	Enter the username for the connector's service account in the TM1 instance.
   Password	Enter the password for the Username property.
   Token	If Integrated Windows authentication (IWA) is enabled for the TM1 server, enter its authentication token.
   Authentication type	Select the type of authentication enabled for the TM1 server: Basic Auth, for only TM1 username and password authentication Windows Integrated Authentication, if IWA is enabled Cognos Authentication Manager (CAM), if Cognos security is enabled
   LDAP namespace	If CAM is enabled, enter its LDAP namespace.

   Note: All sensitive credentials are automatically encrypted and stored at Advanced Encryption Standard (AES)-256 encryption.

5. Select the environments to use the connection, and click Save.
6. To test the connection, create and run a chain with the connector's List Cubes command, and verify it returns a valid output.

Troubleshooting

If the connection to IBM Planning Analytics fails:

• Check the URL for the TM1 instance to connect to.
• Verify the service account's authentication credentials.
• Verify the type of authentication enabled for the TM1 server and its related credentials, such as the IWA token or LDAP namespace

If you receive the Unable to find valid certification path to requested target error, add the server certificate to your trusted Java® keystore:

1. To get the certificate from the server, enter this command:

   # openssl s_client -connect tm1server.tux:5010 -servername tm1server.tux:5010 < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > public.crt

2. To import the certificate into your keystore, enter this command:

   # /usr/lib/jvm/java-8-openjdk-amd64$ sudo bin/keytool -import -alias tm1server.tux -keystore jre/lib/security/cacerts -file /home/administrator/public.crt

   Note: The password to your keystore may be changeit.