Edit

Share via

Import and export a Hosted XML process

  • Article

Azure DevOps Services

Important

The import process supports the Hosted XML process model, which allows you to manage customizations by updating the WIT (Work Item Type) definition of a process template. This feature is only available for organizations migrated to Azure DevOps Services using the Database Import Service.

If you use the Inheritance process model, you can customize your work tracking directly through the user interface by creating an inherited process. For organizations using the on-premises XML process model, you can customize a process template. For more information, see the following articles:

In Azure DevOps Services, you can customize work tracking objects using processes. Hosted XML processes allow you to import and export processes through a web-based administration interface, enabling flexibility and control over your organization's workflows.

When you import a new process, you can create new projects based on it. Importing an existing process updates all projects that use that process to reflect the changes automatically. For example, any updates made to the custom process automatically apply to the projects that use the process.

If you need to make other customizations, you can export the existing process, modify the process XML definition files, zip the updated files, and reimport the process. These changes are applied to all existing projects that use the updated process, ensuring consistency across your organization.

The import process supports the following scenarios:

Prerequisites

For guidance on tailoring Azure Boards to align with your specific business requirements, see About configuring and customizing Azure Boards.

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 set to Allow. 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: Member of the project.
Project process model - Have the Inheritance process model for the project collection containing the project.
- If migrating data to Azure DevOps Services, use the Team Foundation Server Database Import Service.
Knowledge Familiarity with the customization and process models.

Import a process from an on-premises Azure DevOps

In an on-premises Azure DevOps Server, each project maintains its own copy of a process. Therefore, it's important to carefully evaluate which processes should exist for your organization. Migration to Azure DevOps Services provides an excellent opportunity to align processes across your organization and reduce the number of process variants. Streamlining your processes ensures consistency and simplifies management in the cloud environment.

To test your process in an on-premises Azure DevOps Server to ensure it works in Azure DevOps Services, follow these steps:

  1. Run the process export script to generate a process for a specific project.
  2. (Optional) Edit the ProcessTemplate.xml file to update the name and description. Ensure it adheres to the rules and constraints outlined in Customize a process.
  3. Compress the process folder and files into a zip file.
  4. Import the zip file of your custom process by following the steps in the next section.
  5. Repeat these steps for each process you want to import into Azure DevOps Services.
  6. Once the process is imported, use it to create projects in Azure DevOps Services for each project you want to migrate.

Open Settings > Process

Create, manage, and make customizations to processes from the Process page.

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

  2. Select Organization settings.

    Screenshot shows highlighted Organization settings button.

  3. Select Process.

    Screenshot shows Organization settings, Process page.

    Important

    If you don't see Process, then you're working from an earlier version where the Process page isn't supported. Use the features supported for the On-premises XML process model.

Import a process

Before you import a process, ensure you customize it to meet your work tracking needs. Name your process something other than Scrum, Agile, or CMMI, as these system processes are locked and you can't overwrite them.

  1. From the Processes tab, select Import process, and either drag-and-drop or browse to the zip file of the customized process.

    Note

    If the Import process link isn't visible, your organization isn't configured to support the Hosted XML process model. In this case, use the Inheritance process model for your customization needs. The Hosted XML process model is only available for accounts created through the Data Import Service.

    Screenshot shows Import Process link.

    Ensure that your custom process meets specific constraints to pass validation checks during the import.

    Screenshot shows Import Process dialog, choose process file to import.

    If you're updating an existing template, check the Replace existing template box. This action overwrites any template with the same name as the one you're importing and requires confirmation.

    Important

    You can't update locked processes, such as Agile, CMMI, and Scrum.

    Upon successful import, the following confirmation message displays.

    Screenshot shows Import Process success dialog.

    If the process fails validation, you receive a list of error messages. Resolve each error and retry the import.

  2. Once the process successfully imports, you can immediately create a project using the new process.

    Screenshot shows Import process actions menu, Create new team project from imported process.

  3. Complete the form that appears to create the project. For more information about the available options, see Create a project.

    Screenshot shows Create new project dialog.

Update an existing process

Once you add a process, you can update it by importing a zip file where you modified one or more files within the process template.

Note

It's a best practice to Export a process before making changes so that you don't accidentally overwrite changes made by other users.

  1. Import the process according to steps 2 and 3 from the previous procedure.

  2. Check the Replace existing template to indicate you want to overwrite the existing process.

    Screenshot shows Import Process dialog, replace existing process.

    The Import Process dialog indicates that the system is updating projects that reference the Hosted XML process.

  3. Upon successful import, the following message displays. All projects created with the process get updated with the modifications.

    Screenshot shows Process page, Import Process success dialog, successfully imported and updated projects.

  4. If you renamed or deleted fields or work item types, you receive a confirmation message. Check the box and proceed with the import. For more information about each message, select the forward link provided. Information messages don't require any action on your part.

    Screenshot shows Deleted field confirmation dialog.

Set the default process

Set a process as the default to preselect it for all new projects you plan to create.

Process page, hosted XML process, set as default process menu option

Export a process

Exporting a process allows you to update an existing process or use it as a template for creating a new one. This action is useful when you need to make customizations or standardize processes across multiple projects in your organization.

When you export a process, the system generates a zip file containing an XML representation of the process. This file includes all the process definitions, such as work item types, fields, and workflows. You can modify these XML files to meet your specific requirements and then reimport the updated process to apply the changes.

For example, you might export a process to:

  • Add custom fields or work item types.
  • Adjust workflows to better align with your team's practices.
  • Create a new process based on an existing one to support a different project or team.

After making the necessary modifications, you can reimport the process to update existing projects or create new ones using the customized process. This action ensures consistency and flexibility in managing work tracking across your Azure DevOps organization.