dimension.audit

Checks a dimension for orphaned elements, which are elements that no longer appear in any hierarchy, and optionally removes them.

Orphans are usually left behind when a hierarchy is restructured and an element isn't re-added anywhere. This is the scripted equivalent of the Audit button, and its Remove Orphans action, on a dimension's page in Gateway.

dimension.audit(dimensionName, remove)

Parameters

Parameter	Type	Description
dimensionName	string	The dimension's name or id.
remove	boolean	true to remove every orphaned element found. false to only report them.

Returns

object

An object with count, the number of orphaned elements, and orphans, their names. Unlike most dimension functions it's an object, not a JSON string, so there's no need for JSON.parse().

When the dimension can't be found, returns { "error": "can not find any dimension with that name or id." } instead.

WARNING

The old values aren't cleared from memory until the cube is next loaded from disk, for example after a server restart. If an element with the same name is created again before then, its old values come back with it.

That makes an accidental delete recoverable by recreating the element within that time window.

Examples

function begin() {
    let values = dimension.audit("Scenario", false);
    console.log(values);

    dimension.audit("Scenario", true); // removes the orphan(s) found above
    values = dimension.audit("Scenario", false);
    console.log(values);
}

{"count":1, "orphans":["Budget"]}
{"count":0, "orphans":[]}

The first call reports one orphan, Budget, sitting in the Scenario dimension outside any hierarchy. The second call, with remove set to true, removes it, so the following report comes back with a count of zero and an empty orphans list.