Connect IBM Planning Analytics#

The IBM Planning Analytics connector (TM1) connects Reportworq to a Planning Analytics server so its cubes, dimensions, subsets, views, and MDX can be modeled and reported. It supports self-hosted (on-premises) and cloud deployments. Getting the authentication right is the main task, so this page gives that section the depth it needs, then covers the deployment traps that most often reach support.

Before you begin#

• You are an administrator, working in Settings > Integrations > DATASOURCES. See Connect a data source for the general add-and-test flow.
• You know which deployment you are connecting to: self-hosted, Cloud (IBM SoftLayer), or Cloud (MCSP).
• You have the credentials or key for that deployment. Some setups require you to request configuration from IBM first, see below.
• The account you connect with has at least read permission to refresh data. Data collection (writeback) additionally needs write on the target cubes and dimensions.
• Best practice: connect with a dedicated Reportworq service account provisioned at data-admin level, not an individual person's login. A shared service account keeps the connection working when people change roles or leave, and scopes access to what Reportworq needs. Full server-admin permission is required only once, to install the REST API Turbo Integrator objects (see below), and can be removed afterward.

Choose the authentication type#

The connector's authentication type has three deployment values, and each shows a different field set. Choose the one that matches your server, then choose how credentials are presented.

Self Hosted (on-premises)#

Use this for a TM1 server you run yourself. Fields:

• Database, a combobox. The Load from Admin Host button can populate it from the Admin Host server list, auto-filling Address, Port, and SSL from each entry's REST port.
• Address, the server as an IP address, machine name, or fully qualified domain name.
• Port, in the range 1 to 65535.
• Use SSL, which must match the server.

For credentials, self-hosted supports three login modes. The single Namespace / Domain field carries whichever value the mode requires, and its label changes to tell you which:

• Native. Enter a Username and Password. Use this for TM1's own user directory.
• Windows Integrated login. Select Use Integrated Login. The credential field's label becomes Domain and authentication is mapped to Active Directory. Use this for a domain-authenticated (WIA) server. Integrated login additionally requires SPNs registered in Active Directory for the FQDN, machine-name, and IP variants of the server address.
• Cognos Access Manager (CAM). Leave integrated login off and enter the CAM Namespace along with the username and password. Use this when the server authenticates through Cognos / CAM.

When to use which: match the mode to how the TM1 server itself authenticates. If TM1 is native, use native; if it is AD-mapped, use Windows Integrated; if it is fronted by Cognos, use CAM with the namespace.

Cloud (IBM SoftLayer)#

Use this for Planning Analytics on IBM Cloud (SoftLayer). Fields:

• Database, which defaults to tm1.
• IBM Cloud URL, for example mycompanyprod.planning-analytics.ibmcloud.com.
• Username and Password.
• Namespace, which defaults to LDAP.

Cloud (IBM SoftLayer) needs an IBM Welcome Kit non-interactive user account. If element names contain special characters such as a backslash, the REST API also needs the nocanon configuration.

Cloud (MCSP)#

Use this for Planning Analytics on AWS. Fields:

• Database.
• Data Center Url, for example us-east-2.aws.planninganalytics.ibm.com.
• TenantId, for example A1BCD2EFGHIJK.
• API Key, entered in the Password field. It is used for distribution and, optionally, data collection.

You may need to request something from IBM support#

Several of these values are not self-serve, so expect a step where you request configuration from IBM before the connection will succeed. Depending on your deployment, that can include a CAM namespace, an Admin Host or gateway / Planning Analytics URL, the REST API enabled on the server (a valid HTTP port in tm1s.cfg), an IBM Welcome Kit non-interactive user for Cloud (IBM SoftLayer), or the nocanon REST configuration for special characters. Plan for that lead time rather than treating a failed test as a Reportworq problem.

Separate credentials for data collection (writeback)#

