Multi-Value Control for CN and Part Numbers (Caterpillar)

Enhanced Multi-Value Control Extension for Azure DevOps

This extension is an enhanced version of the Microsoft DevLabs Multi-Value Control, customized for Caterpillar Inc. It provides independent CN (Change Notice) and Part Number dropdowns with dynamic API integration, client-side search, and performance optimizations.

Credits

Original Extension: Based on Microsoft DevLabs Multi-Value Control (enhanced for Caterpillar Inc)

Enhanced By: Caterpillar Inc - LTF-WPE-CAT-COM Organization

Key Features

✨ Enhanced Features (Beyond Original)

1. Independent Dropdowns

   • Separate CN Number and Part Number dropdowns that operate independently
   • Each dropdown maintains its own state and lifecycle
   • Supports multiple instances on the same work item form

2. Client-Side Search

   • Real-time filtering of dropdown options as you type
   • Debounced search for smooth performance
   • Case-insensitive search across CN and Part Numbers

3. Dynamic API Integration

   • Lazy-loads options from API on focus
   • Integrates with existing Node.js API endpoints (/api/data/CNNum, /api/data/PartNum)
   • Validates Custom.DesignControlIds field before API calls

4. Performance Caching

   • Options cached after first load to prevent redundant API calls
   • Efficient state management for improved responsiveness

5. Enhanced Error Handling

   • Clear error messages with retry functionality
   • Graceful degradation when API is unavailable
   • Timeout handling (10-second timeout)

6. Security Enhancements

   • URL injection protection
   • Input validation and sanitization
   • Generic error messages to prevent information disclosure

How It Works

Prerequisites

1. Required Field: Custom.DesignControlIds (comma-separated list of Design Control IDs)
2. Output Fields:
   • Custom.CNNum (for CN Number dropdown)
   • Custom.PartNum (for Part Number dropdown)

Setup Instructions

1. Create Work Item Fields

   • Create Custom.DesignControlIds field (String type)
   • Create Custom.CNNum field (String or HTML type for multiple values)
   • Create Custom.PartNum field (String or HTML type for multiple values)

2. Add Control to Work Item Form

   • Navigate to Project Settings → Process → Work Item Type
   • Add the Multi-Value Control to your form
   • Configure FieldName as Custom.CNNum for CN dropdown
   • Add another instance with FieldName as Custom.PartNum for Part dropdown

3. Populate Design Control IDs

   • Enter comma-separated Design Control IDs in Custom.DesignControlIds field
   • Example: DC001,DC002,DC003

4. Use the Control

   • Click on CN Number dropdown → Options load from API automatically
   • Click on Part Number dropdown → Options load from API automatically
   • Use search box to filter options
   • Select multiple values from each dropdown independently

Field Configuration

Input Field: Custom.DesignControlIds

• Type: String
• Format: Comma-separated values (e.g., DC001,DC002,DC003)
• Required: Yes (for API calls to work)
• Purpose: Provides Design Control IDs to query API endpoints

Output Fields: Custom.CNNum and Custom.PartNum

• Type: String or HTML (for large lists)
• Format: Comma-separated selected values
• Purpose: Stores user selections from respective dropdowns

API Integration

The extension integrates with your existing API:

• CN Numbers Endpoint: /api/data/CNNum?designControlId={ids}
• Part Numbers Endpoint: /api/data/PartNum?designControlId={ids}
• Base URL: Configured in code (currently: https://projex-qa2.cat.com)

API Response Format

CN Numbers:

[
  { "CHANGE_NOTICE_ID": "CN001" },
  { "CHANGE_NOTICE_ID": "CN002" }
]

Part Numbers:

[
  { "PART_NUMBER": "PART001" },
  { "PART_NUMBER": "PART002" }
]

Add vs Edit Mode

• Add Mode: New work item - dropdowns load options on focus
• Edit Mode: Existing work item - dropdowns pre-populate with saved values, then load options on focus

Querying Work Items

Selected values are stored in comma-separated format. To query:

• Use "Contains Words" operator in work item queries
• Example: Custom.CNNum Contains Words CN001

Support

Organization: LTF-WPE-CAT-COM
Support: Contact your Azure DevOps administrator or visit https://dev.azure.com/LTF-WPE-CAT-COM

Technical Details

• Framework: React + TypeScript
• UI Library: Office UI Fabric React
• SDK: Azure DevOps Extension SDK (migrated from VSS SDK)
• Build: Webpack + TypeScript
• Browser Support: Modern browsers (Chrome, Edge, Firefox)

Version History

v1.0.0 (Current)

• Initial release with enhanced features
• Independent CN and Part Number dropdowns
• Client-side search functionality
• API integration with lazy loading
• Performance caching
• Security enhancements

Note: This extension is private to Caterpillar Inc organization and is not available in the public marketplace.