Graph editor

Route: /service-topology/<topology-id> (also reachable by service name in the path)

The graph editor is a visual map of service, environment, and resource nodes connected by edges. You can overlay active alerts, configure per-node alert hierarchy rules, and persist the layout to the topology record.

The graph is a directed acyclic graph: the service node at the top, environment nodes under it, and resource nodes under an environment or under another resource of the same environment. A resource may have several parents. The server validates the whole graph on Save changes and writes the resource-to-resource edges to the resource graph; the data model and the error codes are described in the Service topology API.

See also: Overview · Topologies · Weight policies · Import and export

Editor layout

Area	Purpose
Header breadcrumb	Service Topology / <topology name> — click Service Topology to return to the list
Display options (dropdown, always visible)	Show alerts, Fluid animations toggles
More actions (dropdown, view mode only)	Reload alert count, Reload topology, Export (complete file from the server — see Import and export), Export to JSON, Import from JSON
Edit mode button	Enter edit mode (view mode only)
Alert-driven service topology button (edit mode only)	Bootstrap suggested nodes computed by the server from the service's active alerts and the resource graph
Save changes split button (edit mode only)	Main action Save changes; its dropdown caret opens Exit edit mode, Reset changes, Import from JSON, Export to JSON
Canvas controls (bottom left)	Fit view, Undo, Redo, and a layout/order icon
Search for a node	Jump to a node on the canvas (enabled in edit mode)
Minimap	Overview of the full graph
Alerts table	Opens below the graph when you click an alert badge or choose View alerts from a node menu

Open the editor

1. Open Management → Service Topology (Services tab).
2. Click View (eye icon) on a row, or click the Service column.
3. You can also open a topology from View Topology on the Services view, the alerts dashboard, or a Service topology widget on a service dashboard.

Rich vs clean topologies

Operators often maintain two kinds of maps:

Scenario	Typical service	Graph content	What you see with Show alerts
Rich (alert-driven)	A service with active alerts (for example main-web-service)	Many environments and resources built from alert history	Severity colors on nodes and edges, alert badges, optional Fluid animations on edges
Clean (manual)	A service with little or no alert traffic (for example a documentation or staging service)	A small tree you draw by hand	Mostly green / neutral nodes — useful for layout and hierarchy work without alert noise

The examples below use main-web-service for alert-driven and alert-overlay steps, and a separate manual topology for the clean tree.

View vs edit mode

Mode	What you can do
View (default)	Pan and zoom, toggle Show alerts / Fluid animations (via Display options), Reload alert count, Reload topology, Export to JSON (via More actions), search nodes (read-only)
Edit mode	Drag nodes, add and delete nodes, connect edges, run Alert-driven service topology, Save changes, undo/redo, layout tools, Import from JSON (via the Save changes dropdown)

Click Edit mode in the header to start editing. When finished, click Save changes to persist the graph to the topology record.

Unsaved changes

Reset changes discards edits in the current session. Reload topology reloads the last saved graph from storage — it is not the same as Reset changes.

Header controls

Control	Description
Display options ▾	Popover with Show alerts and Fluid animations toggles — alert badges, node colors, edge labels, and edge animation
More actions ▾ (view mode)	Reload alert count, Reload topology, Export (complete file from the server), Export to JSON, Import from JSON (writers)
...
Save changes dropdown ▾	Exit edit mode, Reset changes, Import from JSON (mapping drawer), Export to JSON

After large alert bursts or policy changes, open More actions → Reload alert count before relying on node colors.

Graph toolbar (edit mode)

Control	Description
Alert-driven service topology	Add suggested environment and resource nodes from existing alerts for this service
Save changes	Persist nodes and edges to the topology record; exits edit mode on success
Save changes dropdown ▾	Exit edit mode, Reset changes, Import from JSON (opens the mapping drawer), Export to JSON
Undo / Redo	Ctrl+Z / Ctrl+Y (or Shift+Ctrl+Z) — bottom-left canvas controls
Fit view	Zoom to fit all nodes — bottom-left canvas controls
Search for a node	Select a node to center the viewport on it

Create nodes manually

Build the hierarchy from the root service node downward: service → environment → resource, and resource → resource for deeper levels. Each node accepts only one new child through the + handle at a time; add deeper levels from the leaf node you want to extend. A resource that depends on two parents (a database used by two applications) is one node with two incoming edges: connect the second parent to the existing node instead of creating it twice — two resource nodes with the same name in the same environment are rejected on save (duplicateResource).

1. Open the graph and click Edit mode.
2. On a node without children, click the + handle below the node (service nodes get environment children; environment nodes get resource children).
3. In the inline Create a new environment or Create a new resource card, enter or select a name, optionally pick an icon and Description, then click Create.
4. Repeat for additional environments and resources.
5. Click Save changes when the structure is complete.

Clean manual tree example

When you build a small tree on a service without alert history, nodes stay neutral even with Show alerts on:

Node types

Type	Role
service	Root service node (largest icon); exactly one per topology, never a child
environment	Environment layer, directly under the service node; one node per environment name
resource	Resource layer under an environment or under another resource of the same environment; may have several parents; one node per resource name within an environment
build	Inline placeholder card while you are adding a new child

