Skip to main content

How to enable in XML process templates (hosted)

The ClearSpecs AI marketplace extension contributes work item form elements 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.

This page mirrors the same steps as Offline - how to enable in XML process templates (export > WebLayout > validate/import > verify). On Azure DevOps Services, Import, export, and manage work item types (witadmin) applies as follows: for Inherited and Hosted 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 (see the offline doc). 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.

ClearSpecs AI contributions:

ContributionKindContribution id (suffix)
ClearSpecs AIForm groupai-assistant-work-item-form-group
AI Child Item GeneratorForm pageai-child-item-form-page

Prerequisites​

  • ClearSpecs AI installed for your organization.
  • Permission to customize the process (for example Project Collection Administrator or process admin for inherited processes), and/or the roles Microsoft lists for import where you run witadmin (witadmin prerequisites).
  • witadmin from a current Visual Studio install when you use command-line export or import (installation paths).

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). 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.clearspecs-ai).
  2. Ensure an Extensions section references that id:
<Extensions>
  <Extension Id="FJANIT.clearspecs-ai" />
</Extensions>

Use the exact Id from your export or manifest.

  1. Place contributions using the fully qualified id pattern PublisherId.ExtensionId.ContributionId:
<GroupContribution Id="FJANIT.clearspecs-ai.ai-assistant-work-item-form-group" />

Optional separate tab for the child-item flow:

<PageContribution Id="FJANIT.clearspecs-ai.ai-child-item-form-page" />

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 contributions 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 ClearSpecs AI as a form group and, if desired, AI Child Item Generator as a page/tab from the extension’s contributions.
  4. Save the process so projects using it pick up the layout.

3. Validate and import​

Azure DevOps Server / on-premises XML - validate and import with witadmin as in Offline - how to enable in XML process templates:

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

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 ClearSpecs AI and optional AI Child Item Generator appear. Refresh the form if metadata is cached.