Importing from a CMDB

Route: /service-topology (Services tab) → Import → format CMDB (simple)

A CMDB knows which host runs which virtual machine, which database belongs to which service, and in which environment each of them lives. The CMDB import takes that knowledge as a flat list of records — one line per resource — and turns it into relations in the resource graph and into one service topology per service named in the file. You can re-run it every time the CMDB changes: an unchanged file writes nothing.

See also: Overview · Import and export · Graph editor · Resource graph API — Import from a CMDB

Why a flat schema

The topology export is a complete picture of one topology: node IDs, edges, canvas positions, weight policies. A CMDB does not have any of that, and you do not want to maintain it by hand in an export. The CMDB schema therefore has no IDs, no edges and no positions:

• a record is identified by its environment and resource name;
• the hierarchy is a single parent column — the parent resource in the same environment;
• the services column says which topologies the resource belongs to;
• node positions are computed automatically for new nodes and kept for existing ones.

Resources without services still go into the resource graph, where policies and cause-and-effect rules can use them, even if no topology shows them.

Record fields

Field	Required	Description
resource	Yes	Resource name, at most 255 characters. Leading and trailing spaces are removed
environment	No	Environment of the resource, at most 255 characters. When empty, the Default environment of the dialog is used; when that is empty too, the resource has no environment (""). Together with resource it identifies the record
parent	No	Name of the parent resource, in the same environment. It does not have to be in the file (warning unknownParent)
services	No	Services the resource belongs to. A JSON list, or a string with names separated by ; or | (CSV uses the same separators). service in the singular is also accepted. Empty: the record only feeds the resource graph
type	No	Free text, at most 100 characters (hypervisor, vm, database…). Stored as params.type of the topology node
attributes	No	Object of string values, stored as params.attributes of the node. In CSV, every column named attr.<key> becomes one attribute (empty cells are stored as empty strings)

Names are compared exactly after trimming: Prod and prod are two different environments, as everywhere else in ToBeAlert.

Templates

Download template in the dialog (JSON or CSV) downloads a six-record example from the server — two environments, a parent that is not in the file, and a record without services. Both files describe the same records.

JSON — a list, or an object with items:

{
  "items": [
    { "resource": "host-3", "environment": "prod", "services": ["payments"], "type": "hypervisor", "attributes": { "site": "madrid-1" } },
    { "resource": "vm-7", "environment": "prod", "parent": "host-3", "services": ["payments"], "type": "vm", "attributes": { "os": "linux" } },
    { "resource": "db-01", "environment": "prod", "parent": "vm-7", "services": ["payments", "billing"], "type": "database", "attributes": { "engine": "postgres" } },
    { "resource": "api-1", "environment": "prod", "parent": "k8s-cluster", "services": ["payments"], "type": "deployment", "attributes": {} },
    { "resource": "db-01", "environment": "staging", "services": ["payments"], "type": "database", "attributes": { "engine": "postgres" } },
    { "resource": "backup-nas", "environment": "prod", "services": [], "type": "storage", "attributes": {} }
  ]
}

CSV — UTF-8, a header row that must contain resource, comma or semicolon as separator (detected automatically), a BOM is tolerated:

resource,environment,parent,services,type,attr.site,attr.os,attr.engine
host-3,prod,,payments,hypervisor,madrid-1,,
vm-7,prod,host-3,payments,vm,,linux,
db-01,prod,vm-7,payments;billing,database,,,postgres
api-1,prod,k8s-cluster,payments,deployment,,,
db-01,staging,,payments,database,,,postgres
backup-nas,prod,,,storage,,,

Empty lines are skipped. Columns that are neither a known field nor attr.<key> are ignored with a warning (unknownColumn), so you can export more columns from the CMDB than ToBeAlert uses.

What the template produces on an empty instance:

• Resource graph: vm-7 → host-3, db-01 → vm-7 and api-1 → k8s-cluster in prod, all with source cmdb. k8s-cluster is not in the file (unknownParent), but the relation is created anyway so that an alert on api-1 can still find its parent.
• Service payments: created in the catalog and given a topology with the environments prod (host-3 → vm-7 → db-01, and api-1) and staging (db-01). api-1 hangs from the prod environment node because k8s-cluster is not in the service (parentNotInService).
• Service billing: created, with a topology holding prod → db-01. Its parent vm-7 is not part of billing, so db-01 hangs from the environment there.
• backup-nas: in the resource graph only (it has no parent and no services, so in practice it just counts as a graph-only record).

Importing

1. Open Management → Service Topology (Services tab) and click Import.

2. In Source, choose the file or paste its content. In Format, keep CMDB (simple) (detected for CSV and for JSON records without kind).

3. Set the options:

   Option	Description
   Source name	Label of this CMDB, default cmdb (at most 100 characters). It is stored as sourceRef on every relation and as params.cmdbSource on every node the import creates, and it scopes the Replace mode: only relations and nodes of this source are candidates for removal. Use one name per CMDB if you import from several
   Default environment	Environment for records whose environment is empty (warning environmentDefaulted for each)
   Mode	Merge (default) or Replace — see below
   Download template	JSON or CSV example from the server

4. Check the Preview: it is a full dry run on the server and shows the same counters as the real import.

5. Click Import.

What the import does

