MODLR

dimension.set ​

Runs set instructions on a dimension and returns the elements they select, in order. It's often used to fill a dropdown on a custom page.

js
dimension.set(dimension, instructions, options)

Parameters ​

ParameterTypeDescription
dimensionstringThe dimension's name or id.
instructionsarrayThe set instructions, run in order. Use { set: ["All Products"] } to select elements, and plain strings such as "expand-all" for actions. It can't be empty.
optionsobjectOptional. security: true to list only what the signed-in user can see, or a user's id or email address for that user. maxItems: the most elements to return. A warning is written to the process log when the list is cut short.

Returns ​

array | null

The elements, in order. Each has:

  • name: the element's name.
  • label: the text to show. It's the alias when the instructions include "use-alias:AliasName", otherwise the same as name.
  • hierarchy: the hierarchy the element came from.
  • level: how deep the element sits, for indenting a tree.
  • consolidation: true when the element has children.

Returns null when the dimension, or an element or hierarchy in the instructions, can't be found. The reason is written to the process log.

Examples ​

js
// The signed-in user's regions
const regions = dimension.set("Region", [{ set: ["All Regions"] }, "expand-all"], { security: true });
js
[
    { name: "All Regions", label: "All Regions", hierarchy: "Default", level: 0, consolidation: true },
    { name: "North", label: "North", hierarchy: "Default", level: 1, consolidation: false },
    { name: "South", label: "South", hierarchy: "Default", level: 1, consolidation: false }
]
js
// Leaf products, labelled by their Description alias
const products = dimension.set("Product", [
    { set: ["All Products"] },
    "expand-all",
    "remove-all-consolidations",
    "use-alias:Description"
]);
js
[
    { name: "P-100", label: "Standard Widget", hierarchy: "Default", level: 2, consolidation: false },
    { name: "P-200", label: "Deluxe Gadget", hierarchy: "Default", level: 2, consolidation: false }
]
js
// The first 3 accounts a given user can see
const accounts = dimension.set("Account", [{ set: ["Profit and Loss"] }, "expand-all"], {
    security: "user@example.com",
    maxItems: 3
});
js
[
    { name: "Profit and Loss", label: "Profit and Loss", hierarchy: "Default", level: 0, consolidation: true },
    { name: "Revenue", label: "Revenue", hierarchy: "Default", level: 1, consolidation: true },
    { name: "Sales", label: "Sales", hierarchy: "Default", level: 2, consolidation: false }
]
text
dimension.set - Stopped at maxItems (3); the list is incomplete.

Copyright © 2026 MODLR