Layout - Get
Gets the form layout.
GET https://dev.azure.com/{organization}/_apis/work/processes/{processId}/workItemTypes/{witRefName}/layout?api-version=7.1-preview.1URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
organization
|
path | True |
string |
The name of the Azure DevOps organization. |
|
process
|
path | True |
string uuid |
The ID of the process. |
|
wit
|
path | True |
string |
The reference name of the work item type. |
|
api-version
|
query | True |
string |
Version of the API to use. This should be set to '7.1-preview.1' to use this version of the api. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
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.work | Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries, search work items and to receive notifications about work item events via service hooks. |
Examples
Get the form layout
Sample Request
GET https://dev.azure.com/{organization}/_apis/work/processes/{processId}/workItemTypes/{witRefName}/layout?api-version=7.1-preview.1
Sample Response
{
"pages": [
{
"id": "Agile.Bug.Bug",
"inherited": true,
"overridden": true,
"label": "Details",
"pageType": "custom",
"locked": false,
"visible": true,
"isContribution": false,
"sections": [
{
"id": "Section1",
"groups": [
{
"id": "Agile.Bug.Bug.Repro Steps.WideGroup",
"inherited": true,
"label": "Repro Steps",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Microsoft.VSTS.TCM.ReproSteps",
"inherited": true,
"label": "Repro Steps",
"controlType": "HtmlFieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
}
]
},
{
"id": "Agile.Bug.Bug.System Info.WideGroup",
"inherited": true,
"label": "System Info",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Microsoft.VSTS.TCM.SystemInfo",
"inherited": true,
"label": "System Info",
"controlType": "HtmlFieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
}
]
}
]
},
{
"id": "Section2",
"groups": [
{
"id": "Agile.Bug.Bug.Planning",
"inherited": true,
"label": "Planning",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Microsoft.VSTS.Common.ResolvedReason",
"inherited": true,
"label": "Resolved Reason",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Scheduling.StoryPoints",
"inherited": true,
"label": "Story Points",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Common.Priority",
"inherited": true,
"label": "Priority",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Common.Severity",
"inherited": true,
"label": "Severity",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Common.Activity",
"inherited": true,
"label": "Activity",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
}
]
},
{
"id": "Agile.Bug.Bug.Effort (Hours)",
"inherited": true,
"label": "Effort (Hours)",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Microsoft.VSTS.Scheduling.OriginalEstimate",
"inherited": true,
"label": "Original Estimate",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Scheduling.RemainingWork",
"inherited": true,
"label": "Remaining",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Scheduling.CompletedWork",
"inherited": true,
"label": "Completed",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
}
]
},
{
"id": "ms-devlabs.vsts-uservoice-ui.vsts-uservoice-ui-wi-group",
"label": "Customer feedback",
"contribution": {
"contributionId": "ms-devlabs.vsts-uservoice-ui.vsts-uservoice-ui-wi-group"
},
"isContribution": true,
"visible": true,
"controls": []
},
{
"id": "ottostreifel.board-group.board-work-item-form-group",
"label": "Board",
"contribution": {
"contributionId": "ottostreifel.board-group.board-work-item-form-group"
},
"isContribution": true,
"visible": true,
"controls": []
}
]
},
{
"id": "Section3",
"groups": [
{
"id": "Agile.Bug.Bug.Development",
"inherited": true,
"label": "Development",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Development",
"inherited": true,
"label": "",
"controlType": "LinksControl",
"readOnly": false,
"watermark": "",
"metadata": "<LinksControlOptions ViewMode=\"Dynamic\" ZeroDataExperience=\"Development\" ShowCallToAction=\"true\"><ListViewOptions GroupLinks=\"false\"></ListViewOptions><LinkFilters><ExternalLinkFilter Type=\"Build\" /><ExternalLinkFilter Type=\"Integrated in build\" /><ExternalLinkFilter Type=\"Pull Request\" /><ExternalLinkFilter Type=\"Branch\" /><ExternalLinkFilter Type=\"Fixed in Commit\" /><ExternalLinkFilter Type=\"Fixed in Changeset\" /><ExternalLinkFilter Type=\"Source Code File\" /><ExternalLinkFilter Type=\"Found in build\" /></LinkFilters></LinksControlOptions>",
"visible": true,
"isContribution": false
}
]
},
{
"id": "Agile.Bug.Bug.Related Work",
"inherited": true,
"label": "Related Work",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Related Work",
"inherited": true,
"label": "",
"controlType": "LinksControl",
"readOnly": false,
"watermark": "",
"metadata": "<LinksControlOptions><LinkFilters><WorkItemLinkFilter Type=\"System.LinkTypes.Duplicate-Reverse\" /><WorkItemLinkFilter Type=\"System.LinkTypes.Hierarchy-Reverse\" /><WorkItemLinkFilter Type=\"Microsoft.VSTS.Common.TestedBy-Forward\" /><WorkItemLinkFilter Type=\"Microsoft.VSTS.Common.TestedBy-Reverse\" /><WorkItemLinkFilter Type=\"System.LinkTypes.Hierarchy-Forward\" /><WorkItemLinkFilter Type=\"System.LinkTypes.Duplicate-Forward\" /><WorkItemLinkFilter Type=\"System.LinkTypes.Dependency\" /><WorkItemLinkFilter Type=\"System.LinkTypes.Related\" /></LinkFilters><Columns><Column Name=\"System.State\" /><Column Name=\"System.ChangedDate\" /><Column Name=\"System.Links.Comment\" /></Columns></LinksControlOptions>",
"visible": true,
"isContribution": false
}
]
},
{
"id": "Agile.Bug.Bug.System Info",
"inherited": true,
"label": "System Info",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "Microsoft.VSTS.Build.FoundIn",
"inherited": true,
"label": "Found in Build",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
},
{
"id": "Microsoft.VSTS.Build.IntegrationBuild",
"inherited": true,
"label": "Integrated in Build",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"metadata": "",
"visible": true,
"isContribution": false
}
]
}
]
},
{
"id": "Section4",
"groups": []
}
]
},
{
"id": "Agile.Bug.System_History",
"inherited": true,
"label": "History",
"pageType": "history",
"locked": true,
"visible": true,
"isContribution": false,
"sections": [
{
"id": "Section1",
"groups": [
{
"id": "Agile.Bug.System_History.History",
"inherited": true,
"label": "History",
"isContribution": false,
"visible": true,
"controls": [
{
"id": "System.History",
"inherited": true,
"controlType": "WorkItemLogControl",
"visible": true,
"isContribution": false
}
]
}
]
},
{
"id": "Section2",
"groups": []
},
{
"id": "Section3",
"groups": []
},
{
"id": "Section4",
"groups": []
}
]
},
{
"id": "Agile.Bug.System_Links",
"inherited": true,
"label": "Links",
"pageType": "links",
"locked": true,
"visible": true,
"isContribution": false,
"sections": [
{
"id": "Section1",
"groups": [
{
"id": "Agile.Bug.System_Links.Links",
"inherited": true,
"label": "Links",
"isContribution": false,
"visible": true,
"controls": [
{
"inherited": true,
"controlType": "LinksControl",
"metadata": "<LinksControlOptions ZeroDataExperience=\"CallToAction\"><Columns><Column Name=\"System.State\" /><Column Name=\"System.ChangedDate\" /><Column Name=\"System.Links.Comment\" /></Columns></LinksControlOptions>",
"visible": true,
"isContribution": false
}
]
}
]
},
{
"id": "Section2",
"groups": []
},
{
"id": "Section3",
"groups": []
},
{
"id": "Section4",
"groups": []
}
]
},
{
"id": "Agile.Bug.System_Attachments",
"inherited": true,
"label": "Attachments",
"pageType": "attachments",
"locked": true,
"visible": true,
"isContribution": false,
"sections": [
{
"id": "Section1",
"groups": [
{
"id": "Agile.Bug.System_Attachments.Attachments",
"inherited": true,
"label": "Attachments",
"isContribution": false,
"visible": true,
"controls": [
{
"inherited": true,
"label": "Attachments",
"controlType": "AttachmentsControl",
"visible": true,
"isContribution": false
}
]
}
]
},
{
"id": "Section2",
"groups": []
},
{
"id": "Section3",
"groups": []
},
{
"id": "Section4",
"groups": []
}
]
}
],
"systemControls": [
{
"id": "System.Title",
"label": "",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "Enter title",
"visible": true,
"isContribution": false
},
{
"id": "System.AssignedTo",
"label": "Assi&gned To",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "System.State",
"label": "Stat&e",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "System.Reason",
"label": "Reason",
"controlType": "FieldControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "System.AreaPath",
"label": "&Area",
"controlType": "WorkItemClassificationControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "System.IterationPath",
"label": "Ite&ration",
"controlType": "WorkItemClassificationControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "System.History",
"label": "History",
"controlType": "WorkItemLogControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "Links",
"label": "Links",
"controlType": "LinksControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
},
{
"id": "Attachments",
"label": "Attachments",
"controlType": "AttachmentsControl",
"readOnly": false,
"watermark": "",
"visible": true,
"isContribution": false
}
]
}Definitions
| Name | Description |
|---|---|
| Control |
Represent a control in the form. |
| Extension |
Represents the extensions part of the layout |
|
Form |
Describes the layout of a work item type |
| Group |
Represent a group in the form that holds controls in it. |
| Page |
Describes a page in the work item form layout |
|
Page |
The icon for the page. |
| Section |
Defines a section of the work item form layout |
|
Wit |
Properties of a work item form contribution |
Control
Represent a control in the form.
| Name | Type | Description |
|---|---|---|
| contribution |
Contribution for the control. |
|
| controlType |
string |
Type of the control. |
| height |
integer |
Height of the control, for html controls. |
| id |
string |
The id for the layout node. |
| inherited |
boolean |
A value indicating whether this layout node has been inherited. from a parent layout. This is expected to only be only set by the combiner. |
| isContribution |
boolean |
A value indicating if the layout node is contribution or not. |
| label |
string |
Label for the field. |
| metadata |
string |
Inner text of the control. |
| order |
integer |
Order in which the control should appear in its group. |
| overridden |
boolean |
A value indicating whether this layout node has been overridden . by a child layout. |
| readOnly |
boolean |
A value indicating if the control is readonly. |
| visible |
boolean |
A value indicating if the control should be hidden or not. |
| watermark |
string |
Watermark text for the textbox. |
Extension
Represents the extensions part of the layout
| Name | Type | Description |
|---|---|---|
| id |
string |
Id of the extension |
FormLayout
Describes the layout of a work item type
| Name | Type | Description |
|---|---|---|
| extensions |
Gets and sets extensions list. |
|
| pages |
Page[] |
Top level tabs of the layout. |
| systemControls |
Control[] |
Headers controls of the layout. |
Group
Represent a group in the form that holds controls in it.
| Name | Type | Description |
|---|---|---|
| contribution |
Contribution for the group. |
|
| controls |
Control[] |
Controls to be put in the group. |
| height |
integer |
The height for the contribution. |
| id |
string |
The id for the layout node. |
| inherited |
boolean |
A value indicating whether this layout node has been inherited from a parent layout. This is expected to only be only set by the combiner. |
| isContribution |
boolean |
A value indicating if the layout node is contribution are not. |
| label |
string |
Label for the group. |
| order |
integer |
Order in which the group should appear in the section. |
| overridden |
boolean |
A value indicating whether this layout node has been overridden by a child layout. |
| visible |
boolean |
A value indicating if the group should be hidden or not. |
Page
Describes a page in the work item form layout
| Name | Type | Description |
|---|---|---|
| contribution |
Contribution for the page. |
|
| id |
string |
The id for the layout node. |
| inherited |
boolean |
A value indicating whether this layout node has been inherited from a parent layout. This is expected to only be only set by the combiner. |
| isContribution |
boolean |
A value indicating if the layout node is contribution are not. |
| label |
string |
The label for the page. |
| locked |
boolean |
A value indicating whether any user operations are permitted on this page and the contents of this page |
| order |
integer |
Order in which the page should appear in the layout. |
| overridden |
boolean |
A value indicating whether this layout node has been overridden by a child layout. |
| pageType |
The icon for the page. |
|
| sections |
Section[] |
The sections of the page. |
| visible |
boolean |
A value indicating if the page should be hidden or not. |
PageType
The icon for the page.
| Name | Type | Description |
|---|---|---|
| attachments |
string |
Attachment page type. |
| custom |
string |
Custom page type. |
| history |
string |
History page type. |
| links |
string |
Link page type. |
Section
Defines a section of the work item form layout
| Name | Type | Description |
|---|---|---|
| groups |
Group[] |
List of child groups in this section |
| id |
string |
The id for the layout node. |
| overridden |
boolean |
A value indicating whether this layout node has been overridden by a child layout. |
WitContribution
Properties of a work item form contribution
| Name | Type | Description |
|---|---|---|
| contributionId |
string |
The id for the contribution. |
| height |
integer |
The height for the contribution. |
| inputs |
object |
A dictionary holding key value pairs for contribution inputs. |
| showOnDeletedWorkItem |
boolean |
A value indicating if the contribution should be show on deleted workItem. |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for