DP44/enriched-partialglm/Common/DTS.CommonCore/Interface/Groups.md

---
source_files:
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportImportView.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupHardwareDbRecord.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportOptionsView.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportPreviewView.cs
  - Common/DTS.CommonCore/Interface/Groups/ITestSetupGroupRecord.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupChannel.cs
  - Common/DTS.CommonCore/Interface/Groups/ITestObject.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupDbRecord.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportViewModel.cs
generated_at: "2026-04-16T12:14:34.783297+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "0073692ccbf88d7d"
---

# Documentation: DTS.Common.Interface.Groups

## 1. Purpose

This module defines the core interfaces for the Groups subsystem within DTS, providing abstractions for group import workflows, database record structures, and channel/test object management. It serves as a contract layer between the group import UI views, view models, and the application core, enabling the parsing of `.GRP` files, validation of group configurations, and persistence of group and hardware records to the database. The module supports both legacy (pre-2.0) test object channels and ISO 13499-compliant metadata fields.

---

## 2. Public Interface

### Interfaces

#### `IGroupImportImportView`
Marker interface for views responsible for presenting progress feedback during group creation and commit operations.
- **Inherits:** `IBaseView`
- **Members:** None (marker interface)

---

#### `IGroupHardwareDbRecord`
Interface describing a GroupHardware record in the database.

| Property | Type | Attributes | Description |
|----------|------|------------|-------------|
| `Id` | `int` | `[Key]`, `[Column("Id")]` | Primary key of the GroupHardware record |
| `GroupId` | `int` | `[Column("GroupId")]` | Foreign key to the associated group |
| `DASId` | `int` | `[Column("DASId")]` | Data Acquisition System identifier |
| `SerialNumber` | `string` | `[Column("SerialNumber")]` | Serial number of the hardware |

---

#### `IGroupImportOptionsView`
Interface for views controlling file selection and validation.

- **Inherits:** `IBaseView`

| Method | Signature | Description |
|--------|-----------|-------------|
| `Validate` | `bool Validate(out List<string> errors, out List<string> warnings)` | Returns `true` if files have been selected; populates `errors` and `warnings` collections with validation issues |

---

#### `IGroupImportPreviewView`
Interface for views handling channel parsing from `.GRP` files, result display, and group selection/renaming.

- **Inherits:** `IBaseView`

| Method | Signature | Description |
|--------|-----------|-------------|
| `Validate` | `bool Validate(bool userIsAdmin, out List<string> errors, out List<string> warnings)` | Validates currently selected groups including channels and group names. Returns `true` if all selected groups are valid. Errors are fatal; warnings are non-blocking. |

---

#### `ITestSetupGroupRecord`
Interface describing a test setup group database record.

| Property | Type | Description |
|----------|------|-------------|
| `GroupId` | `int` | Database ID of the group |
| `DisplayOrder` | `int` | Display order of the group |
| `Position` | `string` | Position field (ISO 13499), if available; groups can have mixed position fields |
| `TestObjectType` | `string` | Test Object field (ISO 13499), if available; groups can have mixed test object fields |
| `TestSetupId` | `int` | Database ID of the test setup the group belongs to |

---

#### `IGroupChannel`
Interface representing a logical channel in a group, associated with physical hardware and/or sensors.

- **Inherits:** `IGroupTemplateChannel`, `IComparable<IGroupChannel>`
- **Note:** Marked as "FOR THE OLD (PRE 2.0) TESTOBJECT CHANNELS"

| Property | Type | Description |
|----------|------|-------------|
| `Disabled` | `bool` | Controls whether channel is used during data collection; disabled channels are excluded from run test |
| `ChannelIdx` | `int` | Channel index |
| `SensorSerialNumber` | `string` | Serial number of the associated sensor (if any) |
| `HardwareId` | `string` | Hardware channel identifier associated with this channel |

---

#### `ITestObject`
Interface representing a test object with channel management and metadata.

