Description

The iSymphony Status Interface allows users to query, set, and receive notices on extension user statuses, notes, and return times.

Connecting

To connect to the Status Interface simply make a TCP socket connection to port 50002 from an application or telnet.
The port can be configured in /opt/isymphony/server/config/extensions.xml by modifying the <StatusPort> tag.
Note that a port modification will not take effect until the iSymphony server process has been restarted.
The change will not take effect on application level reloads. All connections to the status interface will
remain open until the connection is closed by the connected client or the iSymphony server process has been stopped.
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.

Special Identifiers

Several special identifiers are sent and received by the Status Interface. It is crucial that these
identifiers are understood in order to work with the interface properly.

-Delimiter
Many strings that the Status Interface deals with(i.e. location, tenant, extension, and status names)can
contain and number of allowable Unicode characters, so the interface utilizes an uncommon delimiter "@#" to separate
attributes in commands and events. It is crucial that you do not utilize this delimiter in any location
name, tenant name, extension number, status name or note if you are using the Status Interface.

-New Line
Extension status notes can contain new lines. Since the Status Interface uses new lines to determine
the end of a command or the end of an event you must utilize the identifier "#masknl#" to include new
lines in the set_extension_note command if you would like newlines to be included in the note.
Any event or command reply will contain this identifier as well if reporting on a note that contains new lines.

Errors

Any command can throw an error. If an error occurs when running a command an error message will be
returned with a prefix of "Error:" instead of the normal return value and will be followed by a string
specifying the details of the error that was thrown.

Commands

Commands are used to query or set statuses, notes, and return times

get_extension_state----------------------------------------
Description: 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>.
Usage: get_extension_state
Returns: a list of all current set statuses, notes and return times for all extensions in the system grouped by location and tenant.
Return Structure:

State Report Started
Location@#<location name>
Tenant@#<tenant name>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
Tenant@#<tenant name>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
Location@#<location name>
Tenant@#<tenant name>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
Extension@#<extension number>@#<status name>@#<note>@#<return time>
State Report Finished

<location name> = name of location currently reporting on.
<tenant name> = name of tenant currently reporting on in current location.
<extension number> = extension number currently reporting on in current tenant.
<status name> = name of currently set status.
<note> = note currently set.
<return time> = return time currently set. Represented as a Unix time stamp in number of seconds since the Unix epoch.
-----------------------------------------------------------

get_statuses-----------------------------------------------
Description: Queries all configured statuses in the system.
Usage: get_statuses
Returns: a list of all configured user statuses in the system grouped by location and tenant.
Return Structure:

Status Report Started
Location@#<location name>
Tenant@#<tenant name>
Status@#<status name>
Status@#<status name>
Tenant@#<tenant name>
Status@<status name>
Location@#<location name>
Tenant@#<tenant name>
Status@<status name>
Status@<status name>
Status@<status name>
Status Report Finished

<location name> = name of location currently reporting on
<tenant name> = name of tenant currently reporting on in current location.
<status name> = name of status in current tenant.
-----------------------------------------------------------

get_extension_status---------------------------------------
Description: Queries the status of a given extension.
Usage: get_extension_status@#<location name>@#<tenant name>@#<extension number>
Returns: The currently set status for the specified extension.
Return Structure: ExtensionStatus@#<status name>
-----------------------------------------------------------

get_extension_note-----------------------------------------
Description: Queries the note of a given extension.
Usage: get_extension_note@#<location name>@#<tenant name>@#<extension number>
Returns: The currently set note for the specified extension.
Return Structure: ExtensionNote@#<note>
-----------------------------------------------------------

get_extension_return_time----------------------------------
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>.
Usage: get_extension_return_time@#<location name>@#<tenant name>@#<extension number>
Returns: The currently set return time for the specified extension. Represented as a Unix time stamp in number of seconds since the Unix epoch.
Return Structure: ExtensionReturnTime@#<return time>
-----------------------------------------------------------

