Use ITEMLEVEL to determine the position of a given item within its list. The list is identified based on the item's data type. You can use this function to find the distance from the item to either its root ancestor or its furthest leaf descendant.

Syntax

ITEMLEVEL(Item [, Direction])

Arguments

ArgumentData typeDescription
ItemList itemA list item whose distance to either the root ancestor or the most distant leaf descendant is to be returned.
Direction (optional)Keyword

Determines the direction in which the distance is measured.

The keywords are ROOT and LEAF:

  • ROOT - Counts the number of root ancestors the Item has, plus itself.
    This is the default keyword if you omit the Direction argument.
  • LEAF - Counts the number of items in the path to the Item's furthest descendant, plus itself.

The ITEMLEVEL function returns a numeric value.

Calculation engine functionality differences

This function is only available in the Polaris Calculation Engine.

Syntax example

  ITEMLEVEL(Product1)


Consider the item Product1, which belongs to a list called Products. The function returns the number of items in the Products list from Product1 to its root ancestor, including the item itself in the count.

  ITEMLEVEL(Category1, LEAF)


Consider the item Category1, which belongs to a list called Categories. The function returns the number items in the Categories list from Category1 down to its furthest descendant, including the item itself in the count.

Additional information

The function's result depends on the type of list and the list item's position within it. Key points include:

  • The function counts only the items in the list. The list is identified based on the item's data type.
  • Returns 0 if,
    • In the ROOT direction, Item doesn't have a root ancestor.
    • In the LEAF direction, Item doesn't have any leaf descendants.
  • If the list item has no root or leaf nodes within the specified list, the result is 0.
  • If the list item is blank, the result is 0.
  • Top-level items are treated as the (unique) root of the corresponding lists.

HIERARCHYLEVEL

Examples

The following table represents the structure of a list Products as displayed from the Tree View:

All products



Electronics



Laptops



Gaming laptop


Phones

Furniture



Chairs
  • All products has two children: Electronics and Furniture.
  • Electronics has two children: Laptops and Phones.
  • Laptops has one child: Gaming laptop.
  • Furniture has one child: Chairs.

Consider the following module with three line items: 

  • Item contains all the list items from Products.
  • Result 1 and Result 2 have the ITEMLEVEL formulas with the data from Item.
ItemGaming laptopLaptopsPhonesElectronicsChairsFurnitureAll products

Result 1

  ITEMLEVEL(Item)

4332321

Result 2

  ITEMLEVEL(Item, LEAF)

1213124
  • ITEMLEVEL(Item) counts the number of root ancestors ‌the Item has, plus itself.
  • ITEMLEVEL(Item, LEAF) counts the number of items in the path to the Item's furthest descendant, plus itself.

Here, All Products is at the top level, and its furthest descendent goes down 4 levels to Gaming laptop, so ITEMLEVEL(All Products, LEAF) returns 4. Gaming Laptop is the furthest leaf item, so its root ancestor goes up 4 levels, and its leaf value is 1.