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):

{
  "id": 1,
  "actions": ["VMD_Start(101050)", "CrossSwitch(101050, 3, 0)"]
}

After (Structured with action + parameters):

{
  "id": 1,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    },
    {
      "action": "CrossSwitch",
      "parameters": ["101050", "3", "0"]
    }
  ]
}

How to Edit

Example 1: Change Parameters

Original:

{
  "id": 10,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    }
  ]
}

Edit camera ID from 101050 to 101027:

{
  "id": 10,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101027"]  ← Changed
    }
  ]
}

Example 2: Add Parameters to Action

Original:

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

Add camera parameter:

{
  "id": 5,
  "actions": [
    {
      "action": "ViewerConnectLive",
      "parameters": ["101050", "1"]  ← Added parameters
    }
  ]
}

Example 3: Add Multiple Actions to One Mapping

Original:

{
  "id": 15,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101050"]
    }
  ]
}

Add CrossSwitch action:

{
  "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:

{
  "id": 65,
  "actions": [
    {
      "action": "VMD_Start",
      "parameters": ["101051"]
    },
    {
      "action": "SendMail",
      "parameters": ["admin@example.com", "Motion detected"]
    }
  ]
}

Common Action Types

Video Motion Detection (VMD)

{
  "action": "VMD_Start",
  "parameters": ["101050"]  // Camera ID
}

Cross Switch (Switch Video to Monitor)

{
  "action": "CrossSwitch",
  "parameters": ["101050", "3", "0"]  // Camera ID, Monitor, ???
}

Send Email

{
  "action": "SendMail",
  "parameters": ["user@example.com", "Alert message"]
}

Viewer Connect Live

{
  "action": "ViewerConnectLive",
  "parameters": ["101050"]  // Camera ID
}

Digital Output Control

{
  "action": "SetDigitalOutput",
  "parameters": ["1", "close"]  // Output number, state
}

PTZ Camera Control

{
  "action": "PanLeft",
  "parameters": []  // No parameters needed
}

{
  "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:

{
  "action": "GSC warning: demo mode for 10 min",
  "parameters": []
}

Editing Workflow

1. Export

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:

{
  "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:

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:

{
  "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)