DP44/docs/ai/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-17T15:26:52.176871+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "75086f6da3a24b58"
---

# XML Import Parsers Documentation

## 1. Purpose

This module provides a collection of XML parsing classes for importing configuration data into the DTS system. Each parser handles a specific domain entity (sensors, calibrations, groups, test setups, hardware, etc.) and follows a strategy pattern via the `XMLParseBase` abstract class. The module supports versioned imports with migration logic for pre-2.0 data formats, ID normalization to avoid collisions with existing database records, and cancellation support for long-running operations. Parsers transform XML elements into domain objects and populate an `ImportObject` container for downstream processing.

---

## 2. Public Interface

### XMLParseBase (Abstract Base Class)

```csharp
public abstract class XMLParseBase : IParseVariant
{
    public string FileName { get; set; }
    public abstract void Parse(ref ImportObject importObject);
    
    protected XMLParseBase(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)
}
```

**Behavior:** Base class for all XML parsers. Maintains static ID mapping dictionaries (`_dasIdMapping`, `_groupIdMapping`, `_sensorIdMapping`, `_channelIdMapping`) for cross-parser ID normalization. Provides protected helper methods `GetXmlElement()` and `IsCancelled()`. Initializes an internal `XmlWriter` for generating transformed XML.

---

### 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)
```

**Behavior:** Parses DAS (Data Acquisition System) hardware from XML. Normalizes DAS IDs starting at -2 (preserving -1 for unassigned channels per FB 13544). 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. Normalizes sensor `DatabaseId` starting at -2 (preserving -1 for invalid). Populates `_sensorIdMapping` during conversion. Respects `_skipNormalizing` flag.

---

### 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)
```

**Behavior:** Parses static groups. Clears `_groupIdMapping` on construction. Normalizes group IDs starting at -2. Maps group channels' DAS and Sensor IDs using `_dasIdMapping` and `_sensorIdMapping`. Handles deleted sensors gracefully (FB 14308) by setting `SensorId = 0`. Uses string-based group ID mapping for pre-2.1 exports, integer-based for 2.1+.

---

### 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)
```

**Behavior:** Parses test setups/templates. Clears `_channelIdMapping` on construction. Normalizes channel IDs and group IDs within test templates. Maps hardware references using `_dasIdMapping`. Sets `TestSetupImportFileFormat` on the import object. Catches and records XML read errors as warnings (FB 36879). Handles deleted sensors (FB 14308) and orphaned static group references.

---

### 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 calibrations. Version-specific handling: for version 1.0, sets `AtCapacity = false` and derives `SensitivityUnits` from `NonLinear`/`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. Builds channel lookup from `importObject.CustomChannels()`. Sets `Embedded = true` for system-built or embedded templates. Throws `NotSupportedException` if referenced ISO test object is not found (FB 8790).

---

### 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)
```

**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)
```

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

---

### XMLParseSensorModels

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

public override void Parse(ref ImportObject importObject)
```

**Behavior:** Parses `SensorModel` objects. Creates new instances and calls `ReadXML` on each child element.

---

### XMLParseCustomerDetails, XMLParseLabDetails, XMLParseTestEngineerDetails

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

public IImportNotification ImportNotification { get; set; }  // All three
public override void Parse(ref ImportObject importObject)     // All three
```

**Behavior:** Parse ISO entity details (customer, lab, test engineer). Each reads child elements, converts via internal `XmlWriter`, and re-parses. Sets specific import status (`ReadingCustomerDetails`, `ReadingLabDetails`).

---

### MME Custom Parsers (7 classes)

```csharp
// All follow same pattern:
public XMLParseMMECustom[Type](XmlElement root, double importedVersion, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)

// Types: Directions, TestObjects, Positions, FineLoc3s, FineLoc2s, FineLoc1s, FilterClasses, Channels, MainLocations, PhysicalDimensions
```

**Behavior:** Each parses ISO MME reference data types by iterating child nodes and calling `ReadXML` on each `XmlElement`. Most check `IsCancelled()` per iteration; `XMLParseMMECustomChannels` does not.

---

### Pre-20 Migration Parsers

