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.

DANGER

Treat dimension.audit(dimensionName, true) as destructive. An orphan is removed from the dimension straight away, but any data held against it in cubes isn't dropped until the instance next restarts. An accidental removal can be undone by re-adding the element before that restart; after it, the data is gone for good.

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.