Resource graph. For every record with a parent, a relation resource → parent in the record's environment is written with source cmdb and sourceRef = the source name. A resource has one parent per CMDB: giving it a different parent replaces the previous relation of that source (counted as update). Relations the same resource got from other sources (an alert payload, a manual entry, a policy) are not touched.

Catalog and topologies. For every distinct service name in services:

• the catalog entry is created if it does not exist (serviceCreated); an existing entry is left as it is;
• the topology is created if it does not exist (topologyCreated), otherwise updated;
• one environment node per environment of the service's records, under the service node;
• one resource node per record, with params.cmdbSource, params.type and params.attributes. Existing nodes (same environment and resource) are reused and their parameters updated;
• an edge parent → resource when the parent is in the same service — or is already a node of the topology — and an edge environment → resource otherwise (parentNotInService when the record had a parent);
• positions: existing nodes keep theirs; new nodes are laid out automatically in layers.

The usual validation rules apply to the resulting graph — a cycle between the file's records is reported before anything is written.

Merge and replace

	Merge (default)	Replace
Records in the file	Relations and nodes created or updated	Relations and nodes created or updated
Relations of this source that are not in the file	Kept	Removed
Nodes with this cmdbSource that are not in the file	Kept	Removed from the topology, with their edges
Nodes drawn by hand or imported from another source	Kept	Kept
Edges to a resource of the file	Kept, the file's edge is added	Replaced by the file's edge (the parent in the file wins)

Neither mode deletes a topology, a catalog service, or relations from other sources. Replace is the mode for a scheduled export of the whole CMDB: resources that disappear from the CMDB disappear from the graph and from the topologies.

Idempotency

Importing the same file twice is a no-op: every counter is unchanged and nothing changes in the graph or the topologies. This is what makes it safe to schedule the import after each CMDB export. A record whose parent changed is reported as update on the relation and on the topology edges.

Relations from higher-ranked sources

If the same relation already exists with source manual or event, the CMDB import does not change its source (the resource graph keeps the highest-ranked declaration). The preview counts it as unchanged and nothing is written for it.

Warnings and errors

Warnings do not stop the import; errors reject the whole file (nothing is written). Each carries the record's row number (row) when it concerns one record.

Warning	Meaning
unknownParent	The parent is not a record of the file (same environment). The relation is created anyway
parentNotInService	The parent is not part of this service and not a node of its topology; the resource hangs from the environment node
unknownColumn	A CSV column that is neither a field nor attr.<key>; it is ignored
environmentDefaulted	The record had no environment; the default environment was used
serviceCreated	A catalog service will be created
topologyCreated	A topology will be created

Error	Reason
missingResource	A record without resource, or that is not an object
duplicateRecord	The same environment + resource appears twice
selfParent	A record whose parent is itself
cycle	The parents of one environment form a loop (a → b → a)
valueTooLong	resource, environment, parent or a service name longer than 255 characters, or type longer than 100
invalidCsvHeader	Empty CSV, or no resource column in the header
invalidJson	The content is not valid JSON or UTF-8, or is not a list of records / { "items": [] }
tooManyRecords	More than 50,000 records
bodyTooLarge	The file is larger than 20 MB
A graph validation code	The resulting topology of a service would be invalid (for example resourceInMultipleEnvironments after a merge with hand-drawn nodes)

Limits and permissions

Item	Value
Records	50,000 per import
File size	20 MB
Names	255 characters (resource, environment, parent, services), 100 for type and the source name
Import	write:service_topologies — the same as saving a topology. Relations are written with source cmdb without needing admin:service_topologies
Templates	read:service_topologies
Audit trail	resources-cmdb-imported per real import (mode, source and number of records)

What happens next

Once the CMDB is in the graph, the rest of ToBeAlert uses it without further configuration:

• Alerts get their parent. A Resource relation policy modifier with source Graph copies the resource's parent from the graph into resourceParent of every alert on that resource. An alert on vm-7 then shows host-3 as its parent in the alert details drawer, and the TQL filter resourceParent finds it.
• Cause and effect follows the hierarchy. A Mark as effect modifier with Cause is: Open alert on a parent resource turns alerts on vm-7 and db-01 into effects of an open alert on host-3 — see Cause on a parent resource.
• The topology lights up. The graph editor paints alerts on the nodes the server assigns them to: an alert on db-01 colors the db-01 node of the payments and billing topologies, and an alert on a resource that is not a node colors its first ancestor that is — see Show alerts on the graph.
• You can still edit by hand. Nodes added in the editor keep their place through later CMDB imports (both modes keep nodes that do not come from this source), and the topology can be exported like any other.

Best practices

1. Export from the CMDB on a schedule and import in Replace mode with a fixed Source name: the graph and the topologies follow the CMDB, and nothing drawn by hand is lost.
2. Fill environment in the CMDB export rather than relying on the default environment: relations and alerts only meet when the environment matches exactly.
3. Put a resource in every service that depends on it (payments;billing): the topologies show it in both, and the resource graph still has a single relation per parent.
4. Watch parentNotInService — a resource that hangs from the environment node usually means the parent should be added to that service too.
5. Run the preview on the first import of a new CMDB and check the serviceCreated / topologyCreated warnings: a typo in a service name creates a new service instead of filling the existing one.