```csharp
// XMLPre20ParseGroupTemplates
public XMLPre20ParseGroupTemplates(XmlElement root, double importedVersion, XMLParseGroupTemplates xmlParseGroupTemplates, Func<bool> isCancelled = null)

// XMLPre20ParseSensors
public XMLPre20ParseSensors(XmlElement root, double importedVersion, XMLParseSensors xmlParseSensors, Func<bool> isCancelled = null)
public XmlElement MigrateSensors(IEnumerable<SensorData> sensors)

// XMLPre20ParseDASList
public XMLPre20ParseDASList(XmlElement root, double importedVersion, XMLParseDASList xmlParseDASList, Func<bool> isCancelled = null)
public List<DASHardware> ParsePre20DASList(XmlElement root)

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

**Behavior:** Decorator-style parsers that delegate to their non-Pre20 counterparts after performing version-specific migration. `XMLPre20ParseSensors` assigns negative database IDs starting at -1. `XMLPre20ParseDASList` wraps ISO hardware in `DASHardware` instances.

---

## 3. Invariants

1. **ID Normalization Range:** DAS, Sensor, Group, and Channel IDs are normalized to negative integers starting at -2 (or -1 for sensors in pre-20 migration), preserving -1 for "invalid/unassigned" semantics.

2. **Static Mapping Dictionaries:** `_dasIdMapping`, `_groupIdMapping`, `_sensorIdMapping`, and `_channelIdMapping` are `static readonly` and shared across all parser instances. Callers must ensure proper sequencing (DAS before Sensors before Groups before TestSetups).

3. **Group ID Mapping Key Type:** `_groupIdMapping` uses `string` keys to support both legacy name-based references (pre-2.1) and modern ID-based references (2.1+).

4. **Cancellation Contract:** If `isCancelled` parameter is null, `IsCancelled()` returns `false`. Parsers return partially-populated lists when cancelled mid-iteration.

5. **ImportObject Population:** All `Parse` methods modify the passed `ImportObject` via `ref` and call specific `Add*` methods (e.g., `AddSensors`, `AddHardwareList`, `AddStaticGroups`).

6. **Version Thresholds:** 
   - `FileUtils.DataPROPre20XmlVersion` distinguishes pre-2.0 from modern formats
   - `FileUtils.DataPRO21XmlVersion` (2.1+) changes group ID reference semantics
   - Version 1.0 has special calibration sensitivity unit handling

---

## 4. Dependencies

### This module depends on:
- `DTS.Common.Import.Interfaces` - `ImportObject`, `IParseVariant`, `IImportNotification`, `ImportStatus`, `ImportError`, `ImportSeverityError`
- `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` - Localized error messages (`StringResources`)
- `DTS.Common.Enums.DBExport` - `TopLevelFields` enum for XML element names
- `DTS.Common.Enums` - Various enums
- `DTS.Common.Enums.Sensors` - `SensorConstants.SensUnits`
- `DTS.Common.Utils` - `FileUtils` with version constants
- `DTS.SensorDB` - `SensorData`, `SensorCalibration`, `SensorModel`
- `DTS.Slice.Users` - `User` class
- `DataPROWin7.DataModel` - `DASHardware`, `TestObjectTemplate`, `TestObject`
- `DTS.Common.Classes.TestSetups` - `TestTemplate`
- `DTS.Common.ISO` or `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:
- Not explicitly shown in source, but inferred: Import orchestration code that instantiates these parsers based on XML structure and version, then processes the populated `ImportObject`.

---

## 5. Gotchas

1. **Static Dictionary State:** The ID mapping dictionaries are static and shared. `XMLParseDASList`, `XMLParseGroups`, and `XMLParseTestSetups` clear their respective dictionaries in constructors, but if parsers are instantiated out of order or reused, mappings may be incorrect.

2. **Missing Cancellation Check:** `XMLParseMMECustomChannels.ParseCustomChannels` does not check `IsCancelled()` during iteration, unlike all other MME parsers.

3. **Unused ImportNotification Property:** `XMLParseMMECustomChannels` declares `ImportNotification` property but never uses it.

4. **Empty Error Handling:** In `XMLParseDASList.ParseDASList`, invalid DAS entries are collected into `invalidDAS` list but the subsequent `if (invalidDAS.Any()) { //??? }` block is empty—no error is reported.

5. **Pre-20 Sensor ID Collision:** `XMLPre20ParseSensors.MigrateSensors` starts IDs at -1, while `XMLParseSensors.ConvertSensors` starts at -2. This inconsistency could cause issues if both are used in the same import pipeline.

6. **Group Template Embedded Logic:** `XMLParseGroupTemplates` sets `template.Embedded = template.SysBuilt || template.Embedded` after reading XML, which may override the imported value unexpectedly.

7. **Orphaned Static Group Handling:** `XMLParseTestSetups.ConvertTestTemplates` silently sets `group.StaticGroupId = null` if the ID isn't found in `_groupIdMapping`, with only a comment explaining this is for buggy old exports.

8. **Version 1.0 Calibration Assumptions:** The calibration parser makes assumptions about sensitivity units for version 1.0 files based on `NonLinear` and `IsProportional` flags that may not be accurate for all legacy data.

9. **XmlWriter State Management:** `XMLParseBase.GetXmlElement()` calls `_writer.Close()`, which means it can only be called once per instance. Subsequent calls would fail.