ADO Work Item CLI Tool

Overview

The ADO Work Item CLI Tool is a comprehensive command-line interface designed for managing and analyzing Azure DevOps work items. It enables fetching work items, generating reports, and analyzing work item histories directly from the command line, offering a powerful tool for developers, project managers, and teams utilizing Azure DevOps.

Features

• Fetching Work Items: Retrieve work items based on various criteria, including iteration paths and specific queries.
• Work Item Reporting: Generate detailed reports in table or CSV formats for work items, including their types, states, and iteration path changes.
• Analyzing Work Item History: Access the revision history of work items to track changes over time.
• Work Item Filtering: Filter work items by type, state, or custom criteria to focus on specific items of interest.
• Concurrent Processing: Utilize concurrent operations for efficient data fetching and processing.
• Custom Reporting: Customize reports with specific fields and align columns as required.

Setup

1. Configuration: Before using the CLI, ensure you have a valid Azure DevOps organization URL and a Personal Access Token (PAT) with appropriate access permissions.
2. Installation: The tool is built using Python and requires the Azure DevOps Python SDK. Ensure Python and necessary dependencies are installed.
3. Logging: Configure logging as per your requirements to track tool operations and outputs.

Usage

The CLI supports various commands and options for managing work items:

Fetch Work Items

fetch --max-items [NUMBER]

Fetches work items up to the specified limit. If not specified, all available items are fetched.

Count Work Items

count --state [STATE(S)] --all-states

Counts work items based on their state. Use --all-states to count work items for all states or specify individual states.

Get Work Item Types

get_work_item_types --work-item-type [TYPE(S)] --all-types

Reports the number of work items for specified types. Use --all-types to report on all types or specify individual types.

Fetch History

fetch_history --work-item-id [ID]

Fetches the history of a specified work item, reporting on its revisions.

Report Work Item Changes

report_work_item_changes --max-items [NUMBER] --work-item-type [TYPE(S)] --work-item-state [STATE(S)]

Generates a report on work items of specified types and states, including their iteration path changes.

Configuration

The tool relies on a configuration file (config.py) and an environment variable (ADO_PAT) for the Personal Access Token. Ensure these are correctly set up for authentication with Azure DevOps.

Extensibility

The CLI's modular design allows for easy extension and customization. Developers can add new commands, reports, or processing logic as required for their specific use cases.

PAT8 Compliance

This project is PAT8 compliant, ensuring it adheres to best practices for code structure, security, and performance. Please ensure your usage of the tool complies with Azure DevOps policies and permissions.

User uploaded file with ID 'file-gnSFg7Z0HYPQ1VeqCwryjIeF' to: /mnt/data/Class_and_Function_Details.md.

I've prepared an overview of the classes and functions based on the detailed document provided. Here's a concise summary that can be incorporated into your project's README for a comprehensive understanding of its components:

---

ADO Work Item CLI Tool - Classes and Functions Overview

The ADO Work Item CLI Tool is designed to facilitate the management and reporting of Azure DevOps work items. Below is an overview of its core components:

Classes

WorkItemManager

Responsible for interacting with Azure DevOps services to fetch work items and their details. It encapsulates the logic for querying Azure DevOps APIs and processing the responses.

Key Functions:

• fetch_all_and_related_work_items(wiql_query, max_items): Fetches work items based on a WIQL query, including related items up to a specified maximum.
• fetch_work_item_history(work_item_id): Retrieves the revision history for a specific work item.

ADOWorkItem

A wrapper class that provides a structured representation of Azure DevOps work items, facilitating easier access to their properties and fields.

Key Functions:

• get_field(field_name): Retrieves the value of a specified field from the work item.

TableReportGenerator and CSVReportGenerator

These classes generate detailed reports in table and CSV formats, respectively, from the fetched work item data.

Key Functions:

• generate_report(data): Generates a report based on the provided work item data.
• save_report(report, file_path): Saves the generated report to a specified file path.

Utility Functions

fetch_and_process_work_items(config, personal_access_token, max_items)

Fetches and processes work items from Azure DevOps, returning a list of ADOWorkItem instances.

count_work_items_by_state(work_items, states)

Counts work items by specified states, returning a dictionary mapping states to counts.

filter_work_items(work_items, item_types=None, states=None)

Filters work items by specified types and/or states, returning a list of filtered ADOWorkItem instances.

extract_fields_from_work_item(work_item)

Extracts field names from a work item, useful for dynamic report generation.

count_iteration_path_changes(manager, work_item_id)

Counts the number of iteration path changes for a given work item.

Configuration and Logging

• The tool is configured via a config.py file, which should specify the Azure DevOps organization URL, project name, and iteration path.
• Logging is facilitated by log_config.py, allowing for detailed logging of the tool's operations.

---

This summary provides a clear picture of the tool's architecture and functionalities. For more detailed information, refer to the provided document and inline code comments within the project.

Conclusion

The ADO Work Item CLI Tool offers a powerful and flexible solution for managing Azure DevOps work items from the command line. By leveraging this tool, teams can improve their workflow efficiency, gain deeper insights into their work item lifecycle, and customize their reporting and analysis to fit their project management needs.