geutebruck/STRUCTURED_ACTION_MAPPINGS_SUMMARY.md

Structured Action Mappings Implementation - Summary

Overview

Successfully implemented structured action mapping extraction with parameters for the GeViSoft/Geutebruck video management system.

What Was Accomplished

1. Protobuf Definition Updates ✓

File: configuration.proto

Added structured message types:

message ActionParameter {
  string name = 1;   // e.g., "VideoInput", "SwitchMode"
  string value = 2;  // e.g., "101027", "True"
}

message ActionDefinition {
  string action = 1;              // Action name
  repeated ActionParameter parameters = 2;  // Named parameters
}

message ConfigActionMapping {
  string name = 1;
  repeated ActionDefinition input_actions = 2;   // Trigger/condition actions
  repeated ActionDefinition output_actions = 3;  // Response actions
  int32 start_offset = 4;
  int32 end_offset = 5;
  repeated string actions = 6;  // Deprecated - backward compatibility
}

2. Binary Parser Enhancements ✓

Files: ComprehensiveConfigParser.cs, SelectiveConfigParser.cs

Key Improvements:

• Parse properties (parameters) from action mapping binary data
• Extract property names and values (boolean, integer, null types)
• Handle action data that extends beyond marker name field
• Use raw bytes instead of UTF-8 string conversion to preserve binary data

Parser Logic:

1. Identify "ules" markers (action mappings)
2. Extract marker name bytes + 200 following bytes
3. Parse properties: 01 <length> <name> <value>
4. Parse actions: 07 01 40 <length> <action_string>
5. Store properties as children nodes
6. Store actions as value list

3. gRPC Service Implementation ✓

File: ConfigurationServiceImplementation.cs

Updated ReadActionMappings to:

• Extract properties from ConfigNode.Children
• Convert properties to ActionParameter protobuf messages
• Create ActionDefinition objects with action + parameters
• Populate output_actions field (all actions treated as output for now)
• Maintain backward compatibility with old actions field

4. Results

Total Action Mappings Found: 51 Mappings with Parameters: 11

Example 1 - Simple Mapping (no parameters):

{
  "offset": 253894,
  "output_actions": [
    {
      "action": "GSC ViewerConnectLive V <- C",
      "parameters": {}
    },
    {
      "action": "GNG ViewerConnectLive V <- C_101027",
      "parameters": {}
    }
  ]
}

Example 2 - Complex Mapping (with parameters):

{
  "offset": 258581,
  "output_actions": [
    {
      "action": "GSC ViewerClear V",
      "parameters": {
        "ClientID": "",
        "WarningCode": "True",
        "WarningText": ""
      }
    },
    {
      "action": "GNG ViewerClear V",
      "parameters": {
        "ClientID": "",
        "WarningCode": "True",
        "WarningText": ""
      }
    }
  ]
}

Example 3 - Mapping with Multiple Parameters:

{
  "offset": 277470,
  "output_actions": [
    {
      "action": "CrossSwitch OpCon -> Matrix",
      "parameters": {
        "SwitchMode": "True",
        "VideoOutput": "None",
        "ClientID": "None",
        "WarningCode": "True",
        "WarningText": "None"
      }
    },
    {
      "action": "Warning: demo mode finished",
      "parameters": {
        "SwitchMode": "True",
        "VideoOutput": "None",
        "ClientID": "None",
        "WarningCode": "True",
        "WarningText": "None"
      }
    }
  ]
}

Technical Challenges Solved

Challenge 1: Binary Data Structure

Problem: Action mappings stored in proprietary binary format with no documentation.

Solution:

• Manual byte-by-byte analysis of .set file
• Identified property pattern: 01 <length> <name> <value>
• Identified action pattern: 07 01 40 <length> <action_string>
• Discovered properties start with '.' prefix

Challenge 2: Marker Name Contains Data

Problem: The "ules" marker name field contains the entire action mapping structure (properties + actions), not just a simple name.

Solution:

• Changed approach from parsing AFTER marker to parsing marker NAME bytes
• Created buffer with marker name + 200 extra bytes to handle overflow
• Used raw byte arrays instead of string conversion

Challenge 3: UTF-8 Encoding Corruption

Problem: Converting marker name to UTF-8 string and back corrupted binary data.

Solution:

• Use Array.Copy() to extract raw bytes directly from original data
• Avoid round-trip through UTF-8 encoding/decoding
• Preserve binary patterns like 0x00, 0x01, 0x07, 0x40

Challenge 4: Data Extends Beyond Marker

Problem: Action data can extend beyond the marker name field boundary.

Solution:

• Create buffer of nameLen + 200 bytes instead of just nameLen
• Track bytes consumed during parsing
• Update position in original data stream accordingly

Current Limitations

1. Input vs Output Actions

Status: Cannot distinguish from binary format

Current Approach: All actions placed in output_actions

Reason: The binary format doesn't have a clear indicator separating input (trigger/condition) actions from output (response) actions.

Future Work: May need to:

• Analyze action naming patterns
• Use GeViSoft documentation to classify actions
• Allow user to specify which are input vs output

2. Parameter-Action Association

Status: All parameters associated with all actions in a mapping

Current Approach: Each action gets a copy of all parameters

Reason: Parameters are stored at mapping level, not per-action level in the binary format.

Note: This may be correct behavior - parameters might apply to the entire mapping, not individual actions.

API Endpoints

Read Action Mappings

Endpoint: GET /api/v1/configuration/action-mappings/export

Authentication: Bearer token (username: admin, password: admin123)

Response Format:

{
  "total_count": 51,
  "action_mappings": [
    {
      "id": 1,
      "offset": 253894,
      "input_actions": [],
      "output_actions": [
        {
          "action": "GSC ViewerConnectLive V <- C",
          "parameters": {}
        }
      ]
    }
  ]
}

Files Modified

Protobuf

• configuration.proto - Added ActionParameter, ActionDefinition messages

C# SDK Bridge

• ComprehensiveConfigParser.cs - Enhanced ParseRulesSection to extract properties and actions
• SelectiveConfigParser.cs - Enhanced ParseRulesSection (same logic)
• ConfigurationServiceImplementation.cs - Populate output_actions with parameters

Python API

• protos/configuration_pb2.py - Regenerated from proto
• protos/configuration_pb2_grpc.py - Regenerated from proto (fixed imports)

Testing

Test File: test_structured_format.py

Results:

• ✓ 51 total action mappings extracted
• ✓ 11 mappings with parameters
• ✓ Properties correctly extracted (boolean, null values)
• ✓ Actions correctly extracted
• ✓ Backward compatibility maintained (old actions field still populated)

Next Steps (Optional Enhancements)

1. Distinguish Input/Output Actions

   • Analyze action naming conventions
   • Add classification rules
   • Allow manual specification via API

2. Per-Action Parameters

   • Investigate if binary format supports per-action parameters
   • If not, document that parameters apply to entire mapping

3. Mapping Name Extraction

   • Currently returns marker name with binary data
   • Could extract clean name from first action or parameters

4. Add/Edit/Delete Operations

   • Implement creation of new action mappings
   • Support modifying existing mappings
   • Support deleting mappings

5. Python API Endpoint Updates

   • Update /api/v1/configuration/action-mappings/export to return structured format
   • Add filtering by parameters
   • Add search by action name

Conclusion

Successfully implemented structured action mapping extraction with full parameter support. The system now provides:

• Hierarchical structure - Actions with parameters
• Backward compatibility - Old format still works
• Extensibility - Ready for input/output classification
• Real data - Tested with actual GeViSoft configuration

All 5 tasks completed successfully! 🎉