HierarchicalChildFold

For a parent business object (e.g. “OrganizationalUnit”) which has a hierarchical self-relationship selfRelationshipRef to itself, this system function will recursively traverse through the hierarchy from the current node to its leaf nodes, via the self-relationship.

At a leaf node, it will iterate through the specified child business objects via the child relationship childRelationshipRef, evaluating the childExpression in the context of each of the child business objects. The results of the expression evaluations are aggregated using the aggregatorFunc parameter.

The results from the child node is then passed up to the parent node and aggregated using the aggregatorFunc parameter. This process continues up the hierarchy, until the aggregation completes at the original node.

In essence, the HierarchicalChildFold function supports a rollup aggregation for the child business objects which appear within a specific hierarchy.

In this release, Service Manager only supports the plus (+) aggregator operator.

Syntax

HierarchicalChildFold (parentObjectRef, parentRecId, selfRelationshipRef, displayFieldName, childRelationshipRef, childExpression, aggregatorFunc, childPredicateExpression)

Enabled For

For a description of the business object categories, see Notes on "Enabled For".

Business Object Category Yes/No
Business Rules: Before-Save Rules Yes
Business Rules: Calculation Rules (After Save, with or without Also Recalculate on Load) Yes
Business Rules: Calculation Rules (Before Save or Always, without Also Recalculate On Load) Yes
Business Rules: Calculation Rules (Before Save or Always, with Recalculate On Load) Yes
Business Rules: Editing Rules Yes1
Business Rules: Initialization Rules Yes
Business Rules: Read Only Rules No
Business Rules: Required Rules Yes1
Business Rules: Validation Rules Yes
Client Expressions No
Object Permissions No
Services Yes
LDAP Yes
Mobile Yes
Quick Actions (except UI Quick Actions) Yes
UI Quick Actions No
Reports Yes
Search/Dashboard without field references Yes
Search/Dashboard with field references No
1. Except when this field appears on a form or is triggered by such a field.

Parameters

parentObjectRef

The name of the parent business object. This business object needs to have a self-relationship to itself (e.g. “OrganizationalUnit”).

parentRecId

The RecID of the instance of the parent business object. This is the source of the traversal through the hierarchy, before reaching the child business object.

selfRelationshipRef

The name for the relationship relating the parent to itself. The expression editor will check at design time to ensure that the specified relationship is indeed a self-relationship, and will show an error and prevent saving of the expression if an invalid relationship is specified.

displayFieldName

A field in the parent business object which provides the display name for the given record. The primary intent of this property is to display an error message while evaluating the expression, with the names of the nodes in which a cyclic dependency has been detected, while traversing the hierarchy.

childRelationshipRef

A name for the relationship relating the parent (e.g. “OrganizationalUnit”) to its related object (child business object; e.g. “CI”).

childExpression

The expression to evaluate for each child business object. This is typically a field reference or it can be a sub-expression.

aggregatorFunc

An aggregation function specified as a string. In this release, Service Manager only supports the plus (+) aggregator.

childPredicateExpression

(Optional) A Boolean expression that is evaluated for each child. The child is only included if the result of this evaluation is true.

Return Value

Unicode text value.

Example

The HierarchicalChildFold system function is currently used in the out-of-the-box implementation of Ivanti Asset Manager, specifically the “Calculate Aggregate Values” QuickAction that is defined in the OrganizationalUnit business object.

In the Asset Manager object model, there is a relationship defined between OrganizationalUnit and itself called “OrganizationalUnit#.parent_ou_rel” – this corresponds to the selfRelationshipRef parameter.

There is also a relationship defined between OrganizationalUnit and the child CI called “CI#.CIAssociatedEmbeddedOrganizationalUnit” – this corresponds to the childRelationshipRef parameter.

In the CI business object, there is a field called ivnt_PurchasePrice, which defines the Purchase Price for the given CI (i.e. Asset).

To calculate the Total Purchase Price across all of the CIs for a specific OrganizationalUnit, the existing ChildFold expression can be used:

$(ChildFold("OrganizationalUnit#", RecId, "CI#.CIAssociatedEmbeddedOrganizationalUnit", "ivnt_PurchasePrice", "+"))

To calculate the total Purchase Price across all of the CIs for a specific Organizational Unit, as well as all child Organizational Units in the hierarchy, the new HierarchicalChildFold expression can be used:

$(HierarchicalChildFold("OrganizationalUnit#", RecId, "OrganizationalUnit#.parent_ou_rel", "Name", "CI#.CIAssociatedEmbeddedOrganizationalUnit", "ivnt_PurchasePrice", "+"))

Compared to the earlier ChildFold expression, the HierarchicalChildFold expression has the addition of the selfRelationshipRef and displayFieldName properties, otherwise the body of the expression is identical for both expressions.

Advanced Example

The above example makes use of the “ivnt_PurchasePrice” field in CI as the child expression.

The CI business object has a relationship to Frs_ITFM_Transaction, which represents the Financial Transactions for a given CI. For calculating the total cost, the following ChildFold expression can be used:

$(ChildFold("CI#", RecId, "Frs_ITFM_Transaction#.CostItem", $(Cost), "+"))

For calculating the total cost across all CIs, the following ChildFold expression can be used – notice how it embeds the above ChildFold expression in the main ChildFold expression:

$(ChildFold("OrganizationalUnit#", RecId, "CI#.CIAssociatedEmbeddedOrganizationalUnit", $(ChildFold("CI#", RecId, "Frs_ITFM_Transaction#.CostItem", $(Cost), "+")), "+"))

The above expression represents the Total Cost of Ownership for the given Organizational Unit.

To calculate the Total Cost of Ownership across all of the CIs for a specific Organizational Unit, as well as all child Organizational Units in the hierarchy, the new HierarchicalChildFold expression can be used:

$(HierarchicalChildFold("OrganizationalUnit#", RecId, "OrganizationalUnit#.parent_ou_rel", "Name", "CI#.CIAssociatedEmbeddedOrganizationalUnit", $(ChildFold("CI#", RecId, "Frs_ITFM_Transaction#.CostItem", $(Cost), "+")), "+"))

As in the earlier example, compared to the earlier ChildFold expression, the HierarchicalChildFold expression has the addition of the selfRelationshipRef and displayFieldName properties, otherwise the body of the expression is identical for both expressions.