Best Practices for Creating and Editing Hierarchies
Review these best practices to manage flexible hierarchies.
Required Editions
Available in: Lightning Experience Available in: Unlimited and Agentforce Editions |
Managing Hierarchy Changes
Use the UI-based hierarchy builder to simplify hierarchy creation or the API for precision and scale to manage hierarchies. Review these hierarchy update scenarios, their impact, the recommended methods for updating a hierarchy, and the rationale.
| Action | Structural Impact | Recommended Method | Rationale & Best Practices |
|---|---|---|---|
| Update a field on a node record | No impact on the hierarchy structure. | NA | Hierarchy nodes reference live data. Updates to fields, such as Account Name or Annual Revenue, reflect automatically. |
| Add a node | A new record is added to the hierarchy. | UI or API | Use the hierarchy builder if you plan to add single nodes, and use the API if you plan to add nodes in bulk. |
| Remove an inactive reference record from multiple hierarchies | The nodes referencing the inactive record are removed. | Salesforce Platform Events and Change Data Capture (CDC), Record-Triggered Flows, or Apex | Programmatically identifies and deletes the affected node records to update hierarchies in bulk. |
| Edit a reference record on a node relation | The reference record on the node relation is updated. | UI or API | Use the hierarchy builder for simple updates, and use API for bulk retagging. |
| Edit a node relation | The link between two existing nodes is updated. | API | Provides an efficient and scalable approach. |
| Change a node's reference | An existing node is linked to a different Salesforce object record. | API | Provides an efficient and scalable approach. |
| Change a node relation's reference | The underlying links, such as account account relations or account contact relations are updated while the nodes remain the same. | UI or API | Validate the hierarchy after you update to ensure hierarchy integrity. |
| Change a node’s parent | The hierarchical structure is updated by assigning a new predecessor to the specified node or an entire sub-tree. | API | Changing parent nodes in large structures in the UI can be complex. API approach is efficient and scalable. |
| Add nodes in bulk | A significant number of nodes or multiple levels of a hierarchy are added. | API | Provides an efficient and scalable approach. Best Practice: First, insert all flexible hierarchy node records, and then insert the corresponding flexible hierarchy node relationship records to establish connections. To ensure hierarchy integrity, validate the hierarchy after you add nodes. |
| Delete nodes in bulk | A significant number of nodes or multiple levels of a hierarchy are deleted. | API | Provides an efficient and scalable approach. To avoid island node errors, manually reparent orphaned child nodes or delete the subtree. |
| Delete an entire branch | All child nodes are automatically removed when a parent node is deleted. | UI | Automates the deletion of all child nodes. |
| Delete a specific node | A single node is removed from the hierarchy. | API | To ensure hierarchy integrity, validate the hierarchy after you delete a node. Best Practice: When deleting an intermediary node, you must also delete the corresponding relationship and reparent immediate child nodes to prevent orphaned records. |
Data Visibility and Field Level Security
A node represents a Salesforce record, but it doesn't alter the underlying record. The same record can exist in multiple hierarchies simultaneously. User access to the underlying records is enforced when viewing hierarchies. If a user doesn't have access to an underlying record, its details don't appear in the grid or graph views. The views also enforce field-level security for the underlying fields.
Best Practices for Programmatic Hierarchy Management
- Avoid Orphan and Island Nodes: Deleting a node via API removes only that specific record. If you delete an intermediary node, you must either reconnect its orphaned children to a new parent or delete the entire subtree to maintain structural integrity and prevent validation errors.
- Prevent Circular References: To prevent circular references when reparenting nodes, verify that no child is listed as a parent of its own ancestor. While the validation engine automatically catches these infinite loops, double-checking your structural logic beforehand prevents complex validation failures.
- Validate After Bulk Operations: When making bulk additions or deletions, run all data model operations, such as inserts and deletes first. Once the bulk updates are complete, send a single request to the Connect API to validate the affected hierarchies
Checklist for Importing Hierarchy Data by Using the APIs
Review these guidelines before importing hierarchy data by using the API.
- Specify only one node as the root of the hierarchy
- Verify that node record IDs match the defined node object. For example, don't specify contact IDs in a hierarchy whose hierarchy type configuration contains only account nodes.
- Make sure that every node except the root has a valid parent record ID.
- Verify that the record ID for each node matches the selected object type in the hierarchy type configuration. For example, if you add an account record as a node, the record ID must begin with the prefix, 001, and not any other prefix.
- Make sure that node relation reference record ID matches the node relation object. For example, if you’ve specified an Account Account Relation reference record ID then the corresponding node must be of the type Account Account Relation.
- To prevent circular references, verify that no child is listed as a parent of its own ancestor.
- After importing hierarchy data, open the hierarchy builder to verify the structure in the Grid and Graph views.
- Validate the hierarchy and resolve validation errors.
- Log in as a hierarchy user and verify the hierarchy.
Did this article solve your issue?
Let us know so we can improve!
