Entity Filter with TraverseHierarchy Parameter

TraverseHierarchy is available for all feed types that can use Entity filter (check the full list of available filters).

TraverseHierarchy flag enables additional logic to perform a deeper search: after the list of entityIds is determined, a tree of entities is built for composite entities (Entities with ENTITY_TYPE=COMP) and all sub-entities of this composite entity will be extracted as well.

To get a better understanding of this, please see some general description and examples of use with interaction with EntityId, list of EntityIds, EntityComposite and EntityList filters, followed by a comparison table of results of extraction.

The following filters can be used with TraverseHierarchy flag:

EntityID
EntityComposite
EntityList
ProcessCenter
EntityXrefId

On this page

1 Processing Details
2 Passing EntityID
3 Passing a List of EntityIDs
4 Passing a List of EntityComposites
5 Passing a List of EntityLists
6 Compare Examples and Results

Processing Details

The general approach here is simple:
1. Main filter makes up a list of Entity Ids (any entity type)
2. TraverseHierarchy logic is enabled to parse the hierarchy and to add sub-entities of composite entities to the list for extraction
3. Extraction is performed
TraverseHierarchy flag toggles execution of step 2.

For example, we have a number of EntityIds of different Entity types:

With the following hierarchy:

There are two large Entity structures, BT8207C1 and BT8207L1, which contain entities of various types: composites, lists and portfolios.

Passing EntityID

<taskParameter>
    <name>entityselectiontype</name>
    <dataType>S</dataType>
    <value>EntityID</value>
</taskParameter>
<taskParameter>
    <name>entityselectionvalue</name>
    <dataType>S</dataType>
    <value>BT8207C3</value>
</taskParameter>

On the first step we get only one EntityId:

TraverseHierarchy goes thru the tree of dependencies and makes up a list of EntityIds for it:

This list contains only entities under composite entities. BT8207_6 and BT8207_8 are not included because they belong to an entity with type 'LIST', not a composite entity. (EntityList and Entity Composite filters work in a little bit different way)

This list of Entities can also be set by Usergroups filter

Passing a List of EntityIDs

<taskParameter>
    <name>entityselectiontype</name>
    <dataType>S</dataType>
    <value>EntityID</value>
</taskParameter>
<taskParameter>
    <name>entityselectionvalue</name>
    <dataType>S</dataType>
    <value>BT8207C3,BT8207_4,BT8207L4</value>
</taskParameter>

Initial list of Entities:

These entities can be of any entity type. On this step only data for these 3 entities is extracted. But if you switch TraverseHierarchy to 'Y', these entities are taken as a starting point, their hierarchy is analyzed:

Among these three only BT8207C3 is composite, so only its tree is examined and its sub-entities are added to the list for extraction. Same goes for its composite sub-entity BT8207C4 - its tree is parsed and sub-entities are added to the final list.

Passing a List of EntityComposites

You can also pass lists of Entity Composites. (BT8207C3,BT8207C2,BT8207C1)

<taskParameter>
    <name>entityselectiontype</name>
    <dataType>S</dataType>
    <value>EntityComposite</value>
</taskParameter>
<taskParameter>
    <name>entityselectionvalue</name>
    <dataType>S</dataType>
    <value>BT8207C3</value>
</taskParameter>

When you set EntityComposite Filter, you get entities that belong to this Composite(s).

Initial list of Entities:

As you can see this list contains only EntityIds which belong to EntityComposite BT8207C3, but it does not contain BT8207C3 itself.

Hierarchy is then examined and the final list of entities transforms into:

Since only BT8207C4 has type = COMP, only its tree is built and its two sub-entities are added. The result is very similar to EntityId filter case. But BT8207C3 is not on the list.

Passing a List of EntityLists

The same principle as for EntityComposite, we use EntityIds which belong this List.

<taskParameter>
    <name>entityselectiontype</name>
    <dataType>S</dataType>
    <value>EntityList</value>
</taskParameter>
<taskParameter>
    <name>entityselectionvalue</name>
    <dataType>S</dataType>
    <value>BT8207L2</value>
</taskParameter>

Initial list:

Final list (after Traverse):

Compare Examples and Results

Input Parameters	Initial List of EntityIds (Or result w\o Traverse flag)	List of EntityIds with Traverse

Input Parameters	Initial List of EntityIds (Or result w\o Traverse flag)	List of EntityIds with Traverse
EntityId EntityID = BT8207C3
List of EntityIds EntityID = BT8207C3,BT8207_4,BT8207L4
EntityComposite EntityComposite = BT8207C3
EntityList EntityList = BT8207L2