ModifyUserData

Revision as of 13:28, 11 June 2015

ModifyUserData is the action used to change information like adding rooms, renaming devices, scenes and so on.

It works as a UPNP POST request to http://IP/port_49451/upnp/control/hag which contains an XML envelope:

 <s:envelope s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
	<s:body>	
	<u:modifyuserdata xmlns:u="urn:schemas-micasaverde-org:service:HomeAutomationGateway:1">		
	<inuserdata>{"devices": {    
  },
  "scenes": {
    "scenes_1000001": {
      "id": 1000001,
      "name": "New scene",
      "posx": 0,
      "posy": 0,
      "room": 0
    }
  },
  "sections": {    
  },
  "rooms": [    
  ],
  "users": {    
  }
  }</inuserdata>		
  		<dataformat>json</dataformat>  
	</u:modifyuserdata>
	</s:body>
  </s:envelope>

The objects from the JSON object are added if they contain the tag "json_action": "add", deleted if they contain "json_action": "del" or merged if neither one of those is contained (default action).

For example, assume that the data is currently like this:

 "Room": {
       "PK_Room_1": {
           "Description": "Living Room",
           "FK_Section": "1" 
       },
       "PK_Room_2": {
           "Description": "Bedroom",
           "FK_Section": "1" 
       } 

You want to remove the bedroom and add a new room called "Den" and change the Living Room to be called Kitchen. You put the following in the parm post:

{

   "Room": {
       "PK_Room_2": {
           "json_action": "del" 
       },
       "PK_Room_1": {
           "Description": "Kitchen",
       },
       "PK_Room_1000002": {
           "Description": "Den",
           "FK_Section": "1",
           "json_action": "add" 
       } 
   }

}

Note that Sections, Rooms, Devices, and Scenes are all numbered: PK_Room_1, scene_2, etc. When are adding new Sections, Rooms, Devices, and Scenes, use a number that is very high (> 1,000,000) to prevent conflicts. Note that Room uses a really large ID. You don't want to use the next available ID, like 3, because that might already have been created by another user, and, since the ID # is the key to merging, your new room would be preserved and there would be 2 room 3's if json_action=add, or your changes would be merged and overwrite room 3 otherwise. When you use large id's > 1m, then on save, the system automatically re-numbers them and re-outputs the renumbered result. This includes relationships as well. So if you are submitting a new scene, device, room, etc., the device may be id 1m, and reference room 2, so it goes into room 2, and a new device id 1m + 1 may reference room 1m. In this case both device id's would be renumbered, and the room 1m would be renumbered, and the reference in the device id 1m + 1 would be changed to reflect this.

If ModifyUserData fails, it return an UPNP error.