Smartscape node and edge extraction in OpenPipeline

Latest Dynatrace
Explanation
5-min read
Published Apr 30, 2026

This article describes OpenPipeline Smartscape node and edge stages and the processors for topology definition. It describes the available parameters and provides examples.

Key terms

Node: A Smartscape entity instance. Nodes carry an ID, a type, and mutable information, such as fields and static edges, that can change over the entity's lifetime.
Edge: A relationship between two nodes. Can be static (stored on the node, inherits its lifetime) or dynamic (recorded at a specific point in time).
Smartscape ID: A unique identifier calculated from a node type and one or more ordered ID components. OpenPipeline calculates the ID and enriches the source record with it. The ID is stored in a dt.smartscape.<type> field.

To learn more, see Smartscape on Grail and the Smartscape model reference.

Overview

OpenPipeline provides two dedicated stages for Smartscape topology on Grail: the Smartscape node stage and the Smartscape edge stage. They define custom topology and relationships from records, including metrics, logs, spans, and events.

In the Smartscape node stage, records are enriched with a Smartscape ID. Any record that carries a Smartscape ID is associated with that entity in queries. If configured, a node can be extracted to update the Smartscape storage.
The Smartscape edge stage extracts a dynamic edge between two entities in a specific moment in time, using Smartscape IDs already present on the records.

Additionally, you can:

Parse the record fields via the Processing stage, for example, to derive a display name from existing dimensions. This can simplify Smartscape processor configuration, for example, when a field you need doesn't exist in its final form on the record.
Control who can access the node in queries by adding a dt.security_context field on a Smartscape node via the Security context stage.

Security context applies to nodes only. Smartscape edges are not independently queryable; they're only accessible in the context of a source or target node.

Smartscape node stage

In the Smartscape node stage, every matching record is enriched with a Smartscape ID. When Extract node is enabled, the processor also creates or updates the node in Smartscape storage. A single pipeline can contain multiple Smartscape node processors. Processors run top to bottom, and each can target a different node type. This allows you to calculate the Smartscape ID in one processor and reference it as a static edge target in the next.

Use this stage to:

Enrich records with a Smartscape ID. Any record that carries a Smartscape ID field is queryable in the context of that entity.
Create or update a node in Smartscape storage with fields and static edges.

Smartscape node processor

The Smartscape node processor calculates a Smartscape ID from the specified node type and ID components, and enriches the record with it. Its primary function is to ensure that records are associated with the related entity via Smartscape ID.

When Extract node is enabled, the processor can also create or update a node in Smartscape storage, including configured fields and static edges. This option is useful when the record carries properties that update the entity in Smartscape storage, such as the version.

The processor parameters correspond to the SmartscapeNodeAttributes object in the builtin:openpipeline.<configuration.scope>.pipelines schema of the Settings API.

Name	API parameter	Description	Required
Name	`description`	Name of the processor	Required
Matching condition	`matcher`	DQL statement that identifies the records the processor applies to.	Required
Node type	`nodeType`	Uppercase string identifying the node type. The name must begin with `CUSTOM_` or `EXT_`, for example, `CUSTOM_TRUCK`. It must be unique in your environment.	Required
Node ID field name	`nodeIdFieldName`	Name of the field added to the record to hold the Smartscape ID. Defaults to `dt.smartscape.<type>`, for example, `dt.smartscape.custom_truck`. We recommend using the default value and changing it only if necessary.	Required
ID components	`idComponents`	Ordered list of components used to calculate the Smartscape ID. Each component maps an ID component key (`idComponent`) to a Referenced field name (`referencedFieldName`) on the record. The component value is taken from the reference field found on the record. Order is relevant.	Required
Extract node	`extractNode`	When enabled, OpenPipeline creates or updates the node in Smartscape storage. When disabled, the processor calculates the Smartscape ID and adds it to the record without generating a node event.	Optional

When Extract node is enabled, the following parameters are available.

Name	API parameter	Description	Required
Node name	`nodeName`	Display name for the node instance. Use Field name to derive the name from a record field, or Static string to set a fixed value. Required only when Extract node is enabled.	Required
Fields to extract	`fieldsToExtract`	The record field-values to store as node properties, for example, a hardware model or version. Each entry maps a Field name (`fieldName`) to a Referenced field name (`referencedFieldName`) on the record. Fields to extract can be custom (manually entered and added values) or predefined (recommended fields that can be selected and deselected). Use for properties that change infrequently, such as a hardware model or version. For information that is best captured at a specific moment in time, extract a dynamic edge via the Smartscape edge stage instead.	Optional
Static edges to extract	`staticEdgesToExtract`	Static edges to store on the node, inheriting its lifetime. Each entry specifies an EDGE_TYPE (`edgeType`), a CUSTOM_NodeType (`targetType`), and a Referenced field name (`targetIdFieldName`)—the record field holding the Smartscape ID of the target node. The edge type can be a predefined type (for example, `contains`, `is_child_of`, `runs_on`) or a custom string. Note that extracting a static edge overrides others of the same type.	Optional

Example: Enrichment and node update

These examples are taken from the Define custom topology via OpenPipeline tutorial, which walks through a complete pipeline configuration.

This example calculates a Smartscape ID for incoming truck metrics so that they can be queried in the context of the entity. A processor targeting truck.* metrics is configured to calculates the Smartscape ID and enrich the record with it.

The processor matching condition is:

matchesValue(metric.key, "truck.*")

Unprocessed

{
  "metric.key": "truck.fuel.total",
  "trucknr": "0123456789ABCDEF",
  "model": "company-model_1"
}

Processed

{
  "metric.key": "truck.fuel.total",
  "trucknr": "0123456789ABCDEF",
  "model": "company-model_1",
  "dt.smartscape.custom_truck": "CUSTOM_TRUCK-0123456789ABCDEF"
}

dt.smartscape.custom_truck is now on every truck metric. The metrics are queryable in the context of the truck entity.

Truck metrics also carry model. This is a property that changes infrequently, but when it does change, the truck entity in Smartscape storage should reflect the latest value. To achieve this, Extract node can be turned on and model is added as a field to extract.

The record is structured as follows:

{
  "metric.key": "truck.fuel.total",
  "trucknr": "0123456789ABCDEF",
  "model": "company-model_2",
  "dt.smartscape.custom_truck": "CUSTOM_TRUCK-0123456789ABCDEF"
}

The processor updates the entity with Smartscape ID CUSTOM_TRUCK-0123456789ABCDEF in Smartscape storage with the field model and the latest value.

Smartscape edge stage

In the Smartscape edge stage, you can extract Smartscape dynamic edges for the records that match the condition of a Smartscape edge processor.

A dynamic edge requires that both the source and target Smartscape IDs are already present as fields on the record when the processor runs. Calculate them before, using a Smartscape node processor.

Smartscape edge processor

The Smartscape edge processor records a dynamic edge between two nodes, using Smartscape IDs already present on the records.

Processor field	API field	Description	Required
Name	`description`	The name of the processor.	Required
Matching condition	`matcher`	DQL statement that identifies the records the processor applies to.	Required
Source type	`sourceType`	Uppercase string identifying the node type of the source entity, for example, `CUSTOM_TRUCK`.	Required
Source ID field name	`sourceIdFieldName`	Name of the field that holds the Smartscape ID of the source node. Defaults to `dt.smartscape.<type>`, for example, `dt.smartscape.custom_truck`. We recommend using the default value and changing it only if necessary.	Required
Edge type	`edgeType`	The relationship between source and target. The edge type can be a predefined type (for example, `contains`, `is_child_of`, `runs_on`) or a custom string.	Required
Target type	`targetType`	Uppercase string identifying the node type of the target entity, for example, `CUSTOM_CONTAINER`.	Required
Target ID field name	`targetIdFieldName`	Name of the field that holds the Smartscape ID of the target node. Defaults to `dt.smartscape.<type>`, for example, `dt.smartscape.custom_container`.	Required

Example: Record a dynamic edge between trucks and containers

This example is taken from the Define custom topology via OpenPipeline tutorial.

The following example records a dynamic edge identifying the truck each container belongs to. The processors records a dynamic edge for every container metric. Both Smartscape IDs are already present on the record because the Smartscape node processors ran first.

The record is structured as follows:

{
  "metric.key": "container.temperature",
  "containernr": "865412",
  "trucknr": "0123456789ABCDEF",
  "dt.smartscape.custom_truck": "CUSTOM_TRUCK-0123456789ABCDEF",
  "dt.smartscape.custom_container": "CUSTOM_CONTAINER-865412"
}

The processor applies to records matching:

matchesValue(metric.key, "container.*")

The result is that the following dynamic edge is recorded: CUSTOM_TRUCK-0123456789ABCDEF contains CUSTOM_CONTAINER-865412.

Use cases

Define custom entity types: Enrich records with a Smartscape ID to represent custom sources as entities in Dynatrace.
Enrich Dynatrace built-in entities: Add topology fields to existing nodes, such as enriching a HOST node with a static edge.
Record telemetry relationships: When a single record carries identifiers for two different entities, use the Smartscape edge stage to record a dynamic edge.