DP44/enriched-partialglm/Common/DTS.Common.Import/XML.md

---
source_files:
  - Common/DTS.Common.Import/XML/XMLPre20ParseGroupTemplates.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomDirections.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomTestObjects.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomPositions.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomFineLoc3s.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomFineLoc2s.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomFineLoc1s.cs
  - Common/DTS.Common.Import/XML/XMLParseSensorModels.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomFilterClasses.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomChannels.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomMainLocations.cs
  - Common/DTS.Common.Import/XML/XMLParseMMECustomPhysicalDimensions.cs
  - Common/DTS.Common.Import/XML/XMLPre20ParseSensors.cs
  - Common/DTS.Common.Import/XML/XMLParseUsers.cs
  - Common/DTS.Common.Import/XML/XMLParseBase.cs
  - Common/DTS.Common.Import/XML/XMLParseTestEngineerDetails.cs
  - Common/DTS.Common.Import/XML/XMLParseLabDetails.cs
  - Common/DTS.Common.Import/XML/XMLParseGlobalSettings.cs
  - Common/DTS.Common.Import/XML/XMLPre20ParseDASList.cs
  - Common/DTS.Common.Import/XML/XMLParseCustomerDetails.cs
  - Common/DTS.Common.Import/XML/XMLParseSensors.cs
  - Common/DTS.Common.Import/XML/XMLParseDASList.cs
  - Common/DTS.Common.Import/XML/XMLParseGroupTemplates.cs
  - Common/DTS.Common.Import/XML/XMLParseCalibrations.cs
  - Common/DTS.Common.Import/XML/XMLPre20ParseCalibrations.cs
  - Common/DTS.Common.Import/XML/XMLParseGroups.cs
  - Common/DTS.Common.Import/XML/XMLParseTestSetups.cs
generated_at: "2026-04-16T11:44:54.944851+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "87dec39982bd8179"
---

# Documentation: DTS.Common.Import.XML Parsers

## 1. Purpose

This module provides a family of XML parsing classes for importing configuration and data entities into the DTS system. Each parser handles a specific domain entity (sensors, hardware, groups, test setups, calibrations, MME custom definitions, etc.) by reading XML elements and populating an `ImportObject`. The module supports versioned imports (handling pre-2.0, 1.0, and 2.1+ formats) with ID normalization to avoid collisions with existing database records. All parsers inherit from `XMLParseBase` and implement `IParseVariant`, enabling a strategy pattern for import operations.

---

## 2. Public Interface

### XMLParseBase (Abstract Base Class)

```csharp
public abstract class XMLParseBase : IParseVariant
{
    // Properties
    public string FileName { get; set; }
    
    // Abstract method
    public abstract void Parse(ref ImportObject importObject);
    
    // Constructor
    protected XMLParseBase(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)
    
    // Protected methods
    protected XmlElement GetXmlElement()
    protected bool IsCancelled() // via delegate
}
```

**Behavior**: Base class providing shared infrastructure for all XML parsers. Maintains static ID mapping dictionaries for DAS, group, sensor, and channel IDs. Provides cancellation support via delegate and XML document building utilities via `XmlWriter`.

---

### XMLParseDASList

```csharp
public XMLParseDASList(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public List<DASHardware> ParseDASList(XmlElement root)
private XmlElement ConvertDASList(List<DASHardware> dasList)
```

**Behavior**: Parses DAS (Data Acquisition System) hardware entries. Normalizes DAS IDs starting at -2 (preserving -1 for unassigned channels). Validates hardware types against `DTS.Common.Enums.Hardware.HardwareTypes`. Clears `_dasIdMapping` on construction.

---

### XMLParseSensors

```csharp
public XMLParseSensors(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public XmlElement ConvertSensors(IEnumerable<SensorData> sensors)
public IEnumerable<SensorData> ParseSensors(XmlElement root)
```

**Behavior**: Parses sensor data entries. Normalizes sensor `DatabaseId` starting at -2 (preserving -1 for invalid). Populates `_sensorIdMapping` during conversion. Optionally skips normalization via `_skipNormalizing`.

