Relic Solution: Improving compatibility between New Relic One and the Insights Dashboard API

New Relic One introduced a new 12-column grid for dashboards. That's cool, right?

Correct! New Relic One opened up a (literally) wide range of possibilities for beautiful and complex dashboards. At the same time, those dashboards are still backwards-compatible with Insights, though when viewed in original New Relic they will appear to fit a 3-column grid.

How does that backwards compatibility work behind-the-scenes?

As exposed through the Dashboard API, you might find the underlying schema for a dashboard to look something like this:

{
  "dashboard": {
    "title": "Untitled",
    "description": null,
    "icon": "bar-chart",
    "visibility": "all",
    "editable": "editable_by_all",
    "metadata": {
      "version": 1
    },
    "widgets": [
      {
        "visualization": "faceted_line_chart",
        "layout": {
          "width": 3,
          "height": 3,
          "row": 1,
          "column": 1
        },
        "data": [
          {
            "nrql": "FROM Metric SELECT average(synthetics.metric) FACET location.name TIMESERIES"
          }
        ],
        "presentation": {
          "title": "",
          "notes": null
        }
      }
    ],
    "filter": null
  }
}

A dashboard schema like the above might mean one of two things. It could mean tall, full-width widgets in Insights and New Relic One:

And yet, at the same time, this schema might be representative of a dashboard with much smaller widgets:

So what's the difference there?

To reiterate, dashboards created in Insights will conform to a 3x3 layout, while dashboards created in New Relic One conform to a 12x12 layout.

This means that if I set a widget’s height and width to 3, a dashboard with 3 columns will display a widget that’s as long as it is wide. Likewise, a widget with a height and width of 3 on a 12x12 dashboard will display that same widget at 1/4th the maximum height and width in New Relic One.

With regards to the UI, here’s a cheat sheet you can use to determine how the grid layout is set:

  • Dashboards are conformed to a 12x12 layout if…
    • A dashboard is created in New Relic One
    • A preexisting 3x3 dashboard is updated in New Relic One
  • Dashboards are conformed to a 3x3 layout if…
    • A dashboard is created in Insights
    • A preexisting 12x12 dashboard is updated in Insights

Also of note: if you open a 12x12 dashboard in Insights, every widget will appear as if it’s 1x1 on a 3-column grid.

How does the Dashboard API handle the difference between grid layouts?

Let’s return to the schema I posted earlier:

{
  "dashboard": {
    "title": "Untitled",
    "description": null,
    "icon": "bar-chart",
    "visibility": "all",
    "editable": "editable_by_all",
    "metadata": {
      "version": 1
    },
...
}

That’s an example of some of the top-level information returned by a GET call. You might notice something missing: specifically, there’s nothing that defines whether the dashboard has a 3-column or 12-column layout.

By default, when a dashboard is created through the Dashboard API, it is assigned the 3x3 grid. Meaning — if I create a new dashboard and provide the exact schema that I posted at the top of this guide, it will appear like so:

This is because of a field called "grid_column_count". While it is not exposed via GET, it is always present in a dashboard’s underlying schema, as it tells us how to represent and arrange the dashboard’s widgets in the UI.

By default, when a dashboard is created through the API, it is assigned a "grid_column_count" value of 3. Behind-the-scenes, this means your schema looks like the following:

{
  "dashboard": {
    "grid_column_count": 3,
    ...
    },
...
}

Likewise, any dashboard that has been conformed to the 12x12 layout in the UI is then assigned a "grid_column_count" value of 12.

Most importantly, if you pass "grid_column_count": 12 when creating a dashboard, you can programmatically create dashboards that take advantage of the New Relic One 12-column layout.

Take this example:

{
  "dashboard": {
    "grid_column_count": 12,
    "title": "Untitled",
    "description": null,
    "icon": "bar-chart",
    "visibility": "all",
    "editable": "editable_by_all",
    "metadata": {
      "version": 1
    },
    "widgets": [
      {
        "visualization": "faceted_line_chart",
        "layout": {
          "width": 3,
          "height": 3,
          "row": 1,
          "column": 1
        },
        "data": [
          {
            "nrql": "FROM Metric SELECT average(synthetics.metric) FACET location.name TIMESERIES"
          }
        ],
        "presentation": {
          "title": "",
          "notes": null
        }
      }
    ],
    "filter": null
  }
}

Rather than the enormous widget this schema would have produced by default were it using the 3-column grid, specifying "grid_colum_count": 12 allows us to take advantage of that spacious New Relic One layout:

So, is "grid_column_count" going to solve all of my problems?

Possibly! If you have a need to explicitly specify whether you want your widgets to be arranged on a 3- or a 12-column grid — or if you’ve longed for interoperability between the Dashboard API and the New Relic One layout — "grid_column_count" is here for you.

9 Likes

This is a life-saver.

Really surprised this information hasn’t been included in the Dashboard API documentation itself.

2 Likes

Appreciate hearing that feedback @rishav.dhar. :star_struck: