Edit

Share via


Change a project from Hosted XML to an inherited process

Azure DevOps Services

Once you clone your Hosted XML process to an inherited process, you can change the project from the Hosted XML process to the inherited process. You change a project from a Hosted XML process to its derived inherited process to start customizing the process through the user interface.

Caution

Choosing to clone a project from a Hosted XML process model to an inherited process is an irreversible operation. Before you change the process of an existing project from Hosted XML to the cloned inherited process, review Supported operations for moving from Hosted XML to an inherited process, further in this article, to understand which customizations get preserved and which aren't before you change the process of a project from Hosted XML to an inherited process. Also, create a test project to verify the customizations preserved or reapplied to a process.

Prerequisites

Category Requirements
Permissions - To create, delete, or edit a process: Member of the Project Collection Administrators group or specific collection-level permissions Create process, Delete process, Edit process, or Delete a field from organization. For more information, see Set permissions and access for work tracking, Customize an inherited process.
- To update boards: Team Administrator or a member of the Project Administrators group.
Access - Even if you have Basic or lower access, you can still change a process if someone gives you permissions to do so.
- To update and change the type of your existing work items: Project member.

Supported operations for moving from Hosted XML to an inherited process

Upgrading a Hosted XML process model to an inherited process allows you to customize your work tracking system through the user interface. For details on supported customizations, see About process customization and inherited processes.

While the clone process preserves most work tracking customizations, some advanced customizations from the Hosted XML process might not be supported. Additionally, certain customizations must be manually recreated in the inherited process.

Customizations preserved during clone

When you clone a Hosted XML process to an inherited process, the customizations listed in the following table are preserved.

Artifact Description
Work item types (WITs) All system and custom WITs are preserved. Customizations made to WIT color and icon are preserved.
Work item fields All custom fields are preserved. Fields that reference global lists are updated with picklists. All default values are ignored. To learn more about supported field customizations, see About process customization and inherited processes, Field customizations.
Workflow states All system and custom workflow states are preserved.
Workflow state categories All customizations made to the ProcessConfiguration XML file to map a workflow state to a state category (Proposed, In Progress, Resolved, Completed) are preserved. Only one workflow state can be assigned to the Completed state category. If you assigned a custom workflow state to the Completed state category, it is preserved upon clone.

Any workflow state for a work item type that isn't included in a backlog level gets assigned to the In Progress state category. Check all custom workflow states post clone. For more information, see Workflow states and state categories.
Work item form layout A best effort is made to preserve the customizations made to the web form layout. However, any customizations made to the header area are ignored. Specifically, the Weblayout ShowEmptyReadOnlyFields attribute assignment is ignored.
Backlog levels Additions and customizations made to the product backlog and portfolio backlog levels are preserved.
Global lists Global lists are converted to picklists for individual fields.
Default properties The default properties set for teams that you add to a project are preserved as documented in Process configuration XML element reference, Specify properties, and behaviors.

Customizations ignored during clone

Artifact Description
Header area customization Any customizations made to the header area within the work item form are ignored. The header area, as shown in the following image, gets managed by the system. Any customizations made within the SystemControls section of the WebLayout are ignored.

Work item web form, Header area
Four column layout and size The inherited process supports a a fixed relative sizing of three columns to a WIT layout, while the Hosted XML process supports up to four columns and allows you to set the first column as equal sized with the rest of the columns.
Hide Details page in layout The inherited process ignores any customizations made to hide the Details page in a WIT layout.
Workflow restriction The inherited process follows an any-to-any workflow state transition. Any customizations that restrict the transition from one workflow state to another are ignored.
Workflow state reasons Customized reasons added to workflow states are ignored.
Conditional picklists Conditional picklists, also referred to as dependent or cascading picklists, are ignored. Multiple sets of allowed values per field are ignored. Picklists are defined for a field at the collection level and shared across processes and WITs.
Custom rules All custom rules to fields and workflow are ignored.
Custom link controls Custom link controls are ignored.
Extensions The inherited process supports an opt-out model for custom control extensions, while the Hosted XML process supports an opt-in model. This means that work item types defined within the cloned inherited process show all contributions from all installed and enabled extensions. You can selectively hide or remove them as needed.
Categories Changes made to a default category are preserved, but any custom categories are ignored. Also note that system work item types such as Issue or Impediment aren't supported on a backlog level.
Identity fields with string values Lists that contain an identity value in ALLOWEDVALUES or PROHIBITEDVALUES are automatically converted into the Identity field type. Any other string values in the list are ignored.
Test Steps Test steps aren't supported in any work item type other than Test Case.

Change the project process to an inherited process

After you verify your customizations, you can apply the inherited process to your existing project. Do the following steps:

  1. Sign in to your organization (https://dev.azure.com/{Your_Organization}).

  2. Select gear icon Organization settings.

    Screenshot showing highlighted Organization settings button.

  3. Select Process and choose the original Hosted XML process.

  4. Select the Projects page.

    Screenshot shows Open inherited process, Projects page.

  5. Open the … context menu for the project and choose the Change process… option.

    Here we open the menu for the Fabrikam Test project.

    Fabrikam Test project context menu, Choose Change process

  6. Choose the inherited process that you created. The system lists only those processes that are valid for the selected project.

    Change process to an inherited process dialog

  7. Select Ok.

Post-upgrade customizations to make manually

The upgrade makes a best-effort attempt to reconcile the system process and the customizations made to the Hosted XML process. After you upgrade, we recommend you review the inherited process and reapply customizations manually.