---

### XMLParseGroups

```csharp
public XMLParseGroups(XmlElement root, double importedVersion, Func<bool> isCancelled = null)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public List<IGroup> ParseGroups(XmlElement root, ref ImportObject importObject)
private XmlElement ConvertGroups(List<IGroup> staticGroups)
```

**Behavior**: Parses static group definitions. Normalizes group IDs starting at -2. Maps group IDs by string (name) for pre-2.1 exports, by integer ID for 2.1+. Remaps DAS and sensor IDs in group channels using `_dasIdMapping` and `_sensorIdMapping`. Clears `_groupIdMapping` on construction.

---

### XMLParseTestSetups

```csharp
public XMLParseTestSetups(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public IEnumerable<TestTemplate> ParseTestTemplate(ImportObject importObject, XmlElement root)
private XmlElement ConvertTestTemplates(IEnumerable<TestTemplate> testTemplates, ImportObject importObject)
```

**Behavior**: Parses test setup templates. Normalizes channel IDs starting at -1. Remaps DAS, sensor, and group IDs using the static mapping dictionaries. Handles embedded groups and deleted sensor references gracefully. Clears `_channelIdMapping` on construction. Sets `importObject.TestSetupImportFileFormat` based on template count.

---

### XMLParseCalibrations

```csharp
public XMLParseCalibrations(XmlElement root, double importedVersion, Func<bool> isCancelled = null)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public XmlElement ConvertCalibrations(IEnumerable<SensorCalibration> calibrations)
public IEnumerable<SensorCalibration> ParseCalibrations(XmlElement root)
```

**Behavior**: Parses sensor calibration data. Handles version-specific logic: for version 1.0, sets `AtCapacity = false` and derives `SensitivityUnits` based on `NonLinear` and `IsProportional` flags. Uses `FileUtils.DataPROPre20XmlVersion` threshold.

---

### XMLParseGroupTemplates

```csharp
public XMLParseGroupTemplates(XmlElement root, double importedVersion, ISO.ISO13499FileDb iSO13499FileDb, Func<bool> isCancelled = null)

public override void Parse(ref ImportObject importObject)
public IEnumerable<DataPROWin7.DataModel.TestObjectTemplate> ParseGroupTemplates(ref ImportObject importObject, XmlElement root)
```

**Behavior**: Parses group templates (test object templates). Requires `ISO13499FileDb` reference. Sets `Embedded = true` for system-built or embedded templates. Throws `NotSupportedException` if referenced ISO test object is not found in import file.

---

### XMLParseUsers

```csharp
public XMLParseUsers(XmlElement root, double importedVersion, IEnumerable<IUIItems> uiItems, Func<bool> isCancelled = null)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private IEnumerable<User> ParseUsers(XmlElement root, IEnumerable<IUIItems> iUItems)
```

**Behavior**: Parses user records. Requires `IEnumerable<IUIItems>` for user construction. Sets import status to `ReadingUsers`.

---

### XMLParseGlobalSettings

```csharp
public XMLParseGlobalSettings(XmlElement root, double importedVersion, Func<bool> isCancelled = null)

public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private Dictionary<string, string> ParseGlobalSettings(XmlElement root)
private void GetGlobalSetting(XmlElement node, ref Dictionary<string, string> settings)
```

**Behavior**: Parses global settings into a `Dictionary<string, string>`. Reads `SettingName` and `SettingValue` child elements.

---

### XMLParseSensorModels

```csharp
public XMLParseSensorModels(XmlElement root, double importedVersion, Func<bool> isCancelled = null)

public override void Parse(ref ImportObject importObject)
private List<SensorModel> ParseSensorModels(XmlElement root)
```

**Behavior**: Parses sensor model definitions. Creates new `SensorModel` instances and calls `ReadXML` on each.

---

### MME Custom Parsers (8 classes)

All follow the same pattern:

