Wiki source code of Status API
Last modified by Sean Hetherington on 2021/09/10 22:35
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{section}} | ||
| 2 | {{column}} | ||
| 3 | The iSymphony Status Interface allows users to query, set, and receive notices on extension user statuses, notes, and return times. | ||
| 4 | |||
| 5 | = Connecting = | ||
| 6 | |||
| 7 | To connect to the Status Interface simply make a TCP socket connection to port 50002 from an application or telnet. | ||
| 8 | The port can be configured in /opt/isymphony/server/config/extensions.xml by modifying the <StatusPort> tag. | ||
| 9 | Note that a port modification will not take effect until the iSymphony server process has been restarted. | ||
| 10 | The change will not take effect on application level reloads. All connections to the status interface will | ||
| 11 | remain open until the connection is closed by the connected client or the iSymphony server process has been stopped. | ||
| 12 | In versions 2.1.0 and lower connections can only be made from the machine that is running the iSymphony server process. The status port is bound to localhost for security. | ||
| 13 | {{/column}} | ||
| 14 | |||
| 15 | {{column width="300px"}} | ||
| 16 | {{panel}} | ||
| 17 | **//On this page~://** | ||
| 18 | |||
| 19 | |||
| 20 | |||
| 21 | {{toc maxLevel="2"/}} | ||
| 22 | {{/panel}} | ||
| 23 | {{/column}} | ||
| 24 | {{/section}} | ||
| 25 | |||
| 26 | = Special Identifiers = | ||
| 27 | |||
| 28 | Several special identifiers are sent and received by the Status Interface. It is crucial that these | ||
| 29 | identifiers are understood in order to work with the interface properly. | ||
| 30 | |||
| 31 | == Delimiter == | ||
| 32 | |||
| 33 | Many strings that the Status Interface deals with(i.e. location, tenant, extension, and status names)can | ||
| 34 | contain and number of allowable Unicode characters, so the interface utilizes an uncommon delimiter "@#" to separate | ||
| 35 | attributes in commands and events. It is crucial that you do not utilize this delimiter in any location | ||
| 36 | name, tenant name, extension number, status name or note if you are using the Status Interface. | ||
| 37 | |||
| 38 | == New Line == | ||
| 39 | |||
| 40 | Extension status notes can contain new lines. Since the Status Interface uses new lines to determine | ||
| 41 | the end of a command or the end of an event you must utilize the identifier "#masknl#" to include new | ||
| 42 | lines in the set_extension_note command if you would like newlines to be included in the note. | ||
| 43 | Any event or command reply will contain this identifier as well if reporting on a note that contains new lines. | ||
| 44 | |||
| 45 | = Errors = | ||
| 46 | |||
| 47 | Any command can throw an error. If an error occurs when running a command an error message will be | ||
| 48 | returned with a prefix of "Error:" instead of the normal return value and will be followed by a string | ||
| 49 | specifying the details of the error that was thrown. | ||
| 50 | |||
| 51 | = Commands = | ||
| 52 | |||
| 53 | Commands are used to query or set statuses, notes, and return times | ||
| 54 | |||
| 55 | {{panel}} | ||
| 56 | {{expand title="get_extension_state"}} | ||
| 57 | === Description === | ||
| 58 | |||
| 59 | Queries all extension statuses, notes, and return times for all extensions in the system. Note extensions with no return time set will have a value of "0" for <return time>. | ||
| 60 | |||
| 61 | === Usage === | ||
| 62 | |||
| 63 | get_extension_state | ||
| 64 | |||
| 65 | === Returns === | ||
| 66 | |||
| 67 | A list of all current set statuses, notes and return times for all extensions in the system grouped by location and tenant. | ||
| 68 | |||
| 69 | === Return Structure === | ||
| 70 | |||
| 71 | State Report Started | ||
| 72 | Location@#<location name> | ||
| 73 | Tenant@#<tenant name> | ||
| 74 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 75 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 76 | Tenant@#<tenant name> | ||
| 77 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 78 | Location@#<location name> | ||
| 79 | Tenant@#<tenant name> | ||
| 80 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 81 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 82 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 83 | Extension@#<extension number>@#<status name>@#<note>@#<return time> | ||
| 84 | State Report Finished | ||
| 85 | |||
| 86 | <location name> = name of location currently reporting on. | ||
| 87 | <tenant name> = name of tenant currently reporting on in current location. | ||
| 88 | <extension number> = extension number currently reporting on in current tenant. | ||
| 89 | <status name> = name of currently set status. | ||
| 90 | <note> = note currently set. | ||
| 91 | <return time> = return time currently set. Represented as a Unix time stamp in number of seconds since the Unix epoch. | ||
| 92 | {{/expand}} | ||
| 93 | |||
| 94 | {{expand title="get_statuses"}} | ||
| 95 | === (% style="line-height: 1.5625;" %)Description(%%) === | ||
| 96 | |||
| 97 | Queries all configured statuses in the system. | ||
| 98 | |||
| 99 | === Usage === | ||
| 100 | |||
| 101 | get_statuses | ||
| 102 | |||
| 103 | === Returns === | ||
| 104 | |||
| 105 | A list of all configured user statuses in the system grouped by location and tenant. | ||
| 106 | |||
| 107 | === Return Structure === | ||
| 108 | |||
| 109 | Status Report Started | ||
| 110 | Location@#<location name> | ||
| 111 | Tenant@#<tenant name> | ||
| 112 | Status@#<status name> | ||
| 113 | Status@#<status name> | ||
| 114 | Tenant@#<tenant name> | ||
| 115 | Status@<status name> | ||
| 116 | Location@#<location name> | ||
| 117 | Tenant@#<tenant name> | ||
| 118 | Status@<status name> | ||
| 119 | Status@<status name> | ||
| 120 | Status@<status name> | ||
| 121 | Status Report Finished | ||
| 122 | |||
| 123 | <location name> = name of location currently reporting on | ||
| 124 | <tenant name> = name of tenant currently reporting on in current location. | ||
| 125 | <status name> = name of status in current tenant. | ||
| 126 | {{/expand}} | ||
| 127 | |||
| 128 | {{expand title="get_extension_status"}} | ||
| 129 | Description: Queries the status of a given extension. | ||
| 130 | Usage: get_extension_status@#<location name>@#<tenant name>@#<extension number> | ||
| 131 | Returns: The currently set status for the specified extension. | ||
| 132 | Return Structure: ExtensionStatus@#<status name> | ||
| 133 | {{/expand}} | ||
| 134 | |||
| 135 | {{expand title="get_extension_note"}} | ||
| 136 | Description: Queries the note of a given extension. | ||
| 137 | Usage: get_extension_note@#<location name>@#<tenant name>@#<extension number> | ||
| 138 | Returns: The currently set note for the specified extension. | ||
| 139 | Return Structure: ExtensionNote@#<note> | ||
| 140 | {{/expand}} | ||
| 141 | |||
| 142 | {{expand title="get_extension_return_time"}} | ||
| 143 | Description: Queries the return time of a given extension. Note extensions with no return time set will have a value of "0" for <return time>. | ||
| 144 | Usage: get_extension_return_time@#<location name>@#<tenant name>@#<extension number> | ||
| 145 | Returns: The currently set return time for the specified extension. Represented as a Unix time stamp in number of seconds since the Unix epoch. | ||
| 146 | Return Structure: ExtensionReturnTime@#<return time> | ||
| 147 | {{/expand}} | ||
| 148 | |||
| 149 | {{expand title="set_extension_status"}} | ||
| 150 | Description: Sets the status of a given extension. | ||
| 151 | Usage: set_extension_status@#<location name>@#<tenant name>@#<extension number>@#<status name> | ||
| 152 | Returns: new line | ||
| 153 | {{/expand}} | ||
| 154 | |||
| 155 | {{expand title="set_extension_note"}} | ||
| 156 | Description: Sets the note of a given extension. | ||
| 157 | Usage: set_extension_note@#<location name>@#<tenant name>@#<extension number>@#<note> | ||
| 158 | Returns: new line | ||
| 159 | {{/expand}} | ||
| 160 | |||
| 161 | {{expand title="set_extension_return_time"}} | ||
| 162 | Description: Sets the return time of a given extension. <return time> is represented as a Unix time stamp in number of seconds since the Unix epoch. To have no return time set specify "0" as <return time>. | ||
| 163 | Usage: set_extension_return_time@#<location name>@#<tenant name>@#<extension number>@#<return time> | ||
| 164 | Returns: new line | ||
| 165 | {{/expand}} | ||
| 166 | |||
| 167 | {{expand title="exit"}} | ||
| 168 | Description: Closes the Status Interface connection. | ||
| 169 | Usage: exit | ||
| 170 | Returns: nothing | ||
| 171 | {{/expand}} | ||
| 172 | {{/panel}} | ||
| 173 | |||
| 174 | (% style="color: rgb(0,0,0);font-size: 24.0px;line-height: 1.25;" %)Events | ||
| 175 | |||
| 176 | Events specify notifications of changes made to an extension's status, note, and return time as well as additions, removals, and name modifications of locations, tenants, extensions, and statuses so that users can keep the client side model current. | ||
| 177 | |||
| 178 | ExtensionStatusUpdatedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 179 | Description: Notification of an extension's status changing. | ||
| 180 | Structure: ExtensionStatusUpdatedEvent@#<location name>@#<tenant name>@#<extension number>@#<status name> | ||
| 181 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 182 | |||
| 183 | ExtensionNoteUpdatedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 184 | Description: Notification of an extension's note changing. | ||
| 185 | Structure: ExtensionNoteUpdatedEvent@#<location name>@#<tenant name>@#<extension number>@#<note> | ||
| 186 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 187 | |||
| 188 | ExtensionReturnTimeUpdatedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 189 | Description: Notification of an extension's return time changing. Represented as a Unix time stamp in number of seconds since the Unix epoch. | ||
| 190 | Structure: ExtensionReturnTimeUpdatedEvent@#<location name>@#<tenant name>@#<extension number>@#<return time> | ||
| 191 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 192 | |||
| 193 | StatusAddedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 194 | Description: Notification of a new status being added to the system. | ||
| 195 | Structure: StatusAddedEvent@#<location name>@#<tenant name>@#<status name> | ||
| 196 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 197 | |||
| 198 | StatusRemovedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 199 | Description: Notification of a status being removed from the system. | ||
| 200 | Structure: StatusRemovedEvent@#<location name>@#<tenant name>@#<status name> | ||
| 201 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 202 | |||
| 203 | StatusRenameEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 204 | Description: Notification of a status being renamed. | ||
| 205 | Structure: StatusRenameEvent@#<location name>@#<tenant name>@#<old status name>@#<new status name> | ||
| 206 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 207 | |||
| 208 | LocationAddedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 209 | Description: Notification of a new location being added to the system. | ||
| 210 | Structure: LocationAddedEvent@#<location name> | ||
| 211 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 212 | |||
| 213 | LocationRemovedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 214 | Description: Notification of a location being removed from the system. | ||
| 215 | Structure: LocationRemovedEvent@#<location name> | ||
| 216 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 217 | |||
| 218 | LocationRenamedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 219 | Description: Notification of a location being renamed. | ||
| 220 | Structure: LocationRenamedEvent@#<old location name>@#<new location name> | ||
| 221 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 222 | |||
| 223 | TenantAddedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 224 | Description: Notification of a new tenant being added to the system. | ||
| 225 | Structure: TenantAddedEvent@#<location name>@#<tenant name> | ||
| 226 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 227 | |||
| 228 | TenantRemovedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 229 | Description: Notification of a tenant being removed from the system. | ||
| 230 | Structure: TenantRemovedEvent@#<location name>@#<tenant name> | ||
| 231 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 232 | |||
| 233 | TenantRenamedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 234 | Description: Notification of a tenant being renamed. | ||
| 235 | Structure: TenantRenamedEvent@#<location name>@#<old tenant name>@#<new tenant name> | ||
| 236 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 237 | |||
| 238 | ExtensionAddedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 239 | Description: Notification of a new extension being added to the system. Note that a new extension will not fire any status events except for this one. Extensions added to the system will default to "Available" status, a blank note, and "0" for return time. | ||
| 240 | Structure: ExtensionAddedEvent@#<location name>@#<tenant name>@#<extension name> | ||
| 241 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 242 | |||
| 243 | ExtensionRemovedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 244 | Description: Notification of a extension being removed from the system. | ||
| 245 | Structure: ExtensionRemovedEvent@#<location name>@#<tenant name>@#<extension name> | ||
| 246 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 247 | |||
| 248 | ExtensionRenamedEvent~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~- | ||
| 249 | Description: Notification of a extension being re-numbered. | ||
| 250 | Structure: ExtensionRenamedEvent@#<location name>@#<tenant name>@#<old extension number>@#<new extension number> | ||
| 251 | ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-- | ||
| 252 | |||
| 253 |