Wiki source code of WebSocket API Documentation (Event)
Last modified by michaely on 2021/09/10 23:34
Show last authors
author | version | line-number | content |
---|---|---|---|
1 | {{layout}} | ||
2 | {{layout-section ac:type="two_right_sidebar"}} | ||
3 | {{layout-cell}} | ||
4 | {{warning}} | ||
5 | This page is currently being written. Although the information below is probably accurate, it may not be complete or may have errors. | ||
6 | {{/warning}} | ||
7 | |||
8 | {{info}} | ||
9 | The information on this page applies to **iSymphony 3.2+**. | ||
10 | {{/info}} | ||
11 | |||
12 | = (% style="color: rgb(0,0,0);" %)Description(%%) = | ||
13 | |||
14 | The WebSocket API provides realtime events pertaining to the current state of the iSymphony server. External applications can utilize this API to integrate with the iSymphony server, by reacting to events related 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. | ||
15 | {{/layout-cell}} | ||
16 | |||
17 | {{layout-cell}} | ||
18 | {{panel title="On this page:"}} | ||
19 | |||
20 | |||
21 | {{toc maxLevel="2" indent="1"/}} | ||
22 | {{/panel}} | ||
23 | {{/layout-cell}} | ||
24 | {{/layout-section}} | ||
25 | |||
26 | {{layout-section ac:type="single"}} | ||
27 | {{layout-cell}} | ||
28 | |||
29 | |||
30 | = Connecting To The WebSocket = | ||
31 | |||
32 | The following URL can be used to connect to the WebSocket event API: | ||
33 | |||
34 | {{code}} | ||
35 | ws://manager:manag3rpa55word@<hostname or ip of the iSymphony server>:58080/communication_manager/ws/event | ||
36 | {{/code}} | ||
37 | |||
38 | = Security = | ||
39 | |||
40 | 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. | ||
41 | |||
42 | {{info}} | ||
43 | 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. | ||
44 | {{/info}} | ||
45 | |||
46 | = JSON = | ||
47 | |||
48 | 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. | ||
49 | |||
50 | Below is an example of an event that will be generated, when a user logs into the client interface: | ||
51 | |||
52 | {{code language="js"}} | ||
53 | { | ||
54 | "type": "userLogin", | ||
55 | "time": 1436889915953, | ||
56 | "coreServerId": "e5c01703-3c6d-429a-8712-66c826064e65", | ||
57 | "username": "mike", | ||
58 | "userId": "e7577c7b-5d58-46a5-a834-386f52401c19", | ||
59 | "userLoginId": "0c51236d-5f93-4379-8997-8a840a511497", | ||
60 | "port": 57042, | ||
61 | "ip": "127.0.0.1" | ||
62 | } | ||
63 | {{/code}} | ||
64 | |||
65 | == Base Event Properties == | ||
66 | |||
67 | Every event will contain the following properties: | ||
68 | |||
69 | * **type** : Describes the type of event. | ||
70 | * **time** : Specifies the date/time the event was generated. Represented as a unix timestamp, in milliseconds. | ||
71 | * **coreServerId** : Specifies the id of the core server that fired the event. | ||
72 | |||
73 | = Object IDs = | ||
74 | |||
75 | 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. | ||
76 | |||
77 | {{note}} | ||
78 | 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. | ||
79 | {{/note}} | ||
80 | |||
81 | = (% style="color: rgb(0,0,0);" %)Event Filtering(%%) = | ||
82 | |||
83 | The Event API allows connections to specify which events they want to receive from the WebSocket, by specifying property filters. | ||
84 | |||
85 | {{info}} | ||
86 | **Filters specify which events to filter in**, not filter out. | ||
87 | {{/info}} | ||
88 | |||
89 | == The Filter Message == | ||
90 | |||
91 | A message, with the following format, can be sent to the WebSocket, in order to set the current filters for the connection. | ||
92 | |||
93 | {{code language="js"}} | ||
94 | { | ||
95 | "type" : "filter", | ||
96 | "filters" : [ | ||
97 | {"property" : "<property name>", "value" : "<filter value>"}, | ||
98 | {"property" : "<property name>", "value" : "<filter value>"}, | ||
99 | ... | ||
100 | ] | ||
101 | } | ||
102 | {{/code}} | ||
103 | |||
104 | Where <property name> is the name of the property to filter on, and <filter value> is the property value to filter on. Multiple property filters can be specified. | ||
105 | |||
106 | |||
107 | |||
108 | {{info}} | ||
109 | If an event does not contain a property specified in one of the filters, the event will not be received. | ||
110 | {{/info}} | ||
111 | |||
112 | {{info}} | ||
113 | Sending a filter message will clear any previously set filters. | ||
114 | {{/info}} | ||
115 | |||
116 | {{info}} | ||
117 | By default all events will be received, until a filter is specified. | ||
118 | {{/info}} | ||
119 | |||
120 | == (% style="color: rgb(0,0,0);" %)Filter Message Response(%%) == | ||
121 | |||
122 | When a filter message is sent, the WebSocket will respond with one of the following messages: | ||
123 | |||
124 | === Success Message === | ||
125 | |||
126 | Returned when the filter was properly applied. | ||
127 | |||
128 | {{code language="js"}} | ||
129 | { | ||
130 | "type": "success", | ||
131 | "time": 1436889163971, | ||
132 | "correlationId": null | ||
133 | } | ||
134 | {{/code}} | ||
135 | |||
136 | === Error Message === | ||
137 | |||
138 | Returned when an error occurred while processing the filter message. | ||
139 | |||
140 | {{code language="js"}} | ||
141 | { | ||
142 | "type": "error", | ||
143 | "time": 1436889377766, | ||
144 | "error": "<error message>", | ||
145 | "correlationId": null | ||
146 | } | ||
147 | {{/code}} | ||
148 | |||
149 | The error property will contain the details of the error that occurred. | ||
150 | |||
151 | == Correlation ID == | ||
152 | |||
153 | 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. | ||
154 | |||
155 | {{code language="js"}} | ||
156 | { | ||
157 | "type" : "filter", | ||
158 | "correlationId" : "123456", | ||
159 | "filters" : [ | ||
160 | {"property" : "type" : "value" : "dial"} | ||
161 | ] | ||
162 | } | ||
163 | {{/code}} | ||
164 | |||
165 | The filter message above will respond with the following message: | ||
166 | |||
167 | {{code}} | ||
168 | { | ||
169 | "type": "success", | ||
170 | "time": 1436889163971, | ||
171 | "correlationId": "123456" | ||
172 | } | ||
173 | {{/code}} | ||
174 | |||
175 | == (% style="color: rgb(0,0,0);" %)Wildcard(%%) == | ||
176 | |||
177 | 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. | ||
178 | |||
179 | == Examples == | ||
180 | |||
181 | If the following filter is provided, only userStatus events will be received. This filter can be used to detect when any user in the system changes their status. | ||
182 | |||
183 | {{code language="js"}} | ||
184 | { | ||
185 | "type" : "filter", | ||
186 | "filters" : [ | ||
187 | {"property" : "type" : "value" : "userStatus"} | ||
188 | ] | ||
189 | } | ||
190 | {{/code}} | ||
191 | |||
192 | If the following filter is provided, only userLogin and userLogout events will be received, This filter can be used to detect when any user in the system logs in or out of the client. | ||
193 | |||
194 | {{code language="js"}} | ||
195 | { | ||
196 | "type" : "filter", | ||
197 | "filters" : [ | ||
198 | {"property" : "type" : "value" : "userLogin"}, | ||
199 | {"property" : "type" : "value" : "userLogout"} | ||
200 | ] | ||
201 | } | ||
202 | {{/code}} | ||
203 | |||
204 | If the following filter is provided, only userLogin and userLogout events, for a user with username mike, will be received. This filter can be used to detect when user mike logs in and out of the client. | ||
205 | |||
206 | {{code language="js"}} | ||
207 | { | ||
208 | "type" : "filter", | ||
209 | "filters" : [ | ||
210 | {"property" : "type" : "value" : "userLogin"}, | ||
211 | {"property" : "type" : "value" : "userLogout"}, | ||
212 | {"property" : "username" : "value" : "mike"} | ||
213 | ] | ||
214 | } | ||
215 | {{/code}} | ||
216 | |||
217 | If the following filter is provided, only events that reference a user (i.e. contains the username property), will be received. This filter can be used to detect any changes relating to a specific user. | ||
218 | |||
219 | {{code language="js"}} | ||
220 | { | ||
221 | "type" : "filter", | ||
222 | "filters" : [ | ||
223 | {"property" : "username" : "value" : "*"} | ||
224 | ] | ||
225 | } | ||
226 | {{/code}} | ||
227 | |||
228 | If the following filter is provided, the filter will be reset to default (all events will be received). | ||
229 | |||
230 | {{code language="js"}} | ||
231 | { | ||
232 | "type" : "filter", | ||
233 | "filters" : [] | ||
234 | } | ||
235 | {{/code}} | ||
236 | |||
237 | = Events = | ||
238 | |||
239 | The Event API will fire several events that are related to changes occurring in the system. All events that can be fired from the Event API are listed below. Details concerning each event, and their properties, can be found within the individual event documentation pages. | ||
240 | |||
241 | == Event List == | ||
242 | |||
243 | |||
244 | |||
245 | {{children/}} | ||
246 | |||
247 | \\ | ||
248 | {{/layout-cell}} | ||
249 | {{/layout-section}} | ||
250 | {{/layout}} |