```csharp
// XMLParseMMECustomDirections
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEDirections> ParseCustomDirections(XmlElement root)

// XMLParseMMECustomTestObjects
public override void Parse(ref ImportObject importObject)
public IEnumerable<ISO.MMETestObjects> ParseCustomTestObjects(XmlElement root)

// XMLParseMMECustomPositions
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEPositions> ParsePhysicalDimensions(XmlElement root)

// XMLParseMMECustomFineLoc1s/2s/3s
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEFineLocations1/2/3> ParseCustomFineLoc1s/2s/3s(XmlElement root)

// XMLParseMMECustomFilterClasses
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEFilterClasses> ParseMMECustomFilterClasses(XmlElement root)

// XMLParseMMECustomChannels
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public IEnumerable<ISO.MMEPossibleChannels> ParseCustomChannels(XmlElement root)

// XMLParseMMECustomMainLocations
public override void Parse(ref ImportObject importObject)
public IEnumerable<ISO.MMETransducerMainLocation> ParseCustomMainLocations(XmlElement root)

// XMLParseMMECustomPhysicalDimensions
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEPhysicalDimensions> ParsePhysicalDimensions(XmlElement root)
```

**Behavior**: Each parses ISO MME (Measurement Module Equipment) custom definitions by iterating child nodes and calling `ReadXML` on the appropriate ISO type.

---

### Detail Parsers (3 classes)

```csharp
// XMLParseCustomerDetails
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private XmlElement ConvertCustomerDetails(IEnumerable<ISO.CustomerDetails> customerDetails)
private List<ISO.CustomerDetails> ParseCustomerDetails(XmlElement root)

// XMLParseTestEngineerDetails
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private XmlElement ConvertTestEngineerDetails(IEnumerable<ISO.TestEngineerDetails> details)
private List<ISO.TestEngineerDetails> ParseTestEngineerDetails(XmlElement root)

// XMLParseLabDetails
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private XmlElement ConvertLabDetails(IEnumerable<ISO.LabratoryDetails> details)
private List<ISO.LabratoryDetails> ParseLabDetails(XmlElement root)
```

**Behavior**: Parse and re-serialize detail records. Set import status notifications.

---

### Pre-20 Version Parsers (4 classes)

```csharp
// XMLPre20ParseDASList
public XMLPre20ParseDASList(XmlElement root, double importedVersion, XMLParseDASList xmlParseDASList, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
public List<DASHardware> ParsePre20DASList(XmlElement root)
private XmlElement MigratePre20DASList(List<DASHardware> dasList)

// XMLPre20ParseSensors
public XMLPre20ParseSensors(XmlElement root, double importedVersion, XMLParseSensors xmlParseSensors, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
public XmlElement MigrateSensors(IEnumerable<SensorData> sensors)

// XMLPre20ParseCalibrations
public XMLPre20ParseCalibrations(XmlElement root, double importedVersion, XMLParseCalibrations xmlParseCalibrations, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
private IEnumerable<SensorCalibration> ParsePre20Calibrations(ref ImportObject importObject)

// XMLPre20ParseGroupTemplates
public XMLPre20ParseGroupTemplates(XmlElement root, double importedVersion, XMLParseGroupTemplates xmlParseGroupTemplates, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
```

**Behavior**: Handle migration from pre-2.0 XML formats. Delegate to corresponding non-Pre20 parser after initial parsing. Use negative ID assignment starting at -1 for sensors/DAS.

---

## 3. Invariants

1. **ID Normalization**: All normalized IDs are negative integers. DAS and sensor normalization starts at -2 (preserving -1 for "unassigned/invalid"). Group normalization starts at -2. Channel normalization starts at -1.

2. **Mapping Dictionary Lifecycle**: 
   - `_dasIdMapping` is cleared in `XMLParseDASList` constructor
   - `_groupIdMapping` is cleared in `XMLParseGroups` constructor
   - `_channelIdMapping` is cleared in `XMLParseTestSetups` constructor
   - `_sensorIdMapping` is NOT explicitly cleared (relies on static initialization)

3. **Import Order Dependency**: Parsers must be invoked in dependency order (DAS → Sensors → Groups → TestSetups) because later parsers use mapping dictionaries populated by earlier parsers.

