--- 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 errors, out List 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 errors, out List 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` - **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`, 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.