If the server license includes writeback, the editor shows a Data Collection section with Use different credentials for data collection, which reveals a parallel credential set (username and password or integrated login for self-hosted, API key for AWS MCSP). The whole section is hidden unless the license has writeback.

Test the connection#

Select Test connection. A reachable, correctly configured server returns "Success." If it fails, re-check the address and port, the SSL toggle against the server, the authentication mode and namespace or domain, and, for integrated login, that the SPNs are registered.

Advanced Options you should know about#

The connector's Advanced Options section carries a few settings worth understanding before you report against the server.

• PAfE Calculation Mode is on by default and does two distinct things. First, it controls how invalid elements render: on returns #VALUE! (Planning Analytics for Excel behavior), off returns blank (Perspectives behavior). Note the error is #VALUE!, not #N/A. Second, it flips how SUBNM and DIMNM resolve public versus private subsets when a subset is referenced by index. Set it to match how your source workbooks were authored.
• Enable Concurrent Dynamic Report Processing is on by default. It fetches the data for Dynamic Reports and Active Forms concurrently, across multiple threads, rather than one report at a time. This speeds up refresh of those report types. Leave it on unless you need to force single-threaded processing.
• Enable Proportional Data Collection is off by default and relates to consolidated-cell writeback.

Set up REST API job launching#

Advanced Options also carries two actions for launching Reportworq jobs from TM1 itself, using a Turbo Integrator process:

• Install REST API TI Process creates the Turbo Integrator processes on the server.
• Download REST API TI Powershell Script downloads the PowerShell launcher (RunApiJob.ps1) that calls a job. This action is available for Self Hosted and Cloud (IBM SoftLayer) only.

Install does not overwrite an existing process. If a .pro Turbo Integrator process from a previous install is already on the server, selecting Install REST API TI Process again leaves it in place; it does not update it. To refresh a pre-existing process, delete it on the server first, then run Install REST API TI Process again. For the full launch workflow, see Turbo Integrator and automation.

Deployment traps to plan for#

• Disable other datasources on the same database. When several Reportworq datasources point at the same TM1 or Planning Analytics database, disable all except the one the active job uses. Leaving multiples enabled makes the job bind against the wrong connection.
• Cube Monitoring was removed in v6. Earlier releases used a Cube Monitoring service to launch jobs, and it was historically the only launch option for Planning Analytics Cloud. It has been removed; there is no Cube Monitor setting in the connector. Launch jobs from TM1 through the REST API Turbo Integrator instead. The Cloud Connector relay now extends the REST API Turbo Integrator to Planning Analytics Cloud as well, so it is the single path for both self-hosted and cloud. Any Cube Monitoring objects left on a server from a previous release are inert and are not removed automatically. See Turbo Integrator and automation.
• Integrated (CAM) auth can break after a Windows update. Updates that further the deprecation of RC4-Kerberos can cause service accounts with no explicit Kerberos encryption types to be rejected, breaking the integrated-login / CAM path. If integrated auth breaks overnight after patching, enable AES128 and AES256 encryption types on each affected account, reset the account password so the change takes effect, then update the credentials in Cognos and in Reportworq.
• Static Universal Reports are not supported. The connector refreshes full or dynamic Universal Reports, but static ones are skipped with a warning in the log.
• Explorations (PAfE) are not supported. Reportworq does not refresh Planning Analytics for Excel Explorations. Use a supported report type instead: Custom Reports, Dynamic Reports or Active Forms, Quick Reports, or full Universal Reports.

Notes and limits#

• Cross-tab formatting (Crosstab, Tuple Table, Single Row) applies to the Data View and MDX Data View query types.
• Admin permission on the server is needed only one time, to create the REST API Turbo Integrator objects, and can be removed afterward. Day to day, a data-admin service account with read access is sufficient (plus write on the target cubes and dimensions for data collection).

Going deeper. To build a curated model over a Planning Analytics cube and publish it for report authors, see Data models. To launch Reportworq jobs from TM1 itself, see Turbo Integrator and automation.