History and Version Control for Dashboard Updates

A simple version control system for dashboards. Closes #1504. Goals 1. To create a new dashboard version every time a dashboard is saved. 2. To allow users to view all versions of a given dashboard. 3. To allow users to rollback to a previous version of a dashboard. 4. To allow users to compare two versions of a dashboard. Usage Navigate to a dashboard, and click the settings cog. From there, click the "Changelog" button to be brought to the Changelog view. In this view, a table containing each version of a dashboard can be seen. Each entry in the table represents a dashboard version. A selectable checkbox, the version number, date created, name of the user who created that version, and commit message is shown in the table, along with a button that allows a user to restore to a previous version of that dashboard. If a user wants to restore to a previous version of their dashboard, they can do so by clicking the previously mentioned button. If a user wants to compare two different versions of a dashboard, they can do so by clicking the checkbox of two different dashboard versions, then clicking the "Compare versions" button located below the dashboard. From there, the user is brought to a view showing a summary of the dashboard differences. Each summarized change contains a link that can be clicked to take the user a JSON diff highlighting the changes line by line. Overview of Changes Backend Changes - A `dashboard_version` table was created to store each dashboard version, along with a dashboard version model and structs to represent the queries and commands necessary for the dashboard version API methods. - API endpoints were created to support working with dashboard versions. - Methods were added to create, update, read, and destroy dashboard versions in the database. - Logic was added to compute the diff between two versions, and display it to the user. - The dashboard migration logic was updated to save a "Version 1" of each existing dashboard in the database. Frontend Changes - New views - Methods to pull JSON and HTML from endpoints New API Endpoints Each endpoint requires the authorization header to be sent in the format, ``` Authorization: Bearer <jwt> ``` where `<jwt>` is a JSON web token obtained from the Grafana admin panel. `GET "/api/dashboards/db/:dashboardId/versions?orderBy=<string>&limit=<int>&start=<int>"` Get all dashboard versions for the given dashboard ID. Accepts three URL parameters: - `orderBy` String to order the results by. Possible values are `version`, `created`, `created_by`, `message`. Default is `versions`. Ordering is always in descending order. - `limit` Maximum number of results to return - `start` Position in results to start from `GET "/api/dashboards/db/:dashboardId/versions/:id"` Get an individual dashboard version by ID, for the given dashboard ID. `POST "/api/dashboards/db/:dashboardId/restore"` Restore to the given dashboard version. Post body is of content-type `application/json`, and must contain. ```json { "dashboardId": <int>, "version": <int> } ``` `GET "/api/dashboards/db/:dashboardId/compare/:versionA...:versionB"` Compare two dashboard versions by ID for the given dashboard ID, returning a JSON delta formatted representation of the diff. The URL format follows what GitHub does. For example, visiting [/api/dashboards/db/18/compare/22...33](http://ec2-54-80-139-44.compute-1.amazonaws.com:3000/api/dashboards/db/18/compare/22...33) will return the diff between versions 22 and 33 for the dashboard ID 18. Dependencies Added - The Go package [gojsondiff](https://github.com/yudai/gojsondiff) was added and vendored.
2025-08-02 04:31:36 +08:00 · 2017-05-24 19:14:39 -04:00
parent 59f3cca135
commit b6e46c9eb8
60 changed files with 7843 additions and 84 deletions
--- a/pkg/api/dashboard.go
+++ b/pkg/api/dashboard.go
@ -2,8 +2,10 @@ package api

 import (
 	"encoding/json"
+	"fmt"
 	"os"
 	"path"
+	"strconv"
 	"strings"

 	"github.com/grafana/grafana/pkg/api/dtos"
@ -77,6 +79,7 @@ func GetDashboard(c *middleware.Context) {
 		},
 	}

+	// TODO(ben): copy this performance metrics logic for the new API endpoints added
 	c.TimeRequest(metrics.M_Api_Dashboard_Get)
 	c.JSON(200, dto)
 }
@ -255,6 +258,264 @@ func GetDashboardFromJsonFile(c *middleware.Context) {
 	c.JSON(200, &dash)
 }

