SPACE

Appearance

TM1py ​

TM1py is a Python library for working programmatically with IBM Planning Analytics and TM1.

Use it from SPACE scripts or Jupyter notebooks for custom analysis, administration, model development, integrations, and automation. SPACE-managed connections and secrets allow TM1py workflows to obtain connection information at runtime instead of hard-coding credentials in Python files.

Connecting with a SPACE connection ​

For new workflows, use the SPACE Python SDK to retrieve a configured Planning Analytics connection.

The general pattern is:

python
from space import connections
from TM1py.Services import TM1Service

config = connections.get("Planning Analytics - Production")

with TM1Service(
    base_url=config["base_url"],
    user=config["username"],
    password=config["password"],
    namespace=config["namespace"],
) as tm1:
    print(tm1.server.get_server_name())
    print(tm1.server.get_product_version())

The fields available in the returned configuration depend on the connection's authentication type. Map the relevant fields to the corresponding TM1Service arguments.

This approach keeps environment-specific URLs and credentials outside the notebook or script and allows the same code pattern to be reused with centrally managed SPACE connections.

Connecting with a stored secret ​

A secret can also provide TM1 credentials when the workflow does not use a configured SPACE connection.

For example:

python
from space import secrets
from TM1py.Services import TM1Service

credentials = secrets.get("tm1-automation")

with TM1Service(
    address="tm1.example.com",
    port=12354,
    ssl=True,
    user=credentials["username"],
    password=credentials["password"],
    namespace="LDAP",
) as tm1:
    print(tm1.server.get_server_name())

Keep non-sensitive connection settings in code or configuration when appropriate, while retrieving sensitive fields from SPACE at runtime.

Querying TM1 data ​

After creating a TM1Service connection, use TM1py normally.

For example, execute an MDX query and return the cellset as a pandas DataFrame:

python
mdx = '''
SELECT
    {[Period].[Period].[2026]} ON COLUMNS,
    {[Region].[Region].[North America]} ON ROWS
FROM [Sales]
WHERE ([Version].[Version].[Actual])
'''

df = tm1.cells.execute_mdx_dataframe(mdx)
print(df)

Adapt cube, hierarchy, element, and method names to the model and installed TM1py version.

Executing a TurboIntegrator process ​

TM1py can also execute existing TurboIntegrator processes:

python
success, status, error_log_file = tm1.processes.execute_with_return(
    "Load Actuals",
    pYear="2026",
    pMonth="10",
)

print(success, status)

Use process names and parameters defined in the connected Planning Analytics model.

Scripts, notebooks, and jobs ​

The same TM1py code can be used in different SPACE execution workflows:

  • use Jupyter for interactive development and analysis;
  • use Python scripts for reusable programs;
  • use Jobs to execute stored scripts automatically.

This makes it possible to prototype a Planning Analytics workflow interactively and then move the reusable logic into a scheduled script.

Credential management ​

Do not hard-code Planning Analytics passwords or other credentials in notebooks or Python files.

For new workflows, use SPACE-managed secrets or connections. This keeps sensitive values outside source code and makes Python projects easier to move between environments.

The earlier space.cfg pattern can be replaced by managed SPACE configuration for new development.