HierarchyBlueprint ^v2.7.197

Builds a hierarchy in memory, validates it, and publishes it into a dimension.

const report = new HierarchyBlueprint()
    .addChild("All Time", "2026")
    .addChild("2026", "2026 - Q1")
    .addChild("2026 - Q1", "Jan")
    .publish("Time", "Default");

if (!report.ok()) {
    console.log(report);
    script.fail("Publish failed");
}

Constructor

new HierarchyBlueprint new HierarchyBlueprint() HierarchyBlueprint

Creates an empty blueprint for the current model.

const blueprint = new HierarchyBlueprint();

Overview

• Build, then publish: declare elements with add() and parent-child links with addChild(). Nothing changes in the model until you call publish().
• Chaining: the build methods return the blueprint, so calls can be chained.
• Validation: validate() checks the structure for problems such as cycles, without changing anything. publishMode() controls what publishing does when it finds problems.

Methods

add add(elementName) HierarchyBlueprint

Adds an element to the blueprint without linking it to a parent. Adding the same name twice is harmless. An invalid or empty name is logged and ignored.

Parameter	Type	Description
elementName	string	The element's name.

addChild addChild(parentName, childName, weight) HierarchyBlueprint

Links a child element under a parent, adding either to the blueprint if it isn't there yet. An invalid or empty name is logged and ignored.

Parameter	Type	Description
parentName	string	The parent element's name.
childName	string	The child element's name.
weight	number	Optional. How the child rolls up into the parent. Defaults to 1; use -1 to subtract.

clear clear() HierarchyBlueprint

Removes every element and link from the blueprint, so it can be reused to build a different hierarchy.

publishMode publishMode(mode) HierarchyBlueprint

Sets what publish() does when it finds problems. An unrecognised mode logs a warning and uses "STRICT".

Parameter	Type	Description
mode	string	"STRICT", "BEST_EFFORT" or "IGNORE_VALIDATION".

Mode	Behaviour
"STRICT" (default)	Stops if validation finds an error, and stops at the first link that fails to publish.
"BEST_EFFORT"	Records validation errors but carries on, publishing everything it can. Failed links are skipped and recorded.
"IGNORE_VALIDATION"	Skips validation. Links that still can't be applied, such as ones that would create a cycle, fail individually and are recorded.

validate validate(dimensionName, hierarchyName) ValidationReport

Checks the blueprint for problems such as cycles, duplicate or conflicting links, invalid weights and disconnected elements, and checks it against the existing hierarchy, such as an element that would change from a leaf to a parent. Changes nothing; returns a ValidationReport.

Parameter	Type	Description
dimensionName	string	The dimension to check against.
hierarchyName	string	The hierarchy to check against.

publish publish(dimensionName, hierarchyName) PublishReport

Applies the blueprint to a hierarchy, creating the hierarchy and any missing elements. Returns a PublishReport saying what was applied.

Parameter	Type	Description
dimensionName	string	The dimension to publish into.
hierarchyName	string	The hierarchy to publish into.

Examples

Check before publishing

const blueprint = new HierarchyBlueprint()
    .addChild("Total", "Revenue")
    .addChild("Total", "Costs", -1)
    .addChild("Revenue", "Product Sales")
    .addChild("Revenue", "Services");

const validationReport = blueprint.validate("Account", "Default");

if (!validationReport.ok()) {
    console.log(validationReport);
    script.fail("The account hierarchy has errors.");
}

const publishReport = blueprint.publish("Account", "Default");

if (!publishReport.ok()) {
    console.log(publishReport);
}

Related

• ValidationReport: returned by validate().
• PublishReport: returned by publish().