Skip to main content
Version: Next

Hierarchy

APIs to manage hierarchical structures. Hierarchies allow you to create hierarchical trees of generic entities.

How a Hierarchy is structured​

Each node in a hierarchy can have at most one parent and can have multiple child nodes. Children can be other nodes (which does not have a specific type, they are just nodes) or be a generic entity, of the type entityName, specified by the hierarchy.

For example we want to represent a hierarchy of customers, so entityName = CustomerAccount. The root node is "Italy", which has children nodes "North" and "South". "North" has an associated list of entities of type "CustomerAccount", like "C001", "C002", "C003" (the customers in the northern part of Italy), while "South" has another list of entities: "C015", "C016" the customers in the southern part of Italy.

In the above example, "Italy", "North", "South" are just nodes with an id and a description, while "C001", "C002", etc. are customer, i.e. objects of type "CustomerAccount".

Every node can be related also to other specific objects, depending on the use of the hierarchy. For example, in a hierarchy that models a sales network, the entities pointed by "entityName" are the customers, so entityName = CustomerAccount and every node is associated with one user, which are the sales reps or their chiefs (area managers, brand managers and so on).

To continue with the above example, we may associate the user "Paolo Rossi" to the node "Italy": he is the area manager for Italy. Then we associate the user "Giovanna Bianchi" to the node "North" and "Matteo Verdi" to the node "South": they are the sales reps that manage the customers in the north and south, respectively.

How to modify a Hierarchy​

A Hierarchy is a complex entity: to modify it, the user must enter the "edit mode", by calling the edit API. The system will return a draft copy of the entity, which can be modified and saved, even if the editing is partial. The draft copy will only be visible to the user that is editing the object, while other users will continue to see the published version. When the user has finished to modify the object, he must call the publish API to request the publication. Depending on the application configuration, a valid object may be directly published, or it can require the revision of other users: in this case the publish action starts an approval workflow.