Custom Snippets for TurboIntegrator Development

TM1 TurboIntegrator development often involves writing the same code patterns repeatedly—logging setup, view creation, error handling. Custom snippets let you save these patterns as reusable templates that can be inserted into any process with a few clicks.

What Are Snippets?

Snippets are reusable blocks of TurboIntegrator code stored as JSON files. IBM Planning Analytics Workspace includes built-in snippets, but you can create custom ones tailored to your organization's standards.

Think of snippets as templates for frequently used code patterns. Instead of hunting through old processes or copying from reference documents, you open the snippet manager, select your snippet, fill in a few variables, and you're done. Variables can even reference TM1 objects directly—select a cube from a dropdown rather than typing the name.

Accessing snippets from the process editor:

Why Use Snippets?

• Consistency: When everyone uses the same snippets, your codebase becomes predictable. No more deciphering different approaches to the same problem.
• Quality: Best practices like error handling and logging are built in from the start.
• Speed: No more copying from old processes or reference documents.
  

Quick Example

Here's a simple snippet that creates a process header block:

Snippet JSON:

{

"snippetId": "Header_Framework",

"name": "Insert Header",

"description": "Process documentation block",

"auxiliaryVariables": [],

"variables": [

{ "variableName": "vProcess",

"description": "Name of Process",

"valueDefinition": { "type": "STRING", "defaultVal": null }},

{ "variableName": "vPurpose",

"description": "Purpose of Process",

"valueDefinition": { "type": "STRING", "defaultVal": null }}

],

"script": [

"#Region ########## HEADER ##########",

"# Process: vValue:vProcess",

"# Purpose: vValue:vPurpose",

"#EndRegion"

]

}

When inserting a snippet, PAW prompts you to fill in the variables:

Before inserting snippet:

After inserting snippet:

Variable Types:

STRING — Free text input.

NUMERIC — Number input.

CUB — Dropdown of cubes from the server.

DIM — Dropdown of dimensions.

DIM_HIER — Dropdown of hierarchies (requires a parent DIM variable).

Placeholder Syntax:

vValue:varName — Replaced with the user's input value.

vName:varName — Replaced with the variable name itself.

aux:varName — References an auxiliary variable (runtime variables like loop counters).

Snippet Structure

A custom snippet JSON file contains:

snippetId — Unique identifier (required)

name — Display name in the snippet manager (required)

description — Description text (required, can be empty)

auxiliaryVariables — Array of runtime variable names like loop counters (optional)

variables — Array of user-input variables with type definitions (optional)

script — Array of code lines (required)

Common Use Cases

Good candidates for snippets include: process headers with standard documentation, logging and error handling frameworks, view/subset creation loops, data source configurations, and cleanup routines.

ACG's Snippet Library

ACG has developed a snippet library designed to work as a cohesive framework:

Header — Standardized process documentation block

Prolog Framework — Logging initialization, error handling, and variable setup

Metadata/Data Framework — Record processing with counters and logging

Epilog Framework — Process completion and status logging

View Creation — Dynamic view and subset creation across cube dimensions

These snippets integrate with ACG's process logging utility (PLOG), providing visibility into process execution. The Prolog initializes variables that the Metadata and Data snippets reference, while Epilog handles status reporting. The result is consistent, well-instrumented processes.

ACG's snippets in the Snippet Manager:

The snippet library is available on GitHub: https://github.com/ACG-Code/ACG-Snippet-Library

Uploading Snippets

To upload a custom snippet:

1. Create a JSON file following the snippet format

2. Open the process editor in PAW

3. Click the Script tab → Snippet icon → Custom

4. Upload via Snippet Manager

The upload dialog:

Once uploaded to the server, snippets are available to all users across all databases—upload once and everyone can use them.

For detailed documentation on the JSON format, see IBM's guide: https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=process-create-upload-custom-snippet