4. **Cancellation Contract**: When `IsCancelled()` returns true, parsers return their partially-filled collection immediately.

5. **Version Thresholds**:
   - `1.0D`: Legacy format requiring calibration unit inference
   - `FileUtils.DataPROPre20XmlVersion`: Pre-2.0 format threshold
   - `FileUtils.DataPRO21XmlVersion`: 2.1+ format (uses integer group IDs instead of names)

---

## 4. Dependencies

### This module depends on:
- `DTS.Common.Import.Interfaces` - `IParseVariant`, `ImportObject`, `IImportNotification`, `ImportStatus`, `ImportError`, `ImportSeverityError`
- `DTS.Common.Enums.DBExport` - `TopLevelFields` enum
- `DTS.Common.Enums` - Various enums
- `DTS.Common.Interface` - `IUIItems`, sensor interfaces
- `DTS.Common.Interface.Groups.GroupList` - `IGroup`, group interfaces
- `DTS.Common.Interface.GroupTemplate` - Group template interfaces
- `DTS.Common.SharedResource.Strings` - `StringResources` for error messages
- `DTS.Common.Utils` - `FileUtils` with version constants
- `DTS.SensorDB` - `SensorData`, `SensorModel`, `SensorCalibration`, `SensorConstants`
- `DTS.Slice.Users` - `User` class
- `DataPROWin7.DataModel` - `DASHardware`, `TestObjectTemplate`, `TestObject`
- `DTS.Common.Classes.TestSetups` - `TestTemplate`
- `DTS.Common.ISO` / `ISO` namespace - MME types (`MMEDirections`, `MMETestObjects`, `MMEPositions`, `MMEFineLocations1/2/3`, `MMEFilterClasses`, `MMEPossibleChannels`, `MMETransducerMainLocation`, `MMEPhysicalDimensions`, `CustomerDetails`, `TestEngineerDetails`, `LabratoryDetails`)
- `System.Xml` - `XmlElement`, `XmlDocument`, `XmlWriter`

### What depends on this module:
- Unknown from source alone (no consumers shown in imports)

---

## 5. Gotchas

1. **Static Mapping Dictionaries**: The ID mapping dictionaries (`_dasIdMapping`, `_groupIdMapping`, `_sensorIdMapping`, `_channelIdMapping`) are `static`, meaning they persist across parser instances. If parsers are instantiated out of order or reused, stale mappings could cause incorrect ID translations.

2. **Inconsistent Cancellation Checks**: `XMLParseMMECustomChannels.ParseCustomChannels` does NOT check `IsCancelled()` during iteration, unlike all other MME parsers. This could lead to non-responsive cancellation for large channel imports.

3. **Pre-20 vs Standard ID Normalization Difference**: 
   - `XMLPre20ParseSensors` and `XMLPre20ParseDASList` start normalization at -1
   - `XMLParseSensors` and `XMLParseDASList` start at -2
   This inconsistency may be intentional (different handling for pre-2.0 imports) but could cause confusion.

4. **Unused Invalid DAS Collection**: In `XMLParseDASList.ParseDASList`, invalid DAS serial numbers are collected into `invalidDAS` list but the subsequent `if (invalidDAS.Any()) { //??? }` block is empty, suggesting incomplete error handling.

5. **Group ID Mapping Key Type**: `_groupIdMapping` uses `string` keys to handle both old exports (group name) and new exports (integer ID as string). This dual-mode requires careful version checking via `_importedVersion >= FileUtils.DataPRO21XmlVersion`.

6. **Missing Sensor Handling**: In `XMLParseGroups` and `XMLParseTestSetups`, if a sensor ID is not found in `_sensorIdMapping`, it's silently set to 0 rather than failing (per FB 14308). This handles deleted sensors gracefully but may mask data integrity issues.

7. **XMLParseMMECustomChannels Public ImportNotification**: The `ImportNotification` property on `XMLParseMMECustomChannels` is never used within the class, unlike other parsers that call `SetStatus`.

8. **Ref Parameter Patterns**: Several methods pass `ImportObject` by `ref` even when not reassigning the variable, which is unnecessary but harmless.