--- 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-16T02:21:23.908891+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "0073692ccbf88d7d" --- # Groups ## Documentation: Group Import Module Interfaces --- ### 1. **Purpose** This module defines a set of interfaces that constitute the *Group Import* subsystem, responsible for importing test groups (and their associated channels) from external `.grp` files into the application. It supports a multi-step workflow: selecting source files (`IGroupImportOptionsView`), previewing and validating parsed groups/channels (`IGroupImportPreviewView`), and committing the groups to the system while reporting progress (`IGroupImportImportView`). The module is decoupled from UI implementation via view interfaces and delegates, enabling separation of concerns and testability. It interacts with core domain entities like `IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`, `IGroupChannel`, and `ITestObject`, and relies on external services (e.g., group/sensor existence checks, group creation, database commit) provided via delegate injection. --- ### 2. **Public Interface** #### Interfaces (View Layer) | Interface | Method/Property | Signature | Description | |-----------|-----------------|-----------|-------------| | `IGroupImportImportView` | — | *N/A* | Marker interface (extends `IBaseView`) for the view responsible for displaying progress during group creation and commit. | | `IGroupImportOptionsView` | `Validate` | `bool Validate(out List errors, out List warnings);` | Validates file selection. Returns `true` if files are selected; `false` otherwise. Populates `errors` and `warnings` with validation messages. | | `IGroupImportPreviewView` | `Validate` | `bool Validate(bool userIsAdmin, out List errors, out List warnings);` | Validates selected groups (including channels and group names). `userIsAdmin` may affect validation rules. Returns `true` only if *all* selected groups are valid. Errors prevent proceeding; warnings are non-fatal. | | `IGroupImportViewModel` | `SetStatus` | `void SetStatus(string message, Color color);` | Sets status message and associated color (e.g., for UI feedback). | | | `ImportOptionsView` | `IGroupImportOptionsView ImportOptionsView { get; set; }` | Gets/sets the options view (file selection & validation). | | | `ImportPreviewView` | `IGroupImportPreviewView ImportPreviewView { get; set; }` | Gets/sets the preview view (group/channel parsing & selection). | | | `ImportView` | `IGroupImportImportView ImportView { get; set; }` | Gets/sets the import progress view. | | | `ParseSourceFiles` | `void ParseSourceFiles(string userTags);` | Reads and parses source `.grp` files, extracting groups and channels. `userTags` are applied during parsing. | | | `Import` | `void Import();` | Commits parsed groups and channels to the application. | | | `Reset` | `void Reset();` | Resets the view model to initial state (re-initialization for page reuse). | | | `Logger` | `FileUtils.LogDelegate Logger { get; set; }` | Logging delegate for internal messages. | | | `SwitchNavSteps` | `SwitchNavStepsDelegate SwitchNavSteps { get; set; }` | Delegate to navigate to another step in the application. | | | `CheckGroupExists` | `CheckGroupExistsDelegate CheckGroupExists { get; set; }` | Delegate to check if a group (by serial number) exists. | | | `CheckSensorExists` | `CheckSensorExistsDelegate CheckSensorExists { get; set; }` | Delegate to check if a sensor (by serial number) exists. | | | `CreateGroup` | `CreateGroupDelegate CreateGroup { get; set; }` | Delegate to create a new group (by serial number and tags). | | | `AddChannel` | `AddChannelToGroupDelegate AddChannel { get; set; }` | Delegate to add a channel to a group (with optional overrides for capacity, invert, ISO code, and defaults). | | | `CommitGroups` | `CommitGroupsDelegate CommitGroups { get; set; }` | Delegate to commit one or more groups to the database. | | | `DisableUI` / `EnableUI` | `Disable_UIDelegate DisableUI { get; set; }`
`Enable_UIDelegate EnableUI { get; set; }` | Delegates to disable/enable the UI during long-running operations. | | | `BrowseOk` | `bool BrowseOk { get; set; }` | Indicates whether the file browse operation succeeded (likely used internally). | #### Domain Record Interfaces | Interface | Property | Signature | Description | |-----------|----------|-----------|-------------| | `IGroupHardwareDbRecord` | `Id`, `GroupId`, `DASId`, `SerialNumber` | `int Id { get; set; }`
`int GroupId { get; set; }`
`int DASId { get; set; }`
`string SerialNumber { get; set; }` | Represents a hardware mapping record in the DB: links a group (`GroupId`) to a DAS (`DASId`) and hardware serial number. | | `ITestSetupGroupRecord` | `GroupId`, `DisplayOrder`, `Position`, `TestObjectType`, `TestSetupId` | `int GroupId { get; set; }`
`int DisplayOrder { get; set; }`
`string Position { get; set; }`
`string TestObjectType { get; set; }`
`int TestSetupId { get; set; }` | Represents a test setup group record in the DB. Includes ISO 13499 fields (`Position`, `TestObjectType`). Groups may contain mixed values. | | `IGroupDbRecord` | `Id`, `SerialNumber`, `Picture`, `DisplayName`, `Description`, `Embedded`, `LastModified`, `LastModifiedBy`, `StaticGroupId`, `ExtraProperties` | `int Id { get; set; }`
`string SerialNumber { get; set; }`
`string Picture { get; set; }`
`string DisplayName { get; set; }`
`string Description { get; set; }`
`bool Embedded { get; set; }`
`DateTime LastModified { get; set; }`
`string LastModifiedBy { get; set; }`
`int? StaticGroupId { get; set; }`
`string ExtraProperties { get; set; }` | Represents a group entity in the DB. Includes metadata (display name, description, picture), timestamps, and extensibility (`ExtraProperties`). | #### Channel & Test Object Interfaces | Interface | Property/Method | Signature | Description | |-----------|-----------------|-----------|-------------| | `IGroupChannel` | `Disabled`, `ChannelIdx`, `SensorSerialNumber`, `HardwareId` | `bool Disabled { get; set; }`
`int ChannelIdx { get; set; }`
`string SensorSerialNumber { get; set; }`
`string HardwareId { get; set; }` | Logical channel in a group. `Disabled` excludes it from data collection. Extends `IGroupTemplateChannel` and `IComparable`. | | `ITestObject` | `SortChannels()`, `DisplaySerialNumber`, `SerialNumberConverted`, `SerialNumber`, `SerialNumberOrOriginalSerialNumber`, `TestObjectType`, `ParentObject`, `SysBuilt`, `TextL1`, `HardwareIds`, `Template`, `SetTemplateOnly`, `LocalOnly`, `LastModifiedBy`, `LastModified`, `Embedded`, `OriginalSerialNumber`, `OriginalTemplate` | `void SortChannels();`
`string DisplaySerialNumber { get; }`
`string SerialNumberConverted { get; set; }`
`string SerialNumber { get; set; }`
`string SerialNumberOrOriginalSerialNumber { get; }`
`string TestObjectType { get; set; }`
`string ParentObject { get; set; }`
`bool SysBuilt { get; set; }`
`string TextL1 { get; set; }`
`string[] HardwareIds { get; set; }`
`string Template { get; set; }`
`void SetTemplateOnly(string value);`
`bool LocalOnly { get; set; }`
`string LastModifiedBy { get; set; }`
`DateTime LastModified { get; set; }`
`bool Embedded { get; set; }`
`string OriginalSerialNumber { get; set; }`
`string OriginalTemplate { get; set; }` | Represents a test object (group) in the application. Supports serial number variants, template embedding, and hardware ID tracking. | #### Delegates | Delegate | Signature | Purpose | |----------|-----------|---------| | `SwitchNavStepsDelegate` | `void (GroupImportEnums.Steps step)` | Navigate to a different application step. | | `CheckGroupExistsDelegate` | `bool (string name)` | Check if a group (by serial number/name) exists. | | `CheckSensorExistsDelegate` | `bool (string serialNumber)` | Check if a sensor (by serial number) exists. | | `CreateGroupDelegate` | `void (string serialNumber, string tags)` | Create a new group with given serial number and tags. | | `AddChannelToGroupDelegate` | `void (string groupSerialNumber, string displayName, string sensorSerialNumber, double? capacity, bool? invert, string isoCode, IChannelSetting[] channelDefaults)` | Add a channel to a group. `capacity`/`invert` override sensor defaults if non-null. | | `CommitGroupsDelegate` | `void (string[] serialNumbers)` | Commit groups (by serial numbers) to the database. | | `Disable_UIDelegate` / `Enable_UIDelegate` | `void ()` | Disable/enable the UI. | --- ### 3. **Invariants** - **`IGroupImportOptionsView.Validate`**: Must return `true` *only* if files have been selected. Validation errors/warnings must be non-null outputs (even if empty lists). - **`IGroupImportPreviewView.Validate`**: Must return `true` *only* if *all* selected groups are valid (no errors). Warnings do not affect return value. Admin status (`userIsAdmin`) may influence validation rules. - **`IGroupChannel.Disabled`**: When `true`, the channel must be excluded from data collection during test runs. - **`IGroupDbRecord.Embedded`**: Indicates whether the group is embedded in a test setup (likely immutable after embedding). - **`ITestObject.Embedded` / `ITestObject.OriginalTemplate`**: When a group is embedded, its `Template` may change, but `OriginalTemplate` preserves the pre-embedding value. - **`IGroupHardwareDbRecord`**: Each record uniquely maps a `GroupId` → `DASId` + `SerialNumber`. No constraints on uniqueness of `DASId` or `SerialNumber` across records are specified. --- ### 4. **Dependencies** #### Module Dependencies (from source): - **Base Layer**: `DTS.Common.Base` (`IBaseView`, `IBaseViewModel`) - **Enums**: `DTS.Common.Enums.Groups.GroupImportEnums.Steps` (used in `SwitchNavStepsDelegate`) - **Utils**: `FileUtils.LogDelegate` (for logging) - **Channels**: `DTS.Common.Interface.Channels.IChannelSetting[]` (used in `AddChannelToGroupDelegate`) - **GroupTemplate**: `IGroupTemplateChannel` (base interface for `IGroupChannel`) #### Dependencies *on* this Module: - **UI Layer**: Concrete implementations of `IGroupImportOptionsView`, `IGroupImportPreviewView`, `IGroupImportImportView`, and `IGroupImportViewModel`. - **Application Core**: Must provide implementations for the delegates (`CheckGroupExists`, `CreateGroup`, `AddChannel`, `CommitGroups`, etc.) to integrate with the broader system (DB, sensor/group registries, navigation). #### Inferred Dependencies: - `DTS.Common.Interface.GroupTemplate` (for `IGroupTemplateChannel`). - Database access layer (for `IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`). - Sensor and group registries (for `CheckGroupExists`, `CheckSensorExists`). --- ### 5. **Gotchas** - **`IGroupChannel` is marked for *legacy* use**: The XML comment explicitly states: *"THIS IS FOR THE OLD (PRE 2.0) TESTOBJECT CHANNELS"*. New implementations may use a different channel model. - **`ITestObject` has redundant serial number properties**: `SerialNumber`, `OriginalSerialNumber`, `SerialNumberConverted`, and `SerialNumberOrOriginalSerialNumber` suggest complex serial number handling (e.g., conversion, fallback logic). Behavior of these properties is not fully specified. - **`IGroupImportPreviewView.Validate` admin flag**: The `userIsAdmin` parameter implies role-based validation rules, but the source does not specify how admin/non-admin behavior differs. - **`IGroupImportViewModel` re-use pattern**: The `Reset()` method exists because the view model is reused across page visits (not recreated). This may lead to state leakage if `Reset()` is incomplete or skipped. - **`AddChannelToGroupDelegate` parameters**: `capacity`/`invert` are nullable; null means "use sensor defaults". This is critical for correct channel configuration. - **`IGroupHardwareDbRecord` field names**: Uses `DASId` (not `HardwareId` or `DeviceId`), suggesting a specific hardware abstraction layer (DAS = Data Acquisition System?). - **No validation rules for group names/serial numbers**: The interfaces do not define naming constraints (e.g., uniqueness, allowed characters), though `CheckGroupExists` implies uniqueness enforcement elsewhere. *None identified beyond the above.*