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, IBM Cloud, or Planning Analytics as a Service (PA SaaS).
• 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.

IBM Cloud#

Use this for Planning Analytics hosted on IBM Cloud, the deployment whose URL ends in planning-analytics.ibmcloud.com. Fields:

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

IBM Cloud 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.

IBM SaaS (MCSP)#

Use this for Planning Analytics as a Service (PA SaaS), which authenticates through IBM's Multi-Cloud SaaS Platform (MCSP). Fields:

• Database.
• Data Center Url, the host IBM gives you for your tenant's data center, 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 IBM Cloud, 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; an API key for IBM SaaS (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.

Once the editor reaches the server, a read-only Server Version row shows the version it detected: the friendly Planning Analytics release (for example Planning Analytics 2.1.1, or PA-as-a-Service (v12)) alongside the internal TM1 build number (for example 11.8.2300.10). It is filled in when the editor opens against a reachable connection and refreshed each time you select Test connection. Before a connection is made it reads Unknown - not connected, and if Reportworq does not recognize the build it still shows the raw internal build with Unrecognized build as the label. Use it to confirm you are pointed at the server and release you expect.

Planning Analytics v11 vs v12#

Planning Analytics v12 (the containerized PA-Engine, including PA-as-a-Service) behaves differently from the older v11 servers (Planning Analytics 2.x and TM1 11.x) in three ways that affect how you report and automate. Reportworq v6 handles all three; the notes below tell you what changed and where to look.

• v12 enforces stricter, hierarchy-qualified MDX. The v12 engine rejects loosely-qualified MDX that v11 accepted, which affects Dynamic Reports, Active Forms, and any RW.PlanningAnalytics.MDX (RWMDX) query, as well as TM1RPTTITLE / TM1RPTVIEWTITLE output. Any Reportworq v6 release renders correctly against v12. On the v5 line you must be on 5.0.0.92 or greater. See IBM Planning Analytics functions.

• TM1ELLIST indent defaults can add leading blanks. TM1ELLIST indents each element by its hierarchy level by default, which shows up as leading spaces in the spilled names. If those blanks are unwanted, set the 7th parameter (IndentRate) to 0. See IBM Planning Analytics functions.

• Job-launching TI processes use ExecuteHttpRequest on v12. The v12 engine runs in a container with no operating-system shell, so the TI ExecuteCommand function the v11 PowerShell samples rely on is not available. Two v12 "Run Job" samples (Rest API Run Job Sample - v12 and Rest API Run Job Sample - v12 On-Prem) make the same REST call with the native TI ExecuteHttpRequest function instead - no PowerShell, no shell, nothing on disk. Pick the v12 sample in the install chooser for a v12 model. See Turbo Integrator and automation.

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 IBM Cloud 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. If you would rather pick up the latest version of a sample or of RunApiJob.ps1 without touching the server, the Downloads page offers each one as a plain file.

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.