---
url: /process-functions/hierarchy-hierarchyblueprint.md
description: Builds a hierarchy in memory, validates it, and publishes it into a dimension.
---

#  HierarchyBlueprint 

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

```js
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()`  {#new-hierarchyblueprint}

Creates an empty blueprint for the current model.

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

## Overview

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

## Methods

### add `add(elementName)`  {#add}

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)`  {#addchild}

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()`  {#clear}

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

### publishMode `publishMode(mode)`  {#publishmode}

Sets what [publish()](#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)`  {#validate}

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](/process-functions/validationreport).

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

### publish `publish(dimensionName, hierarchyName)`  {#publish}

Applies the blueprint to a hierarchy, creating the hierarchy and any missing elements. Returns a [PublishReport](/process-functions/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

```js
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](/process-functions/validationreport): returned by `validate()`.
* [PublishReport](/process-functions/publishreport): returned by `publish()`.