dimension.audit

Checks a dimension for orphaned elements - elements that still exist in the dimension but no longer appear in any hierarchy, typically left behind after a hierarchy was restructured and the element wasn't re-added anywhere. Returns the orphan count and their names, and optionally removes them. This is the scripted equivalent of the Audit button (and its Remove Orphans action) on a dimension's page in Gateway.

dimension.audit(dimension_name, remove)

Parameters

• dimension_name - Name of the dimension to audit.
• remove - if true, removes every orphaned element found. If false, only reports them without changing anything.

Example

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);
}

Example output

{"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.

TIP

Unlike most other dimension.* functions (elements, hierarchies, aliases, list), dimension.audit returns a native object directly, not a JSON string - no JSON.parse needed to read .count or .orphans.

Failure behavior

Returns the object {"error":"can not find any dimension with that name or id."} when:

• dimension_name doesn't exist

Not thrown as an exception, and still a native object (not a JSON string) - check for an error property rather than count/orphans.

DANGER

Treat dimension.audit(dimension_name, true) as destructive. An orphan is removed from the dimension's element list immediately, but any data held against it in cubes isn't dropped until the Instance is next restarted - so an accidental removal can still be undone by re-adding the element before that restart, but once the Instance restarts, that data is gone for good. Only run it with remove: true when there's a specific reason to clean up the dimension and no important data sits against the orphaned elements.