How-to Adopt Standard Work Item Templates
An existing Azure DevOps (ADO) project - on-premises or in the cloud - may differ from the current standard PCP work item templates due to historical reasons or tailoring. This guide lists the steps and tools to adopt standard work item templates in an existing ADO project with existing data.
Note: ADO templates are complex. Do not hesitate to contact the CM process team or community for expert support and knowledge sharing if needed.
Intended for
Configuration managers.
Activities
Due to differences intechnology, the activities to adopt standard templates are executed in different ways in ADO Server (on-prem) and ADO Services (cloud). Therefore, specific instructions are provided for each activity where applicable.
Spot the differences
Identify differences between the current project and the standard template (with support from the quality control manager (QCM) or CM team if needed).
Tips and tricks: The CM team periodically runs a script based on ADO REST API to analyze current templates and export a csv file containing the list of field differences for each collection, project, and work item type.
Decide how to reconcile differences
Apply the strategies below to manage typical template differences (with support from the QCM or CM team if needed).
| Difference | Strategies |
|---|---|
| Missing fields | This is the most typical case. When a new field is added to the standard template, add it to the project template using the standard template as a reference. The new field will be visible in existing work item data, with empty or default values depending on the field definition. |
| Different work item names | Introduce the new work item type in the project with matching fields. Change the work item type of existing data with REST API or bulk editing from a query. Reconfigure the backlog configuration to show the new work item type name if applicable (e.g. "Product Requirement" -> "Feature"). |
| Additional fields | Desired additional fields can remain unchanged. Unused ones may be hidden, and their value may be copied to "Description" in historical data. |
| Different state names | Update the state machine and backlog visualization configuration. Bulk update existing data. |
| Different drop-down lists | Update the template. Bulk update existing data if any values are removed or renamed. |
| Different rules | Update rules. |
Create a work item in the OpEx project to request the template change.
Tips and tricks: In some cases, the difference analysis may trigger process change requests to improve the standard template.
Prepare the updated template
The CM team prepares the updated template according to the following:
| Where | How to |
|---|---|
| On-prem | Edit the xml template of the corresponding project in the Configuration Management repo on a new branch. Copy/paste and adapt the layout as needed from the on-prem standard work item template stored in the same repo. Import the template to a validation project in the same organization. Create a pull request describing the change and assign it to the respective ADO project configuration manager for review. |
| Cloud | If the ADO organization uses the standard template without modifications, import the latest published standard template from the Configuration Management repo. Assign this template to a validation project for review. If the organization uses a modified template, the CM team cannot import it directly. The project's configuration manager needs to create a copy of the current process in the web UI, apply the change and assign the updated template to a validation project for review. |
- (Optional) If the change requires a bulk update of existing data, prepare a validation project with the same template as the project to update. Add some data, either by importing it from the original project with Naked Agility Migration Tools or by creating sample data.
- Update the template in the validation project. Do not change anything in production until the change is validated.
- (Optional) If the change requires a bulk update of existing data, simulate the bulk update using Naked Agility Migration Tools.
At the end of this activity, the updated project template is available for review in a validation project and/or as code.
Review the change
Review the updated template (with support from the QCM or other roles if needed):
- Check if the template works in the validation project.
- Review and complete pull request (on-prem only).
Update in production
After informing the users and selecting an agreed-upon time, the CM team should update the ADO template in production. If required, bulk update the existing data with Naked Agility Migration Tools. This step requires no downtime.
| Where | How to |
|---|---|
| Cloud | Apply the template to the project from the web UI. |
| On-prem | Apply the template to the project using a Witadmin-based script (also, in the Configuration Management repo) |
Use one or more of the following methods to inform users about changes in a template applied to a project:
- Publish a banner in respective ADO organization with a description of the update.
- Email or other notification to key people.
Details
About work item template updates
On-prem and cloud templates are updated differently. For this, refer to the instructions in the Configuration Management repo, which contains standard templates.
Bulk edit of existing work items
To bulk update work items after a change, write a configuration file for Naked Agility Migration Tools to update data as decided and try it in the validation project until it is validated. Multiple rounds of simulation may be required. It is a good practice to ask some users to check the transformation in the validation project.
Tips and tricks:
- Examples and experience are available within the CM community to support this step.
- Store the configuration file(s) and the templates in a repo to be able to repeat the process as it was validated.
Motivation to align templates
Aligning project templates with the standard ADO template is crucial for maintaining process consistency and enabling the calculation of key performance indicators (KPIs).
Here are some scenarios that require a change in the ADO template or existing data:
- Adopting fields that are used in R&D processes, e.g. "Cloned" and "Security Relevant".
- Changing the list of allowed values for a field, e.g. "How Found".
- Changing the state names, e.g. from "Proposed" to "New".
- Migrating a project from on-prem (e.g. tfsa.abb.com) to cloud (e.g. dev.azure.com/ABB-BCI-PCP).
- Bulk editing field values to match standard field values.
Configuration as code approach
The process for adopting standard work item templates in projects follows a configuration-as-code approach, ensuring consistency, traceability, and efficiency. All templates are managed as code and stored under source control in a Git repository for each project or set of projects sharing the same template. This allows for version control and traceability of changes to specific process change requests.
An automated pipeline with multiple stages is used to deploy the templates. Initially, the templates are deployed to a validation project. After successful testing and review, they are then deployed to the production environment. Manual changes in the production environment are strictly prohibited to maintain consistency and traceability.
The CM team drives the execution of changes, with the support the CM community as needed for executing or reviewing changes. Whenever possible, at least one of the configuration managers of a project is involved in the review and approval for that project. Since changes are reviewed as code, any conflicts in names or layout are resolved before applying the template to production, ensuring smooth and conflict-free deployments.
This centralized approach is more efficient than the previous decentralized method, although it requires effort to manage and maintain. Priorities are managed to optimize the use of available resources, ensuring that changes are addressed promptly. The process includes tracking where changes have been applied and where they have not, which was not possible with the previous approach.
For safety projects
Safety projects are managed according to this process, but can be stored in a separate repository in an appropriate location approved by the Safety team. This approach ensures consistent application of templates across all projects on-premises, provides clear traceability of changes, improves efficiency through centralized management and automated deployment, resolves conflicts before deployment, optimizes resource usage, tracks changes, ensures compliance for safety projects, allows for historical tracking and rollback, eliminates manual errors, and provides a clear audit trail for all changes made.
Tools
The main tool used to manage existing data for this process is Naked Agility Migration Tools. It is a very powerful tool. This guide's most relevant feature is the ability to migrate and bulk update work items while maintaining their history.
Examples:
- Copy work items from the production project to a validation project.
- Bulk edit the value of a field to a default value.
- Map values to bulk replace them.
- Add a tag.
- If a field has a certain value, set the value of another field as configured.
Q&A
Q: Who initiates the process of adopting standard work item templates in a project?
A: The process is usually initiated by the CM team when a standard work item template is updated or by the Quality team when an ADO project deviates from the standard template (for example when a necessary field to follow an R&D process or to calculate a KPI is missing).
Q: My project was created using the Scrum template. Do I have to change it to use the Agile template?
A: No, you can update to the Agile template with the same work item types, states, and backlog visualization.
Q: Is it allowed to have additional custom fields?
A: Additional custom fields are allowed to store more information, provided that the R&D processes or approved tailored processes are followed.
Q: Who is responsible for applying standard templates in ADO Services (cloud)?
A: The CM team applies standard templates to https://dev.azure.com/ABB-BCI-PCP and makes templates available that can be imported to other organizations.
Q: Who is responsible for applying standard templates in ADO Server (on-prem)?
A: The CM team prepares template implementation for each on-prem project and submits a pull review to each project's configuration manager. After successful completion of the pull request, the CM team applies templates to projects. Considering the effort, the CM team may take help from the CM community.