Skip to main content

How to enable in XML process templates

The Checklist Extension for Azure DevOps contributes a work item form group that you place using either XML in your process template (where Microsoft allows witadmin import) or the inheritance process layout in the web portal. Microsoft’s guide Configure work item form extensions via XML describes exporting WIT definitions, editing WebLayout, and importing with witadmin importwitd; it also notes that on Azure DevOps Services you customize work item forms through the inheritance process model instead of XML import when that is your process type.

The overall flow is export > WebLayout > validate/import (where allowed) > verify. On Azure DevOps Services, Import, export, and manage work item types (witadmin) applies as follows: for Inherited and XML process models on the service, you may use witadmin only to list and export work item types - not to import customized XML. The On-premises XML importwitd workflow applies to Azure DevOps Server and similar deployments where import is supported. For typical inherited organizations on the cloud, use section 2 as the XML reference for what to add, and apply it with the layout designer (below) instead of section 3 import.

Checklist templates are configured in Project settings (hub contribution), not via WebLayout. This page covers only the Checklists form group on the work item.

Checklist Extension contributions (work item form):

ContributionKindContribution id (suffix)
ChecklistsForm groupchecklist-work-item-form-group

Prerequisites​

1. Export the work item type​

From a Developer Command Prompt:

witadmin exportwitd /collection:CollectionURL /p:Project /n:TypeName /f:FileName.xml

For Azure DevOps Services, use your project collection URL (for example https://dev.azure.com/YourOrganizationName or https://YourOrganizationName.visualstudio.com). For Azure DevOps Server, use your collection URL (for example https://tfs.contoso.com/tfs/DefaultCollection). See exportwitd for parameters and encoding.

Use this export to inspect WebLayout and the Work Item Extensions comment block; on inherited processes you generally do not re-import the file on the service.

2. Declare the extension in WebLayout​

In the exported XML, open WebLayout. Per Configure work item form extensions via XML:

  1. Find the Work Item Extensions comment that lists installed extensions. Note the extension Id (for example FJANIT.azdo-checklist-extension). You can also confirm the id under Organization settings > Extensions.
  2. Ensure an Extensions section references that id:
<Extensions>
  <Extension Id="FJANIT.azdo-checklist-extension" />
</Extensions>

Use the exact Id from your export or extension manifest.

  1. Place the form group using the fully qualified id pattern PublisherId.ExtensionId.ContributionId:
<GroupContribution Id="FJANIT.azdo-checklist-extension.checklist-work-item-form-group" />

Adjust parent Page / Section / Group elements to match your template. See WebLayout XML elements.

Azure DevOps Services (inherited process) - layout designer​

Where witadmin import is not used for your process type, add the same contribution in the portal:

  1. Organization settings > Boards > Process > your inherited process (inheritance process model).
  2. Work item types > choose a type > Layout (or Form).
  3. Add Checklists (form group from the extension).
  4. Save the process so projects using it pick up the layout.

3. Validate and import​

Azure DevOps Server / on-premises XML - after editing WebLayout, validate then import:

witadmin importwitd /collection:CollectionURL /f:FileName.xml /p:Project /v
witadmin importwitd /collection:CollectionURL /f:FileName.xml /p:Project

Resolve validation errors before running the second command (import without /v).

Azure DevOps Services (Inherited or Hosted XML) - Microsoft’s witadmin documentation restricts import for those models; use section 2 layout designer instead of importwitd.

See importwitd for options (for example /v).

4. Open a work item​

Open a work item of the updated type and confirm the Checklists group appears. Refresh the form if metadata is cached.