Skip to Content
Version 21.1 by michaely on 2015/07/14 10:29
Show last authors
1 {{layout}}
2 {{layout-section ac:type="two_right_sidebar"}}
3 {{layout-cell}}
4 {{info}}
5 The information on this page applies to **iSymphony 3.2+**.
6 {{/info}}
7
8 = (% style="color: rgb(0,0,0);" %)Description(%%) =
9
10 The websocket API provides realtime events about the current state of the iSymphony server. External applications can utilize this API to integrate with the iSymphony server, by reacting to events pertaining to users, and call state. In conjunction with the CRM widget, this API can also be utilized to create custom widgets for the iSymphony client interface.
11 {{/layout-cell}}
12
13 {{layout-cell}}
14 {{panel title="On this page:"}}
15
16
17 {{toc maxLevel="2" indent="1"/}}
18 {{/panel}}
19 {{/layout-cell}}
20 {{/layout-section}}
21
22 {{layout-section ac:type="single"}}
23 {{layout-cell}}
24
25
26 = Connecting To The Websocket =
27
28 The following URL can be used to connect to the websocket event API:
29
30 {{code}}
31 ws://manager:manag3rpa55word@<hostname or ip of the iSymphony server>:58080/communication_manager/ws/event
32 {{/code}}
33
34 = Security =
35
36 By default the Event API websocket will be restricted via HTTP Realm Auth and ACLs. The default credentials will be set to **manager:manag3rpa55word**, and the ACLs will be set up to only allow connections from **localhost**. You can also secure the connection further with SSL encryption. See [[doc:ISYMDOCS.Security]] for more information.
37
38 {{info}}
39 When securing the API with SSL, the URL used to connect to the Event API websocket must use **wss and port 55050**, instead of ws and port 58080.
40 {{/info}}
41
42 = JSON =
43
44 All messages sent to or from the Event API websocket must be in JSON format. Each event will contain a set of properties providing details of the event. Each event documentation page will specify the JSON representation, and properties, of the event.
45
46 {{info}}
47 Properties in the event JSON representation will be in alphabetical order, however you should not rely on the property order.
48 {{/info}}
49
50
51
52 Below is an example of an event that will be generated, when a user logs into the client interface:
53
54 {{code language="js"}}
55 {
56 "coreServerId": "e5c01703-3c6d-429a-8712-66c826064e65",
57 "port": 57042,
58 "ip": "127.0.0.1",
59 "time": 1436889915953,
60 "type": "userLogin",
61 "userId": "e7577c7b-5d58-46a5-a834-386f52401c19",
62 "userLoginId": "0c51236d-5f93-4379-8997-8a840a511497",
63 "username": "mike"
64 }
65 {{/code}}
66
67 == Base Event Properties ==
68
69 Every event will contain the following two properties:
70
71 * **type** : Describes the type of event.
72 * **time** : Specifies the date/time the event was generated. Represented as a unix timestamp, in milliseconds.
73
74 = Object IDs =
75
76 Most events generated by the event API will contain UUIDs that can be used to identify objects the event relates to. Some events will reference multiple ids. These UUIDs are the same ids that are used to reference resources in the [[Live REST API>>doc:Live API]], allowing collaboration between the Live REST API and the Event API.
77
78 {{note}}
79 The UUIDs do not persist across restarts of the iSymphony server. If the server is restarted, the objects will contain new UUIDs. Also, if an object is destroyed then re-added, even with the same configuration, the UUID that represents that object will be different from the original.
80 {{/note}}
81
82 = (% style="color: rgb(0,0,0);" %)Event Filtering(%%) =
83
84 The Event API allows connections to specify which events they want to receive from the websocket, by specifying property filters.
85
86 {{info}}
87 **Filters specify which events to filter in**, not filter out.
88 {{/info}}
89
90 == The Filter Message ==
91
92 A message, with the following format, can be sent to the websocket, in order to set the current filters for the connection.
93
94 {{code language="js"}}
95 {
96 "type" : "filter",
97 "filters" : [
98 {"property" : "<property name>" : "value" : "<filter value>"},
99 {"property" : "<property name>" : "value" : "<filter value>"},
100 ...
101 ]
102 }
103 {{/code}}
104
105 Where <property name> is the name of the property to filter, and <filter value> is the property value to filter on. Multiple property filters can be specified.
106
107
108
109 {{info}}
110 If an event does not contain a property specified in one of the filters, the event will not be received.
111 {{/info}}
112
113 {{info}}
114 Sending a filter message will clear any previously set filters.
115 {{/info}}
116
117 {{info}}
118 By default all events will be allowed through the websocket.
119 {{/info}}
120
121 == (% style="color: rgb(0,0,0);" %)Filter Message Response(%%) ==
122
123 When a filter message is sent, the websocket will respond with one of the following messages:
124
125 === Success Message ===
126
127 Returned when the filter was properly applied.
128
129 {{code language="js"}}
130 {
131 "correlationId": null,
132 "time": 1436889163971,
133 "type": "success"
134 }
135 {{/code}}
136
137 === Error Message ===
138
139 Returned when an error occurred while processing the filter message.
140
141 {{code language="js"}}
142 {
143 "correlationId": null,
144 "error": "<error message>",
145 "time": 1436889377766,
146 "type": "error"
147 }
148 {{/code}}
149
150 The error property will contain the details of the error that occurred.
151
152 == Correlation ID ==
153
154 You can specify a correlation id in the filter message, in order to tie the filter message to the generated response message. The correlation id is optional, and can be any unique string. Randomly generated numbers, or UUIDs, are a good choice for correlation ids.
155
156 {{code language="js"}}
157 {
158 "type" : "filter",
159 "correlationId" : "123456",
160 "filters" : [
161 {"property" : "type" : "value" : "dial"}
162 ]
163 }
164 {{/code}}
165
166 The filter message above will respond with the following message:
167
168 {{code}}
169 {
170 "correlationId": "123456",
171 "time": 1436889163971,
172 "type": "success"
173 }
174 {{/code}}
175
176 == (% style="color: rgb(0,0,0);" %)Wildcard(%%) ==
177
178 If you specify a value of **"*"** for a filter property value, the property filter will match on any value of the property. This can be used to specify that you wish to receive events that contain a specific property, but the value of the property does not matter.
179
180 == Examples ==
181
182 The following filter will only allow events of type dial:
183
184 {{code language="js"}}
185 {
186 "type" : "filter",
187 "filters" : [
188 {"property" : "type" : "value" : "dial"}
189 ]
190 }
191 {{/code}}
192
193 The following filter will only allow events of type userLogin and userLogout:
194
195 {{code language="js"}}
196 {
197 "type" : "filter",
198 "filters" : [
199 {"property" : "type" : "value" : "userLogin"},
200 {"property" : "type" : "value" : "userLogout"}
201 ]
202 }
203 {{/code}}
204
205 The following filter will only allow events of type userLogin and userLogout, on a user with username mike.
206
207 {{code language="js"}}
208 {
209 "type" : "filter",
210 "filters" : [
211 {"property" : "type" : "value" : "userLogin"},
212 {"property" : "type" : "value" : "userLogout"},
213 {"property" : "username" : "value" : "mike"}
214 ]
215 }
216 {{/code}}
217
218 The following filter will only allow events that reference a user (i.e. contains the username property):
219
220 {{code language="js"}}
221 {
222 "type" : "filter",
223 "filters" : [
224 {"property" : "username" : "value" : "*"}
225 ]
226 }
227 {{/code}}
228
229 = REST Resources =
230
231 The Live API exposes several REST resources, that allow access to the current state of specific objects in the system. All current live resources are listed below. Details concerning each resource, and their actions, can be found within the individual resource documentation pages.
232
233 == Resource List ==
234
235
236
237 {{children/}}
238
239 == Notes on Resource Documentation ==
240
241 Due to the interdependent nature of resources in the system, the resource path information in the documentation is split into several sections. Paths in a specific section may relate to, or require, paths specified in other sections.
242
243 * **Root Resource Paths : **Specifies paths that can be used to access sets (multiple instances) of a resource, in relation to a parent resource.
244 * **Instance Resource Paths : **Specifies paths that can be used to access a specific instance of a resource. These paths require a **Root Resource Path**, in most cases, but not all.
245 * **Sub Resource Paths : **Specifies paths that provide access to the child resources, of a specific resource instance. These paths require an **Instance Resource Path.**
246 * **Action Paths: **Specifies paths that are used to perform actions on a specific resource instance. These paths require an **Instance Resource Path.**
247
248 \\
249 {{/layout-cell}}
250 {{/layout-section}}
251 {{/layout}}