pa-code

DevOps Platform for IBM Planning Analytics

Author: Tim Geilen

This project provides a complete integrated development environment (IDE) and deployment pipeline for IBM Planning Analytics (TM1). It enables versioned development (Git), multi-instance management, and automated deployments (CI/CD).

🚀 Features

VS Code Extension (pa-code)

• Live Connection: Support for multiple TM1 instances (Native & CAM Security).
• Settings UI: Easily configure and manage all your TM1 instances through a user-friendly Webview panel (accessible via the ⚙️ gear icon).
• Object Explorer: Tree view for instances, processes, and rules.
• Execute Processes: Run TI processes directly from the explorer tree with a single click. Automatically fetches and opens TM1ProcessError*.log files if errors or warnings occur!
• Hot-Path: Saving (Ctrl+S) immediately sends changes to the connected server (including syntax checks).
• Local Workspace: Synchronizes TM1 objects into a clean folder structure (/Processes, /Rules).

AI Support - use your favorite AI provider in VSCode (e.g. GitHub Copilot, OpenAI, etc.)

• Code Completion: Get code completion suggestions for TM1 processes and rules.
• Code Generation: Generate code for TM1 processes and rules.
• Debugging Support: Debug code for TM1 processes and rules.

Git Support - use your favorite Git provider (e.g. GitLab, GitHub, etc.)

• Versioning: Full version control of TI processes and rules.
• Feature-Branch Workflow: Supports modern branching strategies.
• CI/CD Pipeline (GitLab/GitHub): Automated deployments to Dev, Test, and Prod.
• Intelligent Deployment:
  • Selective: Detects modified instances.
  • Upsert: Creates or updates objects and manages parameters/datasources.

🛠 Installation & Setup

Prerequisites

• VS Code
• Git
• Access to your Git repository

1. Install Extension from marketplace

2. Clone Repository (Optional)

Open a terminal and clone the project:

git clone <REPOSITORY_URL>
cd <REPOSITORY_NAME>
code .

Configuration (Environments)

Click on the ⚙️ Settings Gear icon in the "PA Code" extension view header to open the Configuration UI. Here you configure the top-level Environments (e.g. DEV, PROD). (Alternatively, you can manually create/edit the tm1-project.json file in the root directory).

{
  "environments": [
    {
      "name": "DEV",
      "folder": "DEV_Workspace",
      "adminHost": "your-admin-host.com",
      "port": 5898,
      "ssl": true
    }
  ]
}

Dynamic Server Discovery & Login

Once an environment is configured, the extension automatically queries the Admin Host to discover all running TM1 Server instances (e.g., 24_retail, Finance) underneath it.

1. Expand the Environment in the PA Code tree view to list all discovered servers.
2. Right-click a specific server and select Connect.
3. The extension dynamically detects the authentication mode:
   • Native Security: Prompts for Username and Password.
   • CAM Security: Explicitly prompts for your Namespace first, followed by Username and Password.

Local File Structure

When you download or sync files, PA Code automatically creates a structured local folder hierarchy based on the target system: Workspace Root / Environment Folder / Server Name / Processes (or Rules).

💻 Daily Workflow

1. Connect & Synchronize

1. Click the Connect Icon (plug) next to your instance in the TM1 Extension Sidebar (left).
2. Enter your User and Password.
3. (Optional) Right-click the instance -> "Pull All from Server" to update your local workspace with the latest state from TM1.

2. Develop

Create a new branch for your task:

git checkout -b feature/my-new-feature

1. Open a process or a rule from the tree view.
2. Edit the code.
3. Press Ctrl + S.
   • ✅ Extension: Immediately saves to the server and validates syntax.
   • ✅ File: Saves changes locally to your hard drive.

3. Process Execution & Debugging

Run a process by clicking the Play button next to it in the tree view. If the process fails or finishes with minor errors, the extension will automatically retrieve the correct error log from the TM1 server and open it in a temporary editor tab for immediate debugging.

4. Deployment (GitLab/GitHub)

Commit your changes:

git add .
git commit -m "Logic for new calculation added"
git push origin feature/my-new-feature

1. Create a Merge Request in GitLab targeting dev (or test).
2. Once merged, the Pipeline will automatically start and deploy the changes.

📂 Project Structure

The repository is organized by environments and their discovered servers:

/ (Root)
├── tm1-project.json       # PA Code configuration file
├── .gitlab-ci.yml         # Pipeline definitions (Optional)
├── scripts/               # Python deployment logic (Optional)
│   └── deploy_processes.py
│
└── DEV_Workspace/         # Folder for Environment (e.g. DEV)
    ├── Finance/           # Folder for Server "Finance"
    │   ├── Processes/     # All .ti files for this server
    │   │   └── Update_Dim.ti
    │   └── Rules/         # All .rux files for this server
    │       └── Revenue.rux
    │
    └── HR/                # Folder for Server "HR"
        ├── Processes/
        └── Rules/

❓ Troubleshooting

• Extension won't connect: Check the Settings UI (or tm1-project.json) for correct ports and SSL settings.
• Save failed (404): The server might be unreachable or the object was deleted.