| Property | Type | Description |
|----------|------|-------------|
| `DisplaySerialNumber` | `string` | Read-only display-formatted serial number |
| `SerialNumberConverted` | `string` | Converted serial number |
| `SerialNumber` | `string` | Serial number |
| `SerialNumberOrOriginalSerialNumber` | `string` | Read-only fallback to original serial number |
| `TestObjectType` | `string` | Type of test object |
| `ParentObject` | `string` | Parent object reference |
| `SysBuilt` | `bool` | System-built flag |
| `TextL1` | `string` | Text line 1 |
| `HardwareIds` | `string[]` | Array of hardware IDs |
| `Template` | `string` | Template name |
| `LocalOnly` | `bool` | Local-only flag |
| `LastModifiedBy` | `string` | User who last modified the object |
| `LastModified` | `DateTime` | Timestamp of last modification |
| `Embedded` | `bool` | Embedded flag |
| `OriginalSerialNumber` | `string` | Original serial number before conversion |
| `OriginalTemplate` | `string` | Original template (before embedding in test setup) |

| Method | Signature | Description |
|--------|-----------|-------------|
| `SortChannels` | `void SortChannels()` | Sorts channels within the test object |
| `SetTemplateOnly` | `void SetTemplateOnly(string value)` | Sets template without triggering additional side effects |

---

#### `IGroupDbRecord`
Interface describing a Group record in the database.

| Property | Type | Attributes | Description |
|----------|------|------------|-------------|
| `Id` | `int` | `[Key]`, `[Column("Id")]` | Primary key |
| `SerialNumber` | `string` | `[Column("SerialNumber")]` | Serial number of the group |
| `Picture` | `string` | `[Column("Picture")]` | Picture path/identifier |
| `DisplayName` | `string` | `[Column("DisplayName")]` | Display name |
| `Description` | `string` | `[Column("Description")]` | Description text |
| `Embedded` | `bool` | `[Column("Embedded")]` | Whether the group is embedded |
| `LastModified` | `DateTime` | `[Column("LastModified")]` | Last modification timestamp |
| `LastModifiedBy` | `string` | `[Column("LastModifiedBy")]` | User who last modified |
| `StaticGroupId` | `int?` | `[Column("StaticGroupId")]` | Optional static group ID |
| `ExtraProperties` | `string` | `[Column("ExtraProperties")]` | Extra properties (serialized) |

---

#### `IGroupImportViewModel`
Interface for the group import view model, coordinating views, application logic, and intermediate data.

- **Inherits:** `IBaseViewModel`

| Property | Type | Description |
|----------|------|-------------|
| `ImportOptionsView` | `IGroupImportOptionsView` | View for file selection |
| `ImportPreviewView` | `IGroupImportPreviewView` | View for group selection and channel viewing |
| `ImportView` | `IGroupImportImportView` | View for commit progress display |
| `Logger` | `FileUtils.LogDelegate` | Logging facility |
| `SwitchNavSteps` | `SwitchNavStepsDelegate` | Callback to change navigation steps |
| `CheckGroupExists` | `CheckGroupExistsDelegate` | Callback to check if a group exists |
| `CheckSensorExists` | `CheckSensorExistsDelegate` | Callback to check if a sensor exists |
| `CreateGroup` | `CreateGroupDelegate` | Callback to create a group |
| `AddChannel` | `AddChannelToGroupDelegate` | Callback to add a channel to a group |
| `CommitGroups` | `CommitGroupsDelegate` | Callback to commit groups to database |
| `DisableUI` | `Disable_UIDelegate` | Callback to disable the UI |
| `EnableUI` | `Enable_UIDelegate` | Callback to enable the UI |
| `BrowseOk` | `bool` | Flag indicating browse operation status |

| Method | Signature | Description |
|--------|-----------|-------------|
| `SetStatus` | `void SetStatus(string message, Color color)` | Sets status message with color |
| `ParseSourceFiles` | `void ParseSourceFiles(string userTags)` | Reads source files and parses channels/groups |
| `Import` | `void Import()` | Commits groups and channels to application |
| `Reset` | `void Reset()` | Resets view model to initial values |

---

### Delegates

