Widgets - Create

Create a widget on the specified dashboard.

POST https://dev.azure.com/{organization}/{project}/{team}/_apis/dashboard/dashboards/{dashboardId}/widgets?api-version=5.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 '5.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

POST https://dev.azure.com/fabrikam/{project}/_apis/dashboard/dashboards/e17c2ae9-c35c-4ddd-9d4b-6aa47aa4d01a/widgets?api-version=5.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

{
  "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.

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.

description

string

Description of the dashboard.

eTag

string

Server defined version tracking value, used for edit collision detection.

id

string

ID of the Dashboard. Provided by service at creation time.

name

string

Name of the Dashboard.

ownerId

string

ID of the Owner for a dashboard. For any legacy dashboards, this would be the unique identifier for the team 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.

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

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

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.