Naming And Organizing Applications

Apply Naming and Folder Conventions Before Creating Blocks

Before adding any block, scan the target Application for existing naming patterns. Match existing style for consistency. Only introduce standard conventions on greenfield Applications or when the user explicitly requests cleanup.

Choose the Three-Tier Name for Every Block

Every block has three name layers. Set all three deliberately:

Rules:

• Technical Name is the source of truth for formulas — keep it stable once referenced.
• Use Display Name for end-user readability without renaming the Technical Name.
• Dimensions appear as-is across Boards — keep Technical Names short and readable (PascalCase, no prefix).

Never Use Periods or Colons in Block or Folder Names

Periods (.) and colons (:) break formula references and autocomplete. Application names may use a period in the sortable prefix (e.g. 00. Hub) since applications are not referenced in formulas. Avoid ambiguous spaces inside names.

Name Applications with a Sortable Prefix

Use a two-digit numeric prefix plus a descriptive title so Applications sort predictably in the Workspace:

Application titles use PascalCase or plain descriptive names — no metric-style prefixes.

Name Folders with Numeric Prefixes for Sort Order

Pigment sorts folders numerically (1. before 10.). Top-level: N. Name. Subfolders: N.M Name.

Standard Top-Level Folder Structure

Use tool:create_folder to create folders. Place every block in an explicit folder using tool:move_blocks. Never leave blocks in "No Folder".

Organize folders by functional area, not by block type. Each folder groups all blocks (dimensions, metrics, transaction lists, tables) that belong to the same business process or domain topic.

• 0. Settings: Configuration metrics, variables, mapping metrics, admin blocks
• 1+ functional area folders: All blocks for a specific business domain or process step

Example for a Workforce Planning Application:

• 0. Settings: Admin variables, calendar config, mapping metrics
• 1. Headcount: Employee dimension, LOAD_Employee_Events, DATA_Employee_Count, CALC_FTE
• 2. Compensation: INPUT_Salary_Grid, ASM_Raise_Rate, CALC_Total_Comp
• 3. Recruiting: INPUT_Open_Positions, CALC_Hiring_Plan, OUTPUT_Recruiting_Budget
• 4. Reporting: RES_PnL_Summary, [TBL] Headcount_Summary, output metrics

Adapt numbering to complexity. Functional folders follow the business process: domain-specific steps → outputs.

Block-Type Naming Rules

Dimensions -- PascalCase, No Prefix

DepartmentCostCenterGLAccountProduct

Keep names concise -- dimensions render directly on Boards and in pivot axes.

Metrics -- Snake_Case with Type Prefix

Combine an optional process prefix (Prefix A) with a utilization prefix (Prefix B), separated by underscores:

INPUT_Budget_AmountCALC_Net_RevenueDATA_Employee_CountASM_Churn_RateMAP_Country_To_RegionPUSH_WF_Staff_CostsPULL_Hub_FX_RatesOUTPUT_Total_RevenueRES_PnL_Summary

Common Metric Prefixes

Add process-specific Prefix A acronyms when the Application covers multiple domains (e.g., EE_ for existing employees, REV_ for revenue).

Transaction Lists -- Snake_Case with LOAD_ Prefix

LOAD_Sales_OrdersLOAD_Employee_EventsLOAD_GL_Journal_Entries

Optionally append the source system: LOAD_Employee_HRIS.

Properties -- Snake_Case, No Block Prefix

Sort_OrderAccount_TypeIs_ActiveExternal_ID

Tables -- Snake_Case, Optional [TBL] Prefix

[TBL] Variance_Analysis[TBL] PnL_SummaryHeadcount_Summary

Validate Names Before Saving

1. No forbidden characters: no . or : in Technical Name or folder name (Application sortable prefixes like 00. are allowed).
2. Correct case pattern: PascalCase for dimensions; Snake_Case with prefix for metrics, transaction lists, properties, tables.
3. Explicit folder: block is placed in a numbered folder, not "No Folder". Use tool:move_blocks.
4. Prefix reflects role: metric prefix matches usage (input vs calc vs output vs load).
5. Display Name set: if end users need a friendlier label, use tool:update_metric or tool:update_list to set Display Name without changing the Technical Name.
6. Consistent with Application: if existing blocks use a different convention, follow the established pattern.