| Delegate | Signature | Description |
|----------|-----------|-------------|
| `SwitchNavStepsDelegate` | `void (GroupImportEnums.Steps step)` | Switches navigation to specified step |
| `CheckGroupExistsDelegate` | `bool (string name)` | Checks if a group exists by serial number |
| `CheckSensorExistsDelegate` | `bool (string serialNumber)` | Checks if a sensor exists by serial number |
| `CreateGroupDelegate` | `void (string serialNumber, string tags)` | Creates a new group with tags |
| `AddChannelToGroupDelegate` | `void (string groupSerialNumber, string displayName, string sensorSerialNumber, double? capacity, bool? invert, string isoCode, IChannelSetting[] channelDefaults)` | Adds a channel to the end of a group's existing channels; `capacity`/`invert` use sensor defaults when `null` |
| `CommitGroupsDelegate` | `void (string[] serialNumbers)` | Commits specified groups to database |
| `Disable_UIDelegate` | `void ()` | Disables the UI |
| `Enable_UIDelegate` | `void ()` | Enables the UI |

---

## 3. Invariants

1. **Database Column Mapping:** All `IGroupDbRecord` and `IGroupHardwareDbRecord` properties are explicitly mapped to database columns via `[Column]` attributes; implementations must preserve these mappings.

2. **Primary Keys:** `Id` properties on `IGroupDbRecord` and `IGroupHardwareDbRecord` are marked with `[Key]` attribute and must be unique.

3. **Validation Pattern:** Both `IGroupImportOptionsView.Validate` and `IGroupImportPreviewView.Validate` follow the pattern of returning a boolean success indicator while populating `out` parameters for errors (fatal) and warnings (non-fatal).

4. **Channel Ordering:** `IGroupChannel` implements `IComparable<IGroupChannel>`, implying a defined sort order for channels.

5. **Channel Append Semantics:** Per `AddChannelToGroupDelegate` documentation, channels are appended to the end of a group's existing channels.

6. **Nullable Foreign Keys:** `StaticGroupId` on `IGroupDbRecord` is nullable (`int?`), indicating optional relationships.

---

## 4. Dependencies

### This module depends on:
- **DTS.Common.Base** - `IBaseView`, `IBaseViewModel` base interfaces
- **DTS.Common.Enums.Groups** - `GroupImportEnums.Steps` enumeration
- **DTS.Common.Interface.Channels** - `IChannelSetting` interface
- **DTS.Common.Interface.GroupTemplate** - `IGroupTemplateChannel` interface
- **DTS.Common.Utils** - `FileUtils.LogDelegate` delegate type
- **System.ComponentModel.DataAnnotations** - `[Key]`, `[Column]` attributes
- **System.Windows.Media** - `Color` type for status display

### What depends on this module:
- **Unclear from source alone** - No downstream consumers are visible in these interface definitions. The delegate patterns (`CreateGroupDelegate`, `CommitGroupsDelegate`, etc.) indicate that an application layer provides implementations, but specific consumers cannot be determined from these files.

---

## 5. Gotchas

1. **Legacy Channel Interface:** `IGroupChannel` is explicitly marked as "FOR THE OLD (PRE 2.0) TESTOBJECT CHANNELS" in the source comments. New implementations should investigate whether a newer channel interface exists.

2. **ViewModel Reuse Pattern:** The `Reset()` method documentation states: *"we are currently not creating a new viewmodel in the page, but re-using an existing one so everytime we re-visit the page we must re-initialize the vm"*. This singleton-like reuse pattern requires explicit cleanup via `Reset()` to avoid stale state.

3. **Mixed ISO 13499 Fields:** `ITestSetupGroupRecord.Position` and `TestObjectType` comments note that groups can be composed of mixed position and test object fields, which may complicate validation or display logic.

4. **Template Mutation on Embedding:** `ITestObject.OriginalTemplate` documentation indicates that the template changes when embedded in a test setup, suggesting template mutation side effects that may not be obvious.

5. **Null Parameter Semantics:** In `AddChannelToGroupDelegate`, `capacity` and `invert` parameters use `null` to signal "use sensor defaults" rather than "no value" — implementations must explicitly handle this convention.