In complex enterprise environments, understanding relationships between records, such as organizational structures, location hierarchies, complex approval flows, or service dependencies, is crucial. ServiceNow’s Node Map component offers a powerful way to visualize these connections interactively.
This article walks through how to represent record relationships in a hierarchical visual format using Node Map, including how to configure the data source, populate nodes and edges, and optimize performance.
Table of contents
-
What Is the Node Map Component?
-
Technical Setup
-
Data Resource
-
Node Map Component
-
-
Result: Visual Maps
-
Recommendations
-
Useful Links
-
Conclusions
What Is the Node Map Component?
The Node Map is a Next Experience UI component available in ServiceNow that allows you to visually represent relationships between records—such as hierarchies, dependencies, or workflows—using nodes and edges.
You can configure the Node Map directly in UI Builder, where you define:
- Node Items: Represent individual records (e.g., Locations, Approvals, Employee hierarchy)
- Edge Items: Represent relationships between records (e.g., parent-child connections, CI relationships)
- Events: Trigger actions when users interact with nodes (e.g., click, hover, select)
This makes it ideal for use cases like organizational charts, service maps, flow visual representation, approvals process, or location hierarchies.
Learn more in the official documentation, which includes:
- How to configure Nodes and Edges
- Supported events and interactions
- Styling and layout options
- Performance considerations
ServiceNow Documentation: Node Map Setup in UI Builder (Yokohama Release)
Technical Setup
1. Data Resource Configuration
Create a custom Data Resource to query all records you want to visualize. In this example, we use the Internal Business Location table.
Key configuration steps:
• Name: Use a meaningful identifier
• ID: Avoid espaces or special characters
• Table: Select the relevant table (e.g., Internal Business Location)
• Edit conditions: Filter records based on relevance (e.g., active is true)
• Return fields: Include fields like display name and parent relationship.
• Order by / Sort type / Max results: Configure pagination and sorting as needed.
Tip: Apply filters to improve performance and ensure only relevant records are displayed.
2. Node Map Component
To visualize the data:
2.1. Add the Node Map component to your Next Experience page using UI Builder. Use the left panel to search and insert the component.
2.2. Configure the component using the right panel tabs:
• Configure: Bind data to Node and Edge Items
• Styles: Customize appearance
• Events: Define interactions
Node Items and Edge Items are essential, they define the data and relationships to be displayed.
There are many ways to populate the Node Map component, but one of the most straightforward approaches is to use the Data Resource you configured in the previous step. From this data, you can construct two JSON structures:
- Node Items: Represent individual records (e.g., locations)
- Edge Items: Represent relationships between those records (e.g., parent-child connections)
These JSON objects are then passed to the Node Map component to render the visual hierarchy.
To achieve this, two scripts were added to the Node Map component:
Node Items Script – Builds the nodes based on the location records
/**
* {params} params
* {api} params.api
* {TransformApiHelpers} params.helpers
*/
function evaluateProperty({
api,
helpers
}) {
try {
var userFirstNode = api.data.fetch_business_user_group.results[0]._row_data.uniqueValue;
var internalBLocations = api.data.look_up_all_int_business_locations.results;
var nodeItems = [];
var idNodes = [];
var previousNodesLength = 0,
index = 0;
// Iterate up to 3 levels to get all Nodes which are child from User Internal Business Location
while (index < 3) {
previousNodesLength = idNodes.length;
// Iterate all nodes
for (var i = 0; i < internalBLocations.length; i++) {
// Add only the nodes which have not been added, and are (the user node OR child from a child node)
if ((userFirstNode == internalBLocations[i]._row_data.uniqueValue || idNodes.indexOf(internalBLocations[i].service_organization_parent.value) != -1)
&& idNodes.indexOf(internalBLocations[i]._row_data.uniqueValue) == -1) {
var nodeItemObj = {};
nodeItemObj.id = internalBLocations[i]._row_data.uniqueValue;
nodeItemObj.viewData = {
"primaryLabel": internalBLocations[i].name.value,
"secondaryLabel": internalBLocations[i].name.value,
};
nodeItems.push(nodeItemObj);
idNodes.push(internalBLocations[i]._row_data.uniqueValue);
}
}
index++;
}
// Console log for testing - to be removed
console.log("- Node Items: \n" + JSON.stringify(nodeItems));
return nodeItems;
} catch (error) {
console.log('Node Map -Error: ' + error);
}
}
Edge Items Script – Defines the connections between nodes based on parent relationships
/**
* @Param {params} params
* @Param {api} params.api
* @Param {TransformApiHelpers} params.helpers
*/
function evaluateProperty({
api,
helpers
}) {
try {
var userFirstNode = api.data.fetch_business_user_group.results[0]._row_data.uniqueValue;
var internalBLocations = api.data.look_up_all_int_business_locations.results;
var edgeItems = [];
var idNodes = [];
if (userFirstNode)
idNodes.push(userFirstNode);
var previousNodesLength = 1;
previousNodesLength = idNodes.length;
for (var i = 0; i < internalBLocations.length; i++) {
// Add only the nodes which have not been added, and are (the user node OR child from a child node)
if ((userFirstNode == internalBLocations[i]._row_data.uniqueValue || idNodes.indexOf(internalBLocations[i].service_organization_parent.value) != -1) &&
idNodes.indexOf(internalBLocations[i]._row_data.uniqueValue) == -1) {
if (internalBLocations[i].service_organization_parent.value) {
var nodeItemObj = {};
nodeItemObj.id = 'e' + i;
nodeItemObj.targetId = internalBLocations[i]._row_data.uniqueValue;
nodeItemObj.sourceId = internalBLocations[i].service_organization_parent.value;
edgeItems.push(nodeItemObj);
idNodes.push(internalBLocations[i]._row_data.uniqueValue);
}
}
}
// Console log for testing - to be removed
console.log("- Edge Items: \n" + JSON.stringify(edgeItems));
return edgeItems;
} catch (error) {
console.log(error);
}
}
This setup allows the Node Map to dynamically display a visual representation of your data, making it easier to understand and navigate complex relationships.
Result: Hierarchical Map
The Node Map component renders a visual hierarchy of Internal Business Locations starting from the user's associated location. This helps agents and admins quickly understand organizational structure and navigate relationships.
Screenshot of Node Map displaying Internal Business Locations:
This approach can be extend to other use cases, such us:
- Employee hierarchies
- Approval chains
- Flow executions
- CMDB relationships
- Etc
Recommendations for Improvement
-
Code Review: The current scripts were written quickly and should be reviewed for:
- Performance optimization (e.g., reduce redundant iterations)
- Error handling
- Code readability and comments
- Alignment with corporative development guidelines
-
Filtering: Apply filters to exclude inactive or irrelevant records.
-
Scalability: Consider pagination or lazy loading for large datasets.
-
User Experience: Add tooltips, icons, or color coding to enhance clarity.
- Consider reducing any internal interactions of the node macro component with the server side. Move data fetching/updates to the level of the page that contains the Node Map. Consider using only visual non-connected components for the node macro component.
- To notify the parent page about an update on any of the nodes, use the SN_NODE_MAP#COMPONENT_NODE_EVENT action. On the Node Map, configure a handler for the Wrapped node event (SN_NODE_MAP#WRAPPED_NODE_EVENT) action to encapsulate the original COMPONENT_NODE_EVENT and the data object for the node that triggered the action.
- For compliance with WCAG accessibility standards, to allow screen readers to read out all the relevant internal states and labels inside the custom node macro component, add the attribute aria-label or aria-labelledby on the first element inside the shadowRoot of the custom node component.
- Be certain to select appropriate Width (nodeWidthMode) and Height (nodeHeightMode) properties and any associated value properties.
Useful Links
- ServiceNow Documentation:
Final Thoughts
Visualizing relationships between records can transform how users interact with data. With a few enhancements, this Node Map implementation can become a robust tool for navigating organizational structures in ServiceNow, from employee hierarchies to complex approval flows, ticketing systems, CMD relationships, and more.
We hope this article has been useful. If it truly addressed your needs, please consider marking it as helpful. If not, we’d greatly appreciate your feedback so we can improve and better support our community. Feel free to reach out with any questions.
Thank you!
#uib #uibuilder #nextexperience #workflow #page #script #dataresource #nodemap #visual #diagram #map ##nowassist #automation#getfamiliar #guide #lab #serviceNow
Kind regards,
Luis Estéfano