The server derives each node's environment and resource from its position in the graph when you save; a resource reachable from two different environments is rejected (resourceInMultipleEnvironments).

Double-click a permanent node in edit mode, or right-click and choose Edit node, to open the full configuration dialog.

Alert-driven service topology

Use this workflow to bootstrap a substantial graph from alert data. It works best on a service that already has alerts — for example main-web-service linked to your topology’s Service to fetch field.

The suggestions are computed by the server (POST /api/service_topology/<id>/suggest — see Suggest nodes from alerts) from the service's active alerts and the resource graph:

• an environment node for every environment that raises alerts and is not in the graph yet;
• a resource node for every alerting resource that is not a node yet, placed under its parents: the chain of parents comes from the resourceParent the alerts declare and, when an alert has none, from the resource's main parent in the resource graph, walking up until a resource that is already a node (or the environment).

Resources and environments that are already nodes are skipped. Nothing is saved until you accept suggestions and click Save changes.

1. Open the graph and click Edit mode.
2. Click Alert-driven service topology in the header. A tooltip explains that suggested nodes come from existing alerts.
3. Suggested environment and resource nodes appear with a pulsing style and dashed edges, already chained under their parents.
4. Accept suggestions:
   • Click an individual suggested node to promote it (and its connected suggested children).
   • Click the green forward icon on a node to Add all recursively under that branch.
   • On the service node, use Add all suggestions when suggested children are linked.
5. Optionally click Order nodes to tidy the layout.
6. Click Save changes.

No suggestions?

If the service has no alerts yet, Alert-driven service topology may add nothing. Create nodes manually or wait until alerts arrive for that service, then run the action again. Confirm the topology Service to fetch matches the service that receives alerts.

Show alerts on the graph

Use a saved, alert-rich tree (for example one built from main-web-service) to see severity colors clearly:

1. Open the graph (view or edit mode).
2. Open More actions → Reload alert count so counts and colors reflect the latest data.
3. Open Display options and turn Show alerts on.
4. Nodes and edges use severity colors; badges show alert counts. Edge labels can display text like 3 alerts on connected edges.
5. Turn Fluid animations on to animate edges that carry alerts.

The editor paints the alerts the server assigns to each node (GET /api/service_topology/<id>/assignments — see Alert assignments):

