📈Dashboards

Jira dashboards are customizable, visual displays that provide an overview of project status and performance metrics in real-time. Dashboards are used to track progress and identify trends, enabling teams to make informed decisions and prioritize tasks.

.gif created using the video https://www.youtube.com/watch?v=VswPTqLQzqA

Here are some key elements of Jira dashboards:

1. Gadgets: Gadgets are the building blocks of Jira dashboards. They are small, customizable widgets that display information in various formats, such as charts, lists, or calendars. Examples of gadgets include the Agile Sprint Burndown gadget, which shows the remaining work in a sprint, or the Pie Chart gadget, which displays the distribution of issues across a project.

2. Filters: Filters are used to specify which data should be displayed in a gadget. For example, you can create a filter that displays all open bugs assigned to a specific developer. Filters can be saved and reused across multiple gadgets.

3. Layout: Dashboards can be customized with different layouts to display multiple gadgets on a single page. Users can create multiple dashboards for different purposes, such as a team dashboard or a project-specific dashboard.

4. Permissions: Jira dashboards can be shared with team members or made public, depending on the level of access required. Permissions can be set at the individual gadget level or for the entire dashboard.

Get all dashboards

GET /rest/api/{2-3}/dashboard

Returns a list of dashboards owned by or shared with the user. The list may be filtered to include only favorite or owned dashboards.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jiraCloud, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jiraCloud.Auth.SetBasicAuth(mail, token)
	jiraCloud.Auth.SetUserAgent("curl/7.54.0")

	dashboards, response, err := jiraCloud.Dashboard.Gets(context.Background(), 0, 50, "")

	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for _, dashboard := range dashboards.Dashboards {
		log.Println(dashboard.ID, dashboard.Name)
	}
}

Create dashboard

POST /rest/api/{2-3}/dashboard

This is an experimental endpoint

This method allows you to create a new dashboard in your Jira instance. The request body should contain a JSON object with the following properties:

• name: The name of the dashboard.

• sharePermissions: An array of objects representing the users and groups who have permission to view the dashboard.

• gadget: An array of objects representing the gadgets that should be displayed on the dashboard.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jiraCloud, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jiraCloud.Auth.SetBasicAuth(mail, token)
	jiraCloud.Auth.SetUserAgent("curl/7.54.0")

	var payload = &models.DashboardPayloadScheme{
		Name:        "Team Tracking 4",
		Description: "description sample",
		SharePermissions: []*models.SharePermissionScheme{
			{
				Type: "project",
				Project: &models.ProjectScheme{
					ID: "10000",
				},
				Role:  nil,
				Group: nil,
			},
			{
				Type:  "group",
				Group: &models.GroupScheme{Name: "jira-administrators"},
			},
		},
	}

	dashboard, response, err := jiraCloud.Dashboard.Create(context.Background(), payload)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)

	log.Printf("Dashboard Name: %v", dashboard.Name)
	log.Printf("Dashboard ID: %v", dashboard.ID)
	log.Printf("Dashboard View: %v", dashboard.View)
}

Search for dashboards

GET /rest/api/{2-3}/dashboard/search

Returns a paginated list of dashboards. This operation is similar to Get dashboards except that the results can be refined to include dashboards that have specific attributes.

For example, dashboards with a particular name. When multiple attributes are specified only filters matching all attributes are returned.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jira, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jira.Auth.SetBasicAuth(mail, token)
	jira.Auth.SetUserAgent("curl/7.54.0")

	searchOptions := models.DashboardSearchOptionsScheme{
		DashboardName:       "Bug",
		GroupPermissionName: "administrators",
		OrderBy:             "description",
		Expand:              []string{"description", "favourite", "sharePermissions"},
	}

	dashboards, response, err := jira.Dashboard.Search(context.Background(), &searchOptions, 0, 50)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	for _, dashboard := range dashboards.Values {
		log.Printf("Dashboard Name: %v", dashboard.Name)
		log.Printf("Dashboard ID: %v", dashboard.ID)
		log.Printf("Dashboard View: %v", dashboard.View)

		if dashboard.SharePermissions != nil {
			for _, permission := range dashboard.SharePermissions {
				log.Println(permission)
			}
		}
	}
}

Get dashboard

