Widgets - Create

Reference

Service:: Dashboard

API Version:: 7.1-preview.2

Create a widget on the specified dashboard.

POST https://dev.azure.com/{organization}/{project}/{team}/_apis/dashboard/dashboards/{dashboardId}/widgets?api-version=7.1-preview.2

URI Parameters

Name	In	Required	Type	Description
dashboardId	path	True	string uuid	ID of dashboard the widget will be added to.
organization	path	True	string	The name of the Azure DevOps organization.
project	path	True	string	Project ID or project name
team	path		string	Team ID or team name
api-version	query	True	string	Version of the API to use. This should be set to '7.1-preview.2' to use this version of the api.

Request Body

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
allowedSizes	WidgetSize[]	Refers to the allowed sizes for the widget. This gets populated when user wants to configure the widget
areSettingsBlockedForUser	boolean	Read-Only Property from Dashboard Service. Indicates if settings are blocked for the current user.
artifactId	string	Refers to unique identifier of a feature artifact. Used for pinning+unpinning a specific artifact.
configurationContributionId	string
configurationContributionRelativeId	string
contentUri	string
contributionId	string	The id of the underlying contribution defining the supplied Widget Configuration.
dashboard	Dashboard	Optional partial dashboard content, to support exchanging dashboard-level version ETag for widget-level APIs
eTag	string
id	string
isEnabled	boolean
isNameConfigurable	boolean
lightboxOptions	LightboxOptions	Lightbox configuration
loadingImageUrl	string
name	string
position	WidgetPosition
settings	string
settingsVersion	SemanticVersion	versioning for an artifact as described at: http://semver.org/, of the form major.minor.patch.
size	WidgetSize
typeId	string
url	string

Responses

Name	Type	Description
200 OK	Widget	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.dashboards_manage	Grants the ability to manage team dashboard information

Examples

Sample request

HTTP

POST https://dev.azure.com/fabrikam/{project}/_apis/dashboard/dashboards/e17c2ae9-c35c-4ddd-9d4b-6aa47aa4d01a/widgets?api-version=7.1-preview.2

{
  "name": "Other Links",
  "position": {
    "row": 1,
    "column": 1
  },
  "size": {
    "rowSpan": 1,
    "columnSpan": 2
  },
  "settings": null,
  "settingsVersion": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "dashboard": {
    "eTag": "18"
  },
  "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.OtherLinksWidget"
}

Sample response

Status code:: 200

{
  "id": "69f6c5b7-0eb0-4067-b75f-6edff74d0fcf",
  "eTag": "1",
  "name": "Other Links",
  "position": {
    "row": 1,
    "column": 1
  },
  "size": {
    "rowSpan": 1,
    "columnSpan": 2
  },
  "settings": null,
  "settingsVersion": {
    "major": 1,
    "minor": 0,
    "patch": 0
  },
  "dashboard": {
    "eTag": "19"
  },
  "contributionId": "ms.vss-dashboards-web.Microsoft.VisualStudioOnline.Dashboards.OtherLinksWidget",
  "url": "https://dev.azure.com/fabrikam/6c9633e5-5633-4b1d-8081-02b35e39258e/8b69d2eb-2e18-4c75-a1ca-4c1820800e2e/_apis/Dashboard/Dashboards/e17c2ae9-c35c-4ddd-9d4b-6aa47aa4d01a/widgets/69f6c5b7-0eb0-4067-b75f-6edff74d0fcf",
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/6c9633e5-5633-4b1d-8081-02b35e39258e/8b69d2eb-2e18-4c75-a1ca-4c1820800e2e/_apis/Dashboard/Dashboards/e17c2ae9-c35c-4ddd-9d4b-6aa47aa4d01a/widgets/69f6c5b7-0eb0-4067-b75f-6edff74d0fcf"
    },
    "group": {
      "href": "https://dev.azure.com/fabrikam/6c9633e5-5633-4b1d-8081-02b35e39258e/8b69d2eb-2e18-4c75-a1ca-4c1820800e2e/_apis/Dashboard/Dashboards/e17c2ae9-c35c-4ddd-9d4b-6aa47aa4d01a/widgets"
    },
    "dashboard": {
      "href": "https://dev.azure.com/fabrikam/6c9633e5-5633-4b1d-8081-02b35e39258e/8b69d2eb-2e18-4c75-a1ca-4c1820800e2e/_apis/Dashboard/Dashboards/e17c2ae9-c35c-4ddd-9d4b-6aa47aa4d01a"
    }
  }
}

