Skip to main content

How to enable in XML process templates (offline / Azure DevOps Server)

The ClearSpecs AI - Local LLM (offline) package uses the same extension contributions as the hosted product. On Azure DevOps Server (on-premises), Microsoft documents adding work item form extensions by editing the work item type WebLayout XML and using the witadmin tool to import the definition.

Follow Microsoft’s step-by-step guide: Configure work item form extensions via XML. That article covers exporting the work item type, locating WebLayout, adding Extensions, and placing page, group, and control contributions, then importing with witadmin importwitd.

This page summarizes how that maps to ClearSpecs AI and points to Import, export, and manage work item types (witadmin) for syntax, permissions, and examples.

Prerequisites​

  • Azure DevOps Server with the ClearSpecs AI extension installed for your collection (private gallery or uploaded package).
  • Permissions to import work item types: membership in Team Foundation Administrators or Project Administrators for the project, as described in Microsoft’s witadmin prerequisites.
  • witadmin from a compatible Visual Studio install on a Windows machine that can reach your application tier (see the same article for installation paths by Visual Studio version).

Confirm your server is using the On-premises XML process model (or a process where WIT import is supported). Inherited-process-only customization on Azure DevOps Services is done in the web UI; Server XML customization is what Microsoft documents in Configure work item form extensions via XML.

1. Export the work item type​

From a Developer Command Prompt (paths per Microsoft’s instructions):

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

Example collection URL format for on-premises: http://ServerName:8080/tfs/DefaultCollection.

2. Declare the extension in WebLayout​

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

  1. Find the Work Item Extensions comment block that lists installed extensions (including ClearSpecs AI). Note the extension Id (for example FJANIT.clearspecs-ai-offline for the Marketplace-style id, matching your installed package).
  2. Under Extensions, add an Extension element so the form loads the extension:
<Extensions>
  <Extension Id="FJANIT.clearspecs-ai-offline" />
</Extensions>

Use the exact Id shown in your exported comment block or extension manifest for your build.

Microsoft notes that after the extension is listed, page and group contributions can be positioned in the layout; control contributions are added explicitly with inputs where applicable. ClearSpecs AI exposes at least:

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

The fully qualified contribution id for layout XML is typically PublisherId.ExtensionId.ContributionId (for example FJANIT.clearspecs-ai-offline.ai-assistant-work-item-form-group). Match the values from your Work Item Extensions comment block after install.

Place a group contribution inside the desired Page / Section / Group area, for example:

<GroupContribution Id="FJANIT.clearspecs-ai-offline.ai-assistant-work-item-form-group" />

Add a page contribution at the appropriate location if you want the AI Child Item Generator on its own tab:

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

Adjust parent elements (Page, Section, Group) to match your process template. Refer to Microsoft’s WebLayout XML elements reference for structure.

3. Validate and import​

Validate without saving (optional):

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

Import the work item type:

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

See importwitd parameters and encoding options in Microsoft’s reference.

4. Open a work item​

Create or open a work item of the updated type and confirm ClearSpecs AI (and optional AI Child Item Generator tab) appear. If the layout is cached, refresh or wait for metadata refresh per your server guidance.

Endpoint configuration​

The Local LLM extension still needs your OpenAI-compatible endpoint reachable from browsers and configured in product settings.