Polisy Developers:ISY:API:System Editors

From Universal Devices, Inc. Wiki


Polisy_Developers : ISY : API : System Editors

System Editors

System editors are editors supplied by and maintained by the ISY.

(first available in Polisy 5.4.2)

Summary

  • In the GUI, system editors act the same as other editors
  • All system editors have an id with a prefix of _sys_
  • System editors are only allowed on command parameters (not status)

REST API

Unless otherwise specified, all REST commands use HTTP GET method.

See REST return codes

Notes:

  • URL Prefix: /rest

/system/editors[/<editorId>]

Returns all System Editors, or just the single specified System Editor.

editorId The name of the system editor, or omit to return all system editors
e.g.
/rest/system/editors
/rest/system/editors/_sys_notify_short

Output 

<editors>
   <editor id="_sys_notify_short">
      <range min="1" max="5" step="1" prec="0" uom="146">
         <nls>
            <e id="1">Kitchen lights</e>
            <e id="2">Back door is open</e>
            <e id="3">Motion in front yard</e>
            <e id="4">Car is charging</e>
            <e id="5">Alarm is on</e>
         </nls>
      </range>
   </editor>
   <editor id="_sys_notify_full">
      <range min="1" max="5" step="1" prec="0" uom="148">
         <nls>
            <e id="1">Kitchen lights</e>
            <e id="2">Back door is open</e>
            <e id="3">Motion in front yard</e>
            <e id="4">Car is charging</e>
            <e id="5">Alarm is on</e>
         </nls>
      </range>
   </editor>
</editors>
editor id The name of the system editor
range The set of values supported by this system editor
nls The list of name value pairs for this range
e id The id is the range value

Events

Whenever the content for a system editor changes, the ISY will send out the following event indicating which system editor changed. 

<Event SEQNUM="15" SID="uuid:33">
   <control>_24</control>
   <action>1</action>
   <node>_sys_notify_short</node>
   <eventInfo/>
</Event>
_sys_notify_short
Content changes whenever the custom notifications change in the ISY.
_sys_notify_full
Content changes whenever the custom notifications change in the ISY.


Supported System Editors

_sys_notify_short

The _sys_notify_short system editor provides the list of user created custom notifications.

When a command with a parameter using the _sys_notify_short system editor is submitted to the ISY, the custom notification it specifies is formatted by the ISY into a string as follows:

  • If there is a subject in the notification then only the subject is used
  • If there is no subject then the body is used
  • Maximum of 80 characters are returned

The resulting string is then used as the command parameter rather than the ID of the custom notification.

e.g.

If ISY receives the following command with a parameter using _sys_notify_short. 

  /rest/nodes/n015_t1/cmd/SHOW?GV1.uom146=2
   
  Note the UOM being used is the one reserved for this system editor.

Then the ISY finds notification id=2, formats it, and sends the resulting string as follows to the node server. 

  /n15/nodes/n015_t1/cmd/SHOW?GV1.uom145=Hello%20World
   
  Note the UOM changed to 145 (Text)

Could also be in this format (unnamed parameter) 

  /rest/nodes/n015_t1/cmd/SHOW/2/146
  /n15/nodes/n015_t1/cmd/SHOW/Hello%20World/145

_sys_notify_full

(introduced in version 5.6.1)

The _sys_notify_full system editor provides the list of user created custom notifications.

Command parameters using the _sys_notify_full system editor cause the ISY to format the specified notification into XML with subject, body, from, and mimetype tags.

The resulting XML is then used as the command parameter value rather than the ID of the custom notification.

e.g.

If ISY receives the following command with a parameter using _sys_notify_full. 

  /rest/nodes/n015_t1/cmd/SHOW?NOTIFY.uom148=3
   
  Note the UOM being used is the one reserved for this system editor.

Then the ISY finds notification id=3 and formats it into XML. Rather than sending a GET request to the node server as is normally done, the entire command is converted to XML and sent to the node server using POST. 

POST /n15/nodes/n015_t1/cmd
..header..

<cmd id="SHOW" requestId="5">
   <p id="NOTIFY">
      <val uom="147">
         <![CDATA[<notification id="3"><formatted><mimetype>text/plain</mimetype><from>My Notifications</from><subject>Kitchen Motion Sensor</subject><body>The kitchen motion sensor has been triggered &lt; 10 times today.</body></formatted></notification>]]>
      </val>
   </p>
</cmd>
 
Note the UOM changed to 147 (XML)
Retrieved from "https://wiki.universal-devices.com/index.php?title=Polisy_Developers:ISY:API:System_Editors&oldid=9277"