---
url: /process-functions/hierarchy-hierarchyblueprint.md
description: Create a hierarchy blueprint for building and publishing hierarchy changes.
---

# HierarchyBlueprint 

Create a hierarchy blueprint for building and publishing hierarchy changes.

## Creating a Blueprint

```js
const blueprint = new HierarchyBlueprint();
```

## Methods

* ### `publishMode(mode)`

  Set how publish behaves when validation fails or publish hits errors.

  * #### Parameters
    * `mode` - The publish mode. One of:
      * `"STRICT"` - Validate and stop on validation errors. Publish stops on first publish error.
      * `"BEST_EFFORT"` - Validate, but continue publishing what can be published.
      * `"IGNORE_VALIDATION"` - Skip validation and attempt publish anyway.

* ### `add(element)`

  Ensure an element exists in the blueprint (no links).

  * #### Parameters
    * `element` - The element name.

* ### `addChild(parent, child, weight)`

  Add a parent -> child relationship to the blueprint.

  * #### Parameters
    * `parent` - Parent element name.
    * `child` - Child element name.
    * `weight` - Consolidation weight. `(optional, default: 1)`

* ### `blueprint.clear()`

  Clear the current blueprint contents.

* ### `validate(dimension, hierarchy)`

  Validate the blueprint, it also validates against an existing dimension/hierarchy as best effort to avoid circular references and other issues. Returns a ValidationReport

  * #### Parameters
    * `dimension` - Target dimension name.
    * `hierarchy` - Target hierarchy name.

* ### `blueprint.publish(dimension, hierarchy)`

  Publish the blueprint to the target dimension/hierarchy. Returns a PublishReport

  * #### Parameters
    * `dimension` - Target dimension name.
    * `hierarchy` - Target hierarchy name.

## ValidationReport

Returned from `blueprint.validate(dimension, hierarchy)`.

#### Methods

* `messages()` (array): List of validation messages.
* `elementCount()` (number): Element count in the blueprint.
* `linkCount()` (number): Link count in the blueprint.
* `rootCount()` (number): Top-level root count (elements with no parents in the blueprint).
* `ok()` (boolean): True if there are no `ERROR` messages.

#### Example

```js
var report = bp.validate("MyDimension", "Default");
console.log(report.toString());

if (!report.ok()) 
    throw new Error("validation failed");
```

## PublishReport

Returned from `blueprint.publish(dimension, hierarchy)`.

#### Methods

* `ok()` (boolean): Returns `true` if no errors were recorded.
* `applied()` (number): Number of operations successfully applied.
* `skipped()` (number): Number of operations skipped.
* `errors()` (array): Error messages encountered during publish.

#### Example

```js
var blueprint = new HierarchyBlueprint();

blueprint.addChild("All Time", "Time")
    .addChild("Time", "2026")
    .addChild("2026", "2026 - Q1")
    .addChild("2026 - Q1", "Jan");

var validationReport = blueprint.validate("MyDimension", "Default");
console.log(validationReport);

var publishReport = blueprint.publish("MyDimension", "Default");

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

:::warning Publish Behavior

`blueprint.publish()` may partially succeed depending on `publishMode`.

* `"STRICT"`:
  * Validation errors stop publishing.
  * First publish failure stops publishing.

* `"BEST_EFFORT"`:
  * Validation errors are recorded, but publishing continues.
  * Individual root branches or links that fail are recorded in `errors`, and publishing continues.

* `"IGNORE_VALIDATION"`:
  * Validation is skipped.
  * Engine rules still apply - cycles and invalid operations can still fail per-link, and will be recorded in `errors`.
    :::