+// GetDashboardVersions returns all dashboardversions as JSON
+func GetDashboardVersions(c *middleware.Context) {
+	dashboardIdStr := c.Params(":dashboardId")
+	dashboardId, err := strconv.Atoi(dashboardIdStr)
+	if err != nil {
+		c.JsonApiErr(400, err.Error(), err)
+		return
+	}
+
+	// TODO(ben) the orderBy arg should be split into snake_case?
+	orderBy := c.Query("orderBy")
+	limit := c.QueryInt("limit")
+	start := c.QueryInt("start")
+	if orderBy == "" {
+		orderBy = "version"
+	}
+	if limit == 0 {
+		limit = 1000
+	}
+
+	query := m.GetDashboardVersionsCommand{
+		DashboardId: int64(dashboardId),
+		OrderBy:     orderBy,
+		Limit:       limit,
+		Start:       start,
+	}
+
+	if err := bus.Dispatch(&query); err != nil {
+		c.JsonApiErr(404, fmt.Sprintf("No versions found for dashboardId %d", dashboardId), err)
+		return
+	}
+
+	dashboardVersions := make([]*m.DashboardVersionDTO, len(query.Result))
+	for i, dashboardVersion := range query.Result {
+		creator := "Anonymous"
+		if dashboardVersion.CreatedBy > 0 {
+			creator = getUserLogin(dashboardVersion.CreatedBy)
+		}
+
+		dashboardVersions[i] = &m.DashboardVersionDTO{
+			Id:            dashboardVersion.Id,
+			DashboardId:   dashboardVersion.DashboardId,
+			ParentVersion: dashboardVersion.ParentVersion,
+			RestoredFrom:  dashboardVersion.RestoredFrom,
+			Version:       dashboardVersion.Version,
+			Created:       dashboardVersion.Created,
+			CreatedBy:     creator,
+			Message:       dashboardVersion.Message,
+		}
+	}
+
+	c.JSON(200, dashboardVersions)
+}
+
+// GetDashboardVersion returns the dashboard version with the given ID.
+func GetDashboardVersion(c *middleware.Context) {
+	dashboardIdStr := c.Params(":dashboardId")
+	dashboardId, err := strconv.Atoi(dashboardIdStr)
+	if err != nil {
+		c.JsonApiErr(400, err.Error(), err)
+		return
+	}
+
+	versionStr := c.Params(":id")
+	version, err := strconv.Atoi(versionStr)
+	if err != nil {
+		c.JsonApiErr(400, err.Error(), err)
+		return
+	}
+
+	query := m.GetDashboardVersionCommand{
+		DashboardId: int64(dashboardId),
+		Version:     version,
+	}
+	if err := bus.Dispatch(&query); err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+		return
+	}
+
+	creator := "Anonymous"
+	if query.Result.CreatedBy > 0 {
+		creator = getUserLogin(query.Result.CreatedBy)
+	}
+
+	dashVersionMeta := &m.DashboardVersionMeta{
+		DashboardVersion: *query.Result,
+		CreatedBy:        creator,
+	}
+
+	c.JSON(200, dashVersionMeta)
+}
+
+func dashCmd(c *middleware.Context) (m.CompareDashboardVersionsCommand, error) {
+	cmd := m.CompareDashboardVersionsCommand{}
+
+	dashboardIdStr := c.Params(":dashboardId")
+	dashboardId, err := strconv.Atoi(dashboardIdStr)
+	if err != nil {
+		return cmd, err
+	}
+
+	versionStrings := strings.Split(c.Params(":versions"), "...")
+	if len(versionStrings) != 2 {
+		return cmd, fmt.Errorf("bad format: urls should be in the format /versions/0...1")
+	}
+
+	originalDash, err := strconv.Atoi(versionStrings[0])
+	if err != nil {
+		return cmd, fmt.Errorf("bad format: first argument is not of type int")
+	}
+
+	newDash, err := strconv.Atoi(versionStrings[1])
+	if err != nil {
+		return cmd, fmt.Errorf("bad format: second argument is not of type int")
+	}
+
+	cmd.DashboardId = int64(dashboardId)
+	cmd.Original = originalDash
+	cmd.New = newDash
+	return cmd, nil
+}
+
+// CompareDashboardVersions compares dashboards the way the GitHub API does.
+func CompareDashboardVersions(c *middleware.Context) {
+	cmd, err := dashCmd(c)
+	if err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+	}
+	cmd.DiffType = m.DiffDelta
+
+	if err := bus.Dispatch(&cmd); err != nil {
+		c.JsonApiErr(500, "cannot-compute-diff", err)
+		return
+	}
+	// here the output is already JSON, so we need to unmarshal it into a
+	// map before marshaling the entire response
+	deltaMap := make(map[string]interface{})
+	err = json.Unmarshal(cmd.Delta, &deltaMap)
+	if err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+		return
+	}
+
+	c.JSON(200, simplejson.NewFromAny(util.DynMap{
+		"meta": util.DynMap{
+			"original": cmd.Original,
+			"new":      cmd.New,
+		},
+		"delta": deltaMap,
+	}))
+}
+
+// CompareDashboardVersionsJSON compares dashboards the way the GitHub API does,
+// returning a human-readable JSON diff.
+func CompareDashboardVersionsJSON(c *middleware.Context) {
+	cmd, err := dashCmd(c)
+	if err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+	}
+	cmd.DiffType = m.DiffJSON
+
+	if err := bus.Dispatch(&cmd); err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+		return
+	}
+
+	c.Header().Set("Content-Type", "text/html")
+	c.WriteHeader(200)
+	c.Write(cmd.Delta)
+}
+
+// CompareDashboardVersionsBasic compares dashboards the way the GitHub API does,
+// returning a human-readable diff.
+func CompareDashboardVersionsBasic(c *middleware.Context) {
+	cmd, err := dashCmd(c)
+	if err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+	}
+	cmd.DiffType = m.DiffBasic
+
+	if err := bus.Dispatch(&cmd); err != nil {
+		c.JsonApiErr(500, err.Error(), err)
+		return
+	}
+
+	c.Header().Set("Content-Type", "text/html")
+	c.WriteHeader(200)
+	c.Write(cmd.Delta)
+}
+
+// RestoreDashboardVersion restores a dashboard to the given version.
+func RestoreDashboardVersion(c *middleware.Context, cmd m.RestoreDashboardVersionCommand) Response {
+	if !c.IsSignedIn {
+		return Json(401, util.DynMap{
+			"message": "Must be signed in to restore a version",
+			"status":  "unauthorized",
+		})
+	}
+
+	cmd.UserId = c.UserId
+	dashboardIdStr := c.Params(":dashboardId")
+	dashboardId, err := strconv.Atoi(dashboardIdStr)
+	if err != nil {
+		return Json(404, util.DynMap{
+			"message": err.Error(),
+			"status":  "cannot-find-dashboard",
+		})
+	}
+	cmd.DashboardId = int64(dashboardId)
+
+	if err := bus.Dispatch(&cmd); err != nil {
+		return Json(500, util.DynMap{
+			"message": err.Error(),
+			"status":  "cannot-restore-version",
+		})
+	}
+
+	isStarred, err := isDashboardStarredByUser(c, cmd.Result.Id)
+	if err != nil {
+		return Json(500, util.DynMap{
+			"message": "Error while checking if dashboard was starred by user",
+			"status":  err.Error(),
+		})
+	}
+
+	// Finding creator and last updater of the dashboard
+	updater, creator := "Anonymous", "Anonymous"
+	if cmd.Result.UpdatedBy > 0 {
+		updater = getUserLogin(cmd.Result.UpdatedBy)
+	}
+	if cmd.Result.CreatedBy > 0 {
+		creator = getUserLogin(cmd.Result.CreatedBy)
+	}
+
+	dto := dtos.DashboardFullWithMeta{
+		Dashboard: cmd.Result.Data,
+		Meta: dtos.DashboardMeta{
+			IsStarred: isStarred,
+			Slug:      cmd.Result.Slug,
+			Type:      m.DashTypeDB,
+			CanStar:   c.IsSignedIn,
+			CanSave:   c.OrgRole == m.ROLE_ADMIN || c.OrgRole == m.ROLE_EDITOR,
+			CanEdit:   canEditDashboard(c.OrgRole),
+			Created:   cmd.Result.Created,
+			Updated:   cmd.Result.Updated,
+			UpdatedBy: updater,
+			CreatedBy: creator,
+			Version:   cmd.Result.Version,
+		},
+	}
+
+	return Json(200, util.DynMap{
+		"message":   fmt.Sprintf("Dashboard restored to version %d", cmd.Result.Version),
+		"version":   cmd.Result.Version,
+		"dashboard": dto,
+	})
+}
+
 func GetDashboardTags(c *middleware.Context) {
 	query := m.GetDashboardTagsQuery{OrgId: c.OrgId}
 	err := bus.Dispatch(&query)