Convert unified analysis (UA) pages

Latest Dynatrace
How-to guide
10-min read
Published Jul 16, 2026

Classic unified analysis (UA) pages for extension entities are defined in the screens: section of your extension.yaml. The latest Dynatrace Platform instead renders pages from standalone documents (JSON) that target Smartscape nodes, which unlocks capabilities such as DQL-powered tables, Infrastructure & Operations, and richer injections.

This guide shows you how to use Dynatrace Extensions to convert your existing Classic UA pages into platform documents automatically, review the result, and deploy them with your extension.

Make sure your workspace is connected to a Platform environment. If your tenant connection still uses a Classic URL or access token, follow the Update your tenant configuration guide first.

Prerequisites

Complete the first-time setup for your editor.

This guide assumes you have already configured your editor and registered your workspace. If you're new to Dynatrace Extensions for VS Code, follow the Getting started guide first.
Have an Extension 2.0 project with topology and UA pages defined.

Your extension.yaml must define both a topology.types section and at least one entry in the screens: section. The conversion has nothing to work with otherwise.
Convert your topology to Smartscape first.

Page documents target Smartscape nodes, not the legacy entity types. Before converting pages, run the Dynatrace extensions: Create Smartscape Topology command to generate the OpenPipeline files that map each entity type to a Smartscape node. You can read more in the Convert topology guide.

The page conversion links each entity type to its node through the id_classic field extracted in the generated OpenPipeline files. If you edited those files, make sure id_classic is still extracted for every node, or the matching entity types won't be offered for conversion.

What the command converts

The command walks through each page definition and rebuilds its layout as one or more platform documents. Not every classic construct has an equivalent in the new format, so some content is intentionally skipped and recorded in the conversion report.

Classic content	Result
`detailsSettings`	An entity details document, using a tabs layout, with each card placed on its own tab
`listSettings`	An inventory document with a primary DQL table
`detailsInjections` / `listInjections`	One injection document per injection, targeting the resolved node type
Chart cards, DQL table cards, health cards	Converted into the equivalent platform layout elements, with DQL adjusted to query Smartscape nodes
Message cards	Aggregated into a single Messages tab
Properties card	Added as a Metadata card on the details document
Content targeting `CLASSIC`	Skipped—it has no place on the Platform
Breadcrumbs, entity/metric tables, events, logs, and problems cards	Skipped—no equivalent in the new format

If you're new to unified analysis, find out how to deploy an extension with UA page documents.

Convert your pages

Open your registered workspace in VS Code.
Press F1 and select the command Dynatrace extensions: Convert screens.
Select the entity types to convert pages for.

Only entity types that both have pages defined and resolve to a Smartscape node are offered, along with any built-in entities that carry injections. Pick one or more, then confirm.

The command creates the screens folder if needed and writes the generated documents to extension/screens/. The files are named after the Smartscape node type they target:

<node>-entitydetails.screen.json—the entity details document
<node>-inventory.screen.json—the inventory (list) document
<node>-<key>-detailsinjection.screen.json—one per details injection
<node>-<key>-inventoryinjection.screen.json—one per list injection
category-inventory.screen.json and extension-inventory.screen.json—generic inventory documents that register your extension and its category in Infrastructure & Operations

Your original YAML screens: section is left untouched; the command only adds the new documents alongside it.

Review the conversion report

Every run writes a conversion-report.md file into extension/screens/. Open it to see, per page, which files were produced and any warnings—for example, cards skipped because they targeted CLASSIC or have no platform equivalent.

Treat the report as your checklist. Where a card was dropped, decide whether you need to rebuild that content natively in the generated document. Because the documents are validated against the platform schema, VS Code also flags any structural issues and offers completion suggestions inline as you edit.

You can use the element reference to better understand how to change the generated documents.

Reference the files in the extension manifest

To upload the UA documents to your Dynatrace tenant as part of extension deployment, they need to be referenced within the documents section of the manifest:

documents:
  screens:
    - path: screens/file_name.screen.json

All file names must end in .screen.json.

Build and deploy

Once you're happy with the generated documents, package them and ship them with your extension.

Press F1 and select the command Dynatrace extensions: Build. The entire extension folder is bundled, so the new screens/ documents are included automatically.
When prompted, choose to upload the package to Dynatrace, then activate the new version.

For the full packaging workflow, see the Build command reference.

View your pages

After the new version is active, go to Infrastructure & Operations and look for your extension. By default, this is placed in the "Other" category.

You can change the category your extension is displayed in by editing the category-inventory.screen.json and extension-inventory.screen.json files.

While editing a *.screen.json document in VS Code, you can also use the code lens at the top of the file to open the corresponding page directly in Infrastructure & Operations.

Troubleshooting

Message	What to do
No topology or `screens` found in `extension.yaml`	Ensure your manifest defines both a `topology.types` section and at least one `screens:` entry
No OpenPipeline files found. Can only convert `screens` for Smartscape nodes	Run Create Smartscape Topology first to generate the OpenPipeline files
No pipeline nodes match your `screens` entity types	Make sure the `id_classic` field is extracted for your nodes in the OpenPipeline files so entity types can be matched