Retrieving unit group (hierarchy) information

Unit, unit group, and hierarchy information can be retrieved with functions during import and in calculations (such as with K-fields). However, some functions only work when Org hierarchy filtering is either on of off. The following tables summarize the functions to use, and when you can use them.

Table 1. Common retrieval operations
Retrieve...Import specIn calculations
Unit object (UNIT_OBJECT)findUnit('unitId')

unit('unitId')

or, use the associated E-field, like e_unitid.

Unit NameUNIT_OBJECT.namename(UNIT_OBJECT)
Unit IDUNIT_OBJECT.identifiertext(UNIT_OBJECT)
Unit data fieldunitDataField(UNIT_OBJECT, 'u_fieldName')

getUnitDatafield(UNIT_OBJECT, 'fieldName')

In the following example, the first parameter (e_unitid) is the unit field and the second parameter (myUnitDatafield) is the Keyname of the UnitDatafield that you want to return:

getUnitDatafield(e_unitid, 'myUnitDatafield');

Unit group object (GROUP_OBJECT)findUnitGroup('group_id')getUnitGroupFromOrgHierarchy('groupName')
Unit group NameGROUP_OBJECT.name

getUnitGroupDatafield(UNIT_OBJECT, 'groupId', levelsDown, 'name')

or, use GROUP_OBJECT.name

Unit group IDGROUP_OBJECT.identifier

getUnitGroupDatafield(UNIT_OBJECT,'groupId', levelsDown,'identifier')

or, use GROUP_OBJECT.identifier

Unit group data fieldunitGroupDataField(GROUP_OBJECT, 'ug_fieldName')getUnitGroupDatafield(UNIT_OBJECT, 'groupId', levelsDown, 'fieldName')
Important: This function returns only one value. As such, the unit should cannot be related to more than one unit group in the same hierarchy level.
Table 2. Org hierarchy filtering is ON (Persistent)
Retrieve...Import specIn calculations
Unit is in group——
Group under a specific group—getUnitGroupFromOrgHierarchyOnField('parentGroupName', 'unitField')

Example 1 — The first child UnitGroup under parent 'brand' for a specific unit field (e_unitid) on the record will be returned:

getUnitGroupFromOrgHierarchyOnField('brand', 'e_unitid').name

Example 2 — All unit groups under parent 'brand' for a specific unit field (e_unitid) stored on the record will be returned:

getUnitGroupsFromOrgHierarchyOnField('brand', 'e_unitid')

All groups—getUnitGroupFromOrgHierarchy('parentGroupID')

Example 1 — The first child UnitGroup under parent 'brand' stored on the record will be returned. Use .identifier to return the identifier.

getUnitGroupFromOrgHierarchy('brand').name

Example 2 — All unit groups under parent 'brand' stored on the record will be returned as an array of unit groups:

getUnitGroupsFromOrgHierarchy('brand')

Table 3. Org hierarchy filtering is OFF (Dynamic)
Retrieve...Import specIn calculations
Unit is in group—isUnitMemberOfUnitGroup(UNIT_OBJECT, 'group_id')

The following example returns true if the given unit (e_unitid) is a member of the unit group with the given identifier (brand_A).

if (isUnitMemberOfUnitGroup(e_unitid, 'brand_A')) { return 1; } else { return 2; }

Group under a specific group—getUnitGroupDatafield(UNIT_OBJECT, 'parentGroupName', levelsDown, 'fieldName')

In the following example, the first child UnitGroup identifier under parent unit group 'brand' will be returned from the hierarchy. Use 'name' to return the name or 'identifier' to return the identifier.

getUnitGroupDatafield(e_unitid, 'brand', 1, 'identifier')

All groupsdirectUnitGroups(UNIT_OBJECT)—