Definitions

Name	Description
Dashboard	Model of a Dashboard.
DashboardScope	Dashboard Scope. Can be either Project or Project_Team
LightboxOptions	Lightbox configuration
ReferenceLinks	The class to represent a collection of REST reference links.
SemanticVersion	versioning for an artifact as described at: http://semver.org/, of the form major.minor.patch.
Widget	Widget data
WidgetPosition
WidgetSize

Dashboard

Model of a Dashboard.

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
dashboardScope	DashboardScope	Entity to which the dashboard is scoped.
description	string	Description of the dashboard.
eTag	string	Server defined version tracking value, used for edit collision detection.
groupId	string	ID of the group for a dashboard. For team-scoped dashboards, this is the unique identifier for the team associated with the dashboard. For project-scoped dashboards this property is empty.
id	string	ID of the Dashboard. Provided by service at creation time.
lastAccessedDate	string	Dashboard Last Accessed Date.
modifiedBy	string	Id of the person who modified Dashboard.
modifiedDate	string	Dashboard's last modified date.
name	string	Name of the Dashboard.
ownerId	string	ID of the owner for a dashboard. For team-scoped dashboards, this is the unique identifier for the team associated with the dashboard. For project-scoped dashboards, this is the unique identifier for the user identity associated with the dashboard.
position	integer	Position of the dashboard, within a dashboard group. If unset at creation time, position is decided by the service.
refreshInterval	integer	Interval for client to automatically refresh the dashboard. Expressed in minutes.
url	string
widgets	Widget[]	The set of Widgets on the dashboard.

DashboardScope

Dashboard Scope. Can be either Project or Project_Team

Name	Type	Description
collection_User	string	[DEPRECATED] Dashboard is scoped to the collection user.
project	string	Dashboard is scoped to the project.
project_Team	string	Dashboard is scoped to the team.

LightboxOptions

Lightbox configuration

Name	Type	Description
height	integer	Height of desired lightbox, in pixels
resizable	boolean	True to allow lightbox resizing, false to disallow lightbox resizing, defaults to false.
width	integer	Width of desired lightbox, in pixels

ReferenceLinks

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

SemanticVersion

versioning for an artifact as described at: http://semver.org/, of the form major.minor.patch.

Name	Type	Description
major	integer	Major version when you make incompatible API changes
minor	integer	Minor version when you add functionality in a backwards-compatible manner
patch	integer	Patch version when you make backwards-compatible bug fixes

Widget data

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
allowedSizes	WidgetSize[]	Refers to the allowed sizes for the widget. This gets populated when user wants to configure the widget
areSettingsBlockedForUser	boolean	Read-Only Property from Dashboard Service. Indicates if settings are blocked for the current user.
artifactId	string	Refers to unique identifier of a feature artifact. Used for pinning+unpinning a specific artifact.
configurationContributionId	string
configurationContributionRelativeId	string
contentUri	string
contributionId	string	The id of the underlying contribution defining the supplied Widget Configuration.
dashboard	Dashboard	Optional partial dashboard content, to support exchanging dashboard-level version ETag for widget-level APIs
eTag	string
id	string
isEnabled	boolean
isNameConfigurable	boolean
lightboxOptions	LightboxOptions	Lightbox configuration
loadingImageUrl	string
name	string
position	WidgetPosition
settings	string
settingsVersion	SemanticVersion	versioning for an artifact as described at: http://semver.org/, of the form major.minor.patch.
size	WidgetSize
typeId	string
url	string

WidgetPosition

Name	Type	Description
column	integer
row	integer

WidgetSize

Name	Type	Description
columnSpan	integer	The Width of the widget, expressed in dashboard grid columns.
rowSpan	integer	The height of the widget, expressed in dashboard grid rows.

Share via