GET /rest/api/{2-3}/dashboard/{id}

Returns a dashboard using the dashboard-id

However, to get a dashboard, the dashboard must be shared with the user or the user must own it. Note, users with Administer Jira global permission are considered owners of the System dashboard. The System dashboard is considered to be shared with all other users.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jira, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jira.Auth.SetBasicAuth(mail, token)
	jira.Auth.SetUserAgent("curl/7.54.0")

	dashboard, response, err := jira.Dashboard.Get(context.Background(), "10001")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	log.Printf("Dashboard Name: %v", dashboard.Name)
	log.Printf("Dashboard ID: %v", dashboard.ID)
	log.Printf("Dashboard View: %v", dashboard.View)
}

Update dashboard

PUT /rest/api/{2-3}/dashboard/{id}

This is an experimental endpoint

Updates a dashboard, replacing all the dashboard details with those provided. The dashboard to be updated must be owned by the user.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jira, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jira.Auth.SetBasicAuth(mail, token)
	jira.Auth.SetUserAgent("curl/7.54.0")

	var payload = &models.DashboardPayloadScheme{
		Name:        "Team Tracking #1111",
		Description: "",
		SharePermissions: []*models.SharePermissionScheme{
			{
				Type: "project",
				Project: &models.ProjectScheme{
					ID: "10000",
				},
				Role:  nil,
				Group: nil,
			},
			{
				Type:  "group",
				Group: &models.GroupScheme{Name: "jira-administrators"},
			},
		},
	}

	dashboard, response, err := jira.Dashboard.Update(context.Background(), "10001", payload)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("HTTP Endpoint Used", response.Endpoint)

	log.Printf("Dashboard Name: %v", dashboard.Name)
	log.Printf("Dashboard ID: %v", dashboard.ID)
	log.Printf("Dashboard View: %v", dashboard.View)
}

Delete dashboard

DELETE /rest/api/{2-3}/dashboard/{id}

This is an experimental endpoint

Deletes a dashboard, the dashboard to be deleted must be owned by the user.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jiraCloud, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jiraCloud.Auth.SetBasicAuth(mail, token)
	jiraCloud.Auth.SetUserAgent("curl/7.54.0")

	response, err := jiraCloud.Dashboard.Delete(context.Background(), "10003")
	if err != nil {
		log.Fatal(err)
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)
}

Copy dashboard

POST /rest/api/{2-3}/dashboard/{id}/copy

This is an experimental endpoint

Copies a dashboard. Any values provided in the dashboard parameter replace those in the copied dashboard.

package main

import (
	"context"
	_ "github.com/ctreminiom/go-atlassian/v2/jira/v2"
	"github.com/ctreminiom/go-atlassian/v2/jira/v3"
	"github.com/ctreminiom/go-atlassian/pkg/infra/models"
	"log"
	"os"
)

func main() {

	var (
		host  = os.Getenv("HOST")
		mail  = os.Getenv("MAIL")
		token = os.Getenv("TOKEN")
	)

	jira, err := v3.New(nil, host)
	if err != nil {
		return
	}

	jira.Auth.SetBasicAuth(mail, token)
	jira.Auth.SetUserAgent("curl/7.54.0")

	var payload = &models.DashboardPayloadScheme{
		Name:        "Team Tracking #2 copy",
		Description: "Description sample",
		SharePermissions: []*models.SharePermissionScheme{
			{
				Type: "project",
				Project: &models.ProjectScheme{
					ID: "10000",
				},
				Role:  nil,
				Group: nil,
			},
			{
				Type:  "group",
				Group: &models.GroupScheme{Name: "jira-administrators"},
			},
		},
	}

	dashboard, response, err := jira.Dashboard.Copy(context.Background(), "10001", payload)
	if err != nil {
		if response != nil {
			log.Println("Response HTTP Response", response.Bytes.String())
		}
		log.Fatal(err)
	}

	log.Println("Response HTTP Code", response.Code)
	log.Println("HTTP Endpoint Used", response.Endpoint)

	log.Printf("Dashboard Name: %v", dashboard.Name)
	log.Printf("Dashboard ID: %v", dashboard.ID)
	log.Printf("Dashboard View: %v", dashboard.View)
}