The alert's resource…	Shown on
is a resource node of its environment	that resource node
is not a node, but one of its ancestors in the resource graph is (the alert's own resourceParent counts first)	the first ancestor that is a node
has no ancestor in the graph, but its environment is a node	the environment node
none of the above	not shown on the graph (unassigned)

Counts then roll up from resources to their environment and to the service. Because of the second rule, an alert on a virtual machine you did not draw still colors the hypervisor node it hangs from in the resource graph.

Alerts table

When Show alerts is on, click an alert badge on a node or choose View alerts from the node context menu. A filtered alerts table opens in the lower panel for that node’s alerts. Use Details on a row to inspect an alert. Close the panel with Close in the table header.

Node configuration dialog

Open from Edit node in the context menu or by double-clicking a node in edit mode.

Area	Description
Icon of the node	Font Awesome or custom SVG
Description	Optional notes
Alert hierarchy configuration	Per-node SLA/performance inheritance
Disable hereditary from parents	Stop inheriting severity rules from parent nodes
Do not count for SLA availability / Do not count for SLA performance	Exclude node from SLA roll-ups
Severity levels to consider (for SLA availability)	Fine-tune which severities count for SLA availability
Severity levels to consider (for SLA performance)	Fine-tune which severities count for SLA performance

Click Update to apply changes to the canvas (still requires Save changes to persist to the topology record).

Node context menu (edit mode)

Right-click a node in edit mode:

Action	Description
Edit node	Open configuration dialog
View alerts	Open the alerts table for this node (when alerts are present)
Collapse nodes / Expand nodes	Hide or restore child subtrees on the canvas. Collapsing only hides: collapsed nodes are still saved with Save changes and included in Export to JSON
Move node to root	Attach directly under the service root
Move node under another node	Reparent subtree — choose Select Target Node
Delete node	Remove node (and connected children when confirmed)

Layout and navigation

Action	How
Order nodes	Click the sitemap icon in the bottom-left controls
Toggle order	Switch between top-bottom, left-right, and circular layouts
Fit view	Zoom to fit all nodes
Search for a node	Select from the dropdown (edit mode)
Pan / zoom	Drag the canvas background; use mouse wheel or minimap

Import from JSON

Import from JSON replaces the graph on the canvas with a tree mapped from a JSON file or pasted payload. The map is not saved until you click Save changes.

Open the drawer from:

• View mode: More actions → Import from JSON
• Edit mode: Save changes dropdown (caret) → Import from JSON

The drawer is resizable. You can choose a JSON file or paste JSON, then pick a Source format.

Source format	Typical JSON shape
ToBeAlert (native)	Export from this editor: { "topology": {…}, "nodes": [...], "edges": [...] } — the topology record plus its nodes (with stable IDs) and edges, so a resource with several parents is preserved. Exports from earlier releases (a service root with nested environment and resource children) are still accepted and converted on import
Vue Flow / React Flow	nodes plus edges (source / target)
Cytoscape.js	elements.nodes / elements.edges
D3 / force graph	nodes plus links (source / target)
Datadog service map	services plus calls (from / to)
Dynatrace Smartscape / service flow	nodes with entityType plus edges (from / to)
Elastic APM service map	elements.nodes / elements.edges
AWS X-Ray service graph	Services with nested Edges
Custom / generic JSON	You set node and edge field paths yourself

ToBeAlert only stores service → environment → resource. For each distinct value of the JSON type field (for example group in a D3 file, or web / db in a Datadog export), choose what it becomes:

Kind	Meaning
Service	Application / service node
Environment	Environment, cluster, or stage
Resource	Database, host, API, queue, and similar
Skip	Do not import those nodes

Each row shows the JSON field and value, how many nodes match, and sample names. Default node kind when type is missing applies when a node has no type. Turn on Place imported nodes under this topology service to wrap the imported graph under the current topology’s service.

Preview shows how many service, environment, and resource nodes the mapping would create. If the mapping would break the editor (for example an icon or label that is not text), Import from JSON stays disabled and the drawer lists the reason.

1. Open Import from JSON.
2. Choose a file or paste JSON.
3. Confirm Source format (auto-detected when possible; D3 files that use id / group are adjusted automatically).
4. Map each source type, or skip types you do not want.
5. Check Preview, then click Import from JSON.
6. Click Save changes to persist.

Datadog and D3 exports

A Datadog Service Map in the product UI does not export services + calls directly. The Datadog Service Dependencies API returns a map of service names to dependency lists — convert that to services and calls before import. Classic D3 examples (for example Les Misérables) use numeric group values, not service/environment/resource names — map each group in the drawer.

Save the graph

1. Make structural or configuration changes in Edit mode.
2. Click Save changes. The map is not auto-saved on navigation.
3. Edit mode closes after a successful save. Re-enter edit mode for further changes.

Save changes sends the complete graph — every node and edge, including subtrees you collapsed — and the server replaces the stored graph with it, then updates the resource graph relations of this topology (source topology). The server validates the graph first; if it is invalid, nothing is stored and the editor lists each problem with its error code and the node or edge it concerns, for example:

Code	Meaning	Fix
cycle	The edges form a loop	Remove one of the edges listed in the message
duplicateResource	Two resource nodes with the same name in one environment	Keep one node and connect it to both parents
resourceInMultipleEnvironments	A resource's parents lead to two environments	Create one node per environment
environmentNotUnderService	An environment node has a parent other than the service node (or more than one)	Attach it directly to the service node
resourceWithoutEnvironment	A resource node is not connected to any environment	Attach it, or its parent, to an environment
serviceNodeCount	The graph has no service node, or more than one	Keep exactly one
idCollision	A node ID is already used by another topology (for example after importing another topology's export)	Re-create the node, or import with new IDs

The full list is in the Service topology API — Validation rules.

Export to JSON writes { "topology", "nodes", "edges" } with the complete graph (collapsed subtrees included). Use it before large restructuring as an offline backup. After Import from JSON, always Save changes to persist the new graph.

Import and export

The editor offers two ways to move a topology in and out, which serve different purposes:

Action	Where	What it moves	Saved?
Export	More actions ▾	The saved topology as a complete server file: record, nodes and edges with IDs and positions, the weight policies that apply to the service, and the catalog entry (kind: tobealert-service-topology)	Reads the stored topology; unsaved canvas changes are not included
Export to JSON	More actions ▾ / Save changes ▾	The canvas as { "topology", "nodes", "edges" }, unsaved changes included	—
Import from JSON	More actions ▾ / Save changes ▾	A JSON file mapped onto the canvas (see above)	Only when you click Save changes
Import	Services tab header	A server file, a bundle, an editor export, a file from an earlier release, or flat CMDB records — applied by the server in Replace or Merge mode after a preview	Immediately

The server-side import and export, the file format, and the Replace / Merge rules are described in Import and export. To build topologies from a CMDB extract (one line per resource, with its parent and its services), see Importing from a CMDB.

Best practices

1. Enter Edit mode only when you need structural changes — reduces accidental drags.
2. Save changes after meaningful edits; unsaved graph changes are lost on navigation unless you save.
3. Run Alert-driven service topology on a service with real alert history (for example main-web-service), use Add all recursively, then Save changes before tuning layout or overlays. Send resourceParent with your alerts so the suggestions already come with the right parents.
4. Model shared resources once — one node with several parents instead of a copy under each parent; copies are rejected on save.
5. Reload alert count after incidents so severity colors reflect current state; toggle Show alerts and Fluid animations to validate the overlay.
6. Keep a clean manual topology on a low-traffic service when you need screenshots or templates without alert coloring.
7. Export (or Export to JSON) before large restructuring as a backup; use Import from JSON to bring maps from other tools, then Save changes. To restore a backup or copy a topology between instances, use Import on the Services tab — see Import and export.
8. Configure hierarchy on leaf resources when SLA availability or performance should differ from parents.