Share via

Card fields on a Kanban board

  • Article

TFS 2017 | TFS 2015 | TFS 2013

Note

Looking for REST APIS that support TFS 2018 or later versions? See the Azure DevOps REST API Reference.

api-version = 2.0-preview.1

Use card fields to display work item fields on cards on Kanban boards.

If you haven't already, look at the information on getting started with these APIs.

Get card fields for a board

GET https://{instance}/DefaultCollection/{project}/{team}/_apis/work/boards/{board}/cardSettings?api-version={api-version}
Parameter Type Default Value Notes
URL
instance string TFS server name ({server:port}).
project string Name or ID of a project.
team string Project's default team ID Name or ID of a team within the project.
board string Name or ID of the specific board.
Query
api-version string Version of the API to use.

By ID

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam/_apis/work/boards/41688c28-a3fc-4811-977d-247a33f18a00/cardsettings?api-version=2.0-preview.1

Sample response

{
  "cards": {
    "Bug": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.State"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Severity"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarAndFullName",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "false"
      }
    ],
    "Product Backlog Item": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.TeamProject"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.BusinessValue"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarOnly",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "true"
      }
    ]
  }
}

By name

Sample request

GET https://mytfsserver/DefaultCollection/Fabrikam/_apis/work/boards/Backlog%20items/cardsettings?api-version=2.0-preview.1

Sample response

{
  "cards": {
    "Bug": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.State"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Severity"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarAndFullName",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "false"
      }
    ],
    "Product Backlog Item": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.TeamProject"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.BusinessValue"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarOnly",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "true"
      }
    ]
  }
}

Update card fields on a board

 Allow users to add, update or delete card fields. 
PUT https://{instance}/DefaultCollection/{project}/{team}/_apis/work/boards/{board}/cardSettings?api-version={api-version}
Parameter Type Default Value Notes
URL
instance string TFS server name ({server:port}).
project string Name or ID of a project.
team string Project's default team ID Name or ID of a team within the project.
board string Name or ID of the specific board.
Query
api-version string Version of the API to use.
Body
cards name/value pair Name is a valid workitem type singular name such as "Bug", "Product Backlog Item", etc. The associated value pair is a list of field identifiers such as "System.AssignedTo", "System.Title", etc.
card.fieldIdentifier string Field reference name such as "System.Id", "System.Title", etc. For settings where fieldIdentifier is not defined, the key value pair will apply as a global setting e.g. if showEmptyFields is set to false, it will not display fields when they are empty.
card.displayFormat string Optional display format associated with the field. For "System.AssignedTo" fieldIdentifier can take one of the following 3 options, "AvatarOnly", "FullName" and "AvatarAndFullName".
card.displayType string Optional string that identifies whether a field is a core field or an additional field. e.g. card.displayType can take one of the following values, "CORE", "ADDITIONAL", or "COREANDADDITIONAL". "CORE" refers to a field being only Core e.g. "System.Id", "ADDITIONAL" refers to a field being only additional e.g. "System.ChangedBy", and "COREANDADDITIONAL" refers to fields that can be both core and additional e.g. "System.AssignedTo".

Assumption:

  1. Field identifier order is determined by the order of elements in post data.
  2. Any existing field identifier that is not on the post data will not be displayed.
  3. For each work item type, all the existing field identifiers must be mentioned even if a single identifier needs to be updated. If any of the field identifiers are not valid, the card fields will not be updated.
  4. Up to 10 additional fieldIdentifiers can be configured in card fields.

When update fails, it will return bad request. Following exceptions can be thrown depending on the errors:

  1. CardSettingsValidationFailureException
  2. CardSettingsUpdateFailureException
  3. NoPermissionUpdateCardSettingsException

Status code: 400

{
$id: "1"
innerException: null
message: "TF1530014: The card settings are invalid. Error message: Field identifier 'System.AssignedTo' is required but missing from 'Product Backlog Item' card type. "
typeName: "Microsoft.TeamFoundation.Agile.Common.Exceptions.CardSettingsValidationFailureException, Microsoft.TeamFoundation.Agile.Common, Version=14.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
typeKey: "CardSettingsValidationFailureException"
errorCode: 0
eventId: 3000
}

Sample request

PUT https://mytfsserver/DefaultCollection/Fabrikam/_apis/work/boards/Backlog%20items/cardsettings?api-version=2.0-preview.1

{
  "cards": {
    "Bug": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.State"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Severity"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarAndFullName",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "false"
      }
    ],
    "Product Backlog Item": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.TeamProject"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.BusinessValue"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarOnly",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "true"
      }
    ]
  }
}

Sample response

{
  "cards": {
    "Bug": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.State"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Severity"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarAndFullName",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "false"
      }
    ],
    "Product Backlog Item": [
      {
        "fieldIdentifier": "System.Title"
      },
      {
        "fieldIdentifier": "System.ChangedBy"
      },
      {
        "fieldIdentifier": "System.TeamProject"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.Priority"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Common.BusinessValue"
      },
      {
        "fieldIdentifier": "System.AssignedTo",
        "displayFormat": "AvatarOnly",
        "displayType": "CORE"
      },
      {
        "fieldIdentifier": "Microsoft.VSTS.Scheduling.Effort",
        "displayType": "CORE"
      },
      {
        "showEmptyFields": "true"
      }
    ]
  }
}