Upgrade your custom charts now

Dashboards Classic

If you use Custom charts in your dashboards, you need to read the following text.

Immediate action required

For details, see below.

Does this apply to me?

This does not apply to visualizations and dashboards created using Data Explorer. This applies only to our old Custom charts functionality, which predated Data Explorer and is now fully deprecated.

Check the Dashboards table

To see if you have any old-style custom charts to upgrade, filter the Dashboards table by Custom charts: Yes and see if any dashboards are listed.

Check tiles on the dashboard

When you find a dashboard that has custom charts, open it and look for the following indicators that it has old-style custom charts that should be upgraded:

How can I upgrade?

Before you do anything else, we recommend that you make backups of your most important dashboards. Then try to upgrade the backups so you get comfortable with the upgrading process before upgrading all of your remaining dashboards.

For example, pick any popular dashboard in your environment that you depend on, maybe one that has several advanced and complex Custom chart tiles (multiple metrics are used, and there are configurations for a unit, rates, etc.), and clone it. Then you can safely work on the clone and check whether everything upgrades correctly.

You can upgrade:

In all cases, make backups before starting, and try it out first to familiarize yourself with the process.

Upgrade via web UI

In the web UI, you can upgrade one tile at a time or one dashboard at a time.

Upgrade one tile

To upgrade a single tile

Upgrade entire dashboard

You can run the following procedures with or without creating clones (backups).

Faster but with no backup steps

To upgrade an entire dashboard (all tiles on the dashboard at once) without creating a clone (backup copy).

Slower but with cautious backup steps

To create a clone (backup copy) of the dashboard and then upgrade the entire cloned dashboard (all tiles on the dashboard at once)

Alternative procedure from the dashboard menu

You can run this procedure with or without creating a backup (see step 3).

When a dashboard upgrade is complete:

Check for more dashboards to upgrade

To check for more dashboards to upgrade

For details on identifying dashboards and charts that still need to be upgraded, see the Does this apply to me? section above.

Upgrade via API

Dynatrace version 1.251+

Using the Dynatrace API, you can upgrade one dashboard at a time or all dashboards at once. In any case, the API will always conveniently skip dashboards that don't have any Custom charts on them, which removes the need to first filter out dashboards without Custom charts.

Upgrade one dashboard

To upgrade one dashboard via API, use the migrate endpoint.

https://{your-environment-id}/rest-api-doc/index.jsp?urls.primaryName=Configuration%20API#/Dashboards/migrateDashboard

Make sure to replace {your-environment-id} with your actual environment ID.

Upgrade all dashboards

To upgrade all dashboards via API

Node.js example script

To get you started quickly, feel free to adapt and use the following example Node.js script. We used it to bulk update all dashboards of our own development environment.

Before using the script, make sure you update both lines marked with // TODO with your own information:

import fs from "fs";
import fetch from "node-fetch";

async function migrateAllDashboards() {
  // create a backup directory
  if (!fs.existsSync("./BACKUPS")) {
    fs.mkdirSync("./BACKUPS");
  }

  export const ENV_URL = "{your-environment-id}"; // TODO replace this
  export const AUTH_HEADERS = {
      Authorization: `Api-token {your-api-token}`, // TODO replace this
   };
  const dirName = `./BACKUPS/${new URL(ENV_URL).hostname.replace(
    ".",
    "_"
  )}-${Date.now()}`;
  fs.mkdirSync(dirName);

  console.log("Fetching all the dashboards");
  const fetchAllUrl = `${ENV_URL}/api/config/v1/dashboards`;
  const response = await fetch(fetchAllUrl, { headers: AUTH_HEADERS });
  const dashboardsMetadata = await response.json();
  fs.writeFileSync(
    `${dirName}/_ALL_DASHBOARDS_METADATA.json`,
    JSON.stringify(dashboardsMetadata)
  );
  const allDashboards = dashboardsMetadata.dashboards;
  console.log(`Saved the metadata of ${allDashboards.length} dashboards`);

  for (let index = 0; index < allDashboards.length; index++) {
    const db = allDashboards[index];
    const dbId = db.id;
    const fetchDB = `${ENV_URL}/api/config/v1/dashboards/${dbId}`;
    const response = await fetch(fetchDB, { headers: AUTH_HEADERS });
    const dbContent = await response.json();
    // save dashboard content to backup directory
    fs.writeFileSync(`${dirName}/${dbId}.json`, JSON.stringify(dbContent));

    try {
      // attempt migration
      const migrateResponse = await fetch(
        `${ENV_URL}/api/config/v1/dashboards/${dbId}/migrate`,
        {
          method: "PUT",
          headers: {
            "Content-Type": "application/json",
            ...AUTH_HEADERS,
          },
          body: dbId,
        }
      );

      if (migrateResponse.status === 200) {
        if (migrateResponse.errors) {
          console.log(`X ${dbId} updated failed!);
          console.error(migrateResponse.errors);
        }
      } else {
        console.error(`X ${dbId} update failed!`);
        console.error(migrateResponse);
      }
    } catch (error) {
      console.error(`X ${dbId} update failed!`);
      console.error(updateResponse);
    }
  }
}

console.log("### Backup and Migrate\n");
await migrateAllDashboards();
console.log(`### Migration completed\n\n`);

Check for more dashboards to upgrade

To check for more dashboards to upgrade

For details on identifying dashboards and charts that still need to be upgraded, see the Does this apply to me? section above.

What should I do if an upgrade fails?

Depending on the complexity of the tiles involved, a dashboard upgrade could fail partially (some tiles on the dashboard upgrade successfully and others don't) or completely (no tiles on the dashboard upgrade successfully).

In any case, don't worry about losing data. Dashboards and tiles are visualizations of your data, not the data itself. Your data is never at risk during an upgrade.

Where can I get more information?