set_extension_status---------------------------------------
Description: Sets the status of a given extension.
Usage: set_extension_status@#<location name>@#<tenant name>@#<extension number>@#<status name>
Returns: new line
-----------------------------------------------------------

set_extension_note-----------------------------------------
Description: Sets the note of a given extension.
Usage: set_extension_note@#<location name>@#<tenant name>@#<extension number>@#<note>
Returns: new line
-----------------------------------------------------------

set_extension_return_time----------------------------------
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>.
Usage: set_extension_return_time@#<location name>@#<tenant name>@#<extension number>@#<return time>
Returns: new line
-----------------------------------------------------------

exit-------------------------------------------------------
Description: Closes the Status Interface connection.
Usage: exit
Returns: nothing
-----------------------------------------------------------

Events:
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.

ExtensionStatusUpdatedEvent--------------------------------
Description: Notification of an extension's status changing.
Structure: ExtensionStatusUpdatedEvent@#<location name>@#<tenant name>@#<extension number>@#<status name>
-----------------------------------------------------------

ExtensionNoteUpdatedEvent----------------------------------
Description: Notification of an extension's note changing.
Structure: ExtensionNoteUpdatedEvent@#<location name>@#<tenant name>@#<extension number>@#<note>
-----------------------------------------------------------

ExtensionReturnTimeUpdatedEvent----------------------------
Description: Notification of an extension's return time changing. Represented as a Unix time stamp in number of seconds since the Unix epoch.
Structure: ExtensionReturnTimeUpdatedEvent@#<location name>@#<tenant name>@#<extension number>@#<return time>
-----------------------------------------------------------

StatusAddedEvent-------------------------------------------
Description: Notification of a new status being added to the system.
Structure: StatusAddedEvent@#<location name>@#<tenant name>@#<status name>
-----------------------------------------------------------

StatusRemovedEvent-----------------------------------------
Description: Notification of a status being removed from the system.
Structure: StatusRemovedEvent@#<location name>@#<tenant name>@#<status name>
-----------------------------------------------------------

StatusRenameEvent------------------------------------------
Description: Notification of a status being renamed.
Structure: StatusRenameEvent@#<location name>@#<tenant name>@#<old status name>@#<new status name>
-----------------------------------------------------------

LocationAddedEvent-----------------------------------------
Description: Notification of a new location being added to the system.
Structure: LocationAddedEvent@#<location name>
-----------------------------------------------------------

LocationRemovedEvent---------------------------------------
Description: Notification of a location being removed from the system.
Structure: LocationRemovedEvent@#<location name>
-----------------------------------------------------------

LocationRenamedEvent---------------------------------------
Description: Notification of a location being renamed.
Structure: LocationRenamedEvent@#<old location name>@#<new location name>
-----------------------------------------------------------

TenantAddedEvent-------------------------------------------
Description: Notification of a new tenant being added to the system.
Structure: TenantAddedEvent@#<location name>@#<tenant name>
-----------------------------------------------------------

TenantRemovedEvent-----------------------------------------
Description: Notification of a tenant being removed from the system.
Structure: TenantRemovedEvent@#<location name>@#<tenant name>
-----------------------------------------------------------

TenantRenamedEvent-----------------------------------------
Description: Notification of a tenant being renamed.
Structure: TenantRenamedEvent@#<location name>@#<old tenant name>@#<new tenant name>
-----------------------------------------------------------

ExtensionAddedEvent----------------------------------------
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.
Structure: ExtensionAddedEvent@#<location name>@#<tenant name>@#<extension name>
-----------------------------------------------------------

ExtensionRemovedEvent--------------------------------------
Description: Notification of a extension being removed from the system.
Structure: ExtensionRemovedEvent@#<location name>@#<tenant name>@#<extension name>
-----------------------------------------------------------

ExtensionRenamedEvent--------------------------------------
Description: Notification of a extension being re-numbered.
Structure: ExtensionRenamedEvent@#<location name>@#<tenant name>@#<old extension number>@#<new extension number>
-----------------------------------------------------------