geutebruck/STRUCTURED_ACTIONS_GUIDE.md

# Structured Action Mappings - Edit Guide

## ✅ What's New

Actions are now parsed into **structured format** so you can easily edit action names AND parameters separately!

## Output Format

### Before (Simple strings):
```json
{
  "id": 1,
  "actions": ["VMD_Start(101050)", "CrossSwitch(101050, 3, 0)"]
}
```

### After (Structured with action + parameters):
```json
{
  "id": 1,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    },
    {
      "action": "CrossSwitch",
      "parameters": ["101050", "3", "0"]
    }
  ]
}
```

## How to Edit

### Example 1: Change Parameters

**Original:**
```json
{
  "id": 10,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    }
  ]
}
```

**Edit camera ID from 101050 to 101027:**
```json
{
  "id": 10,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101027"]  ← Changed
    }
  ]
}
```

### Example 2: Add Parameters to Action

**Original:**
```json
{
  "id": 5,
  "actions": [
    {
      "action": "GSC ViewerConnectLive V <- C",
      "parameters": []
    }
  ]
}
```

**Add camera parameter:**
```json
{
  "id": 5,
  "actions": [
    {
      "action": "ViewerConnectLive",
      "parameters": ["101050", "1"]  ← Added parameters
    }
  ]
}
```

### Example 3: Add Multiple Actions to One Mapping

**Original:**
```json
{
  "id": 15,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    }
  ]
}
```

**Add CrossSwitch action:**
```json
{
  "id": 15,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    },
    {
      "action": "CrossSwitch",
      "parameters": ["101050", "3", "0"]  ← Added new action
    }
  ]
}
```

### Example 4: Create New Action Mapping

**Add at end of action_mappings array:**
```json
{
  "id": 65,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101051"]
    },
    {
      "action": "SendMail",
      "parameters": ["admin@example.com", "Motion detected"]
    }
  ]
}
```

## Common Action Types

### Video Motion Detection (VMD)
```json
{
  "action": "VMD_Start",
  "parameters": ["101050"]  // Camera ID
}
```

### Cross Switch (Switch Video to Monitor)
```json
{
  "action": "CrossSwitch",
  "parameters": ["101050", "3", "0"]  // Camera ID, Monitor, ???
}
```

### Send Email
```json
{
  "action": "SendMail",
  "parameters": ["user@example.com", "Alert message"]
}
```

### Viewer Connect Live
```json
{
  "action": "ViewerConnectLive",
  "parameters": ["101050"]  // Camera ID
}
```

### Digital Output Control
```json
{
  "action": "SetDigitalOutput",
  "parameters": ["1", "close"]  // Output number, state
}
```

### PTZ Camera Control
```json
{
  "action": "PanLeft",
  "parameters": []  // No parameters needed
}
```
```json
{
  "action": "GotoPreset",
  "parameters": ["5"]  // Preset number
}
```

## Current File Actions

Your current `action_mappings_clean.json` contains mostly **system messages** and **simple commands** without parameters:

- System messages: `"GSC warning: demo mode for 10 min"`
- Simple commands: `"GSC ViewerConnectLive V <- C"`
- PTZ controls: `"GSC PanLeft"`, `"GSC TiltUp"`, etc.

These are stored as:
```json
{
  "action": "GSC warning: demo mode for 10 min",
  "parameters": []
}
```

## Editing Workflow

### 1. Export
```bash
cd C:\DEV\COPILOT
python save_action_mappings.py
```

This creates `action_mappings_clean.json`

### 2. Edit the JSON

Open in any text editor and modify:

```json
{
  "action_mappings": [
    {
      "id": 1,
      "actions": [
        {
          "action": "VMD_Start",
          "parameters": ["101050"]  ← Edit camera ID
        }
      ]
    },
    {
      "id": 65,  ← Add new mapping
      "actions": [
        {
          "action": "CrossSwitch",
          "parameters": ["101050", "3", "0"]
        }
      ]
    }
  ]
}
```

### 3. Import Back

**Via REST API:**
```bash
curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d @action_mappings_clean.json \
     http://localhost:8000/api/v1/configuration/action-mappings/import
```

**Request body format:**
```json
{
  "actionMappings": [
    {
      "name": "Rules",
      "actions": [
        {
          "action": "VMD_Start",
          "parameters": ["101050"]
        }
      ]
    }
  ]
}
```

## Format Conversion

The system automatically converts between formats:

**Structured → Action String:**
- `{"action": "VMD_Start", "parameters": ["101050"]}` → `"VMD_Start(101050)"`
- `{"action": "CrossSwitch", "parameters": ["101050", "3", "0"]}` → `"CrossSwitch(101050, 3, 0)"`
- `{"action": "PanLeft", "parameters": []}` → `"PanLeft"`

**Action String → Structured:**
- `"VMD_Start(101050)"` → `{"action": "VMD_Start", "parameters": ["101050"]}`
- `"CrossSwitch(101050, 3, 0)"` → `{"action": "CrossSwitch", "parameters": ["101050", "3", "0"]}`
- `"GSC PanLeft"` → `{"action": "GSC PanLeft", "parameters": []}`

## Tips

1. **IDs are sequential** - They're just for reference, not stored in GeViSoft
2. **Parameters are strings** - Even numbers like "101050" are stored as strings
3. **Spacing doesn't matter** - The system strips whitespace from parameters
4. **Empty parameters** - Use `[]` for actions without parameters
5. **Validation** - The import endpoint will validate before writing to GeViSoft

## Quick Reference

| Action | Format | Example |
|--------|--------|---------|
| Start VMD | `VMD_Start(CameraID)` | `{"action": "VMD_Start", "parameters": ["101050"]}` |
| Cross Switch | `CrossSwitch(Camera, Monitor, Mode)` | `{"action": "CrossSwitch", "parameters": ["101050", "3", "0"]}` |
| Send Email | `SendMail(Email, Message)` | `{"action": "SendMail", "parameters": ["user@mail.com", "Alert"]}` |
| Set Output | `SetDigitalOutput(ID, State)` | `{"action": "SetDigitalOutput", "parameters": ["1", "close"]}` |
| PTZ Control | `PanLeft()` | `{"action": "PanLeft", "parameters": []}` |

## Next Steps

1. ✅ Export your current mappings (done - `action_mappings_clean.json`)
2. ⏭️ Study the format and plan your changes
3. ⏭️ Edit the JSON file to add/modify actions
4. ⏭️ Test import functionality
5. ⏭️ Verify in GeViSoft

---

**Status**: ✅ Ready to use
**File**: `action_mappings_clean.json`
**Format**: Structured (action + parameters)