Unified Communications AJAX API Client
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
A Unified Communications AJAX API client is any application that uses the Unified Communications AJAX API to access a Communicator Web Access Server. A client application can be a stand-alone executable, for example, a Microsoft .NET application written in C#. The client can also be browser-based Web application driven by JavaScript or other scripts embedded in a Web page. If the Web application is an ASP.NET application, C# and other .NET-compatible language code can be running behind the Web pages, as well.
Unified Communications AJAX API exposes a set of methods and events. Methods are actions performed by the server, and events are the action results or other updates returned to the client. For the list of methods and events, see Unified Communications AJAX API Reference.
Programming Patterns
The general programming pattern using the Unified Communications AJAX API has the following structure:
A client signs in to a Communicator Web Access Server using either form-based authentication, integrated Windows authentication or Single Sign On based authentication.
A successful sign on and authentication returns an Authentication Ticket through an HTTPS header called CWA-Ticket. This authentication ticket must be cached by the client and returned to the Communicator Web Access Server with each subsequent request. Communicator Web Access Server relies on this ticket to validate all requests. A request posted to the server without an authentication ticket (or an expired ticket) is rejected. The server-generated authentication ticket is periodically replaced and sent back to the client. The current valid authentication ticket is returned to the client with every response from the server.
When successfully signed in to a Communicator Web Access Server, the client can start to invoke a method by posting a cwaRequests element against the command channel to the server. The message body contains a method in XML format. The client is responsible for creating the XML message for the request. In this case, the client waits for a response from the server to determine if the request has been submitted successfully. The response is returned in a cwaResponses element. In this phase, the Communicator Web Access Server validates the request XML message but not execute the requested method before responding synchronously. For this reason, the response on the command channel is almost instantaneous.
To receive events from an asynchronous data channel, the client must register an event handler with the server. The results of the requested method are returned to the Unified Communications API client application in an individual event element contained within cwaEvents Element.
After signing in, the client must start polling the server for any incoming events. This polling can be implemented as a chain of asynchronous HTTP GET requests in which the event handler initiates another asynchronous HTTP GET request before it returns. The new request should wait for a time period, set by the server and returned in each cwaEvents Element as a pollWaitTime Element. This way, the client helps to avoid overwhelming the server. The client is responsible for parsing and handling the returned events. The Communicator Web Access Server holds each HTTP GET request open for 35 seconds to allow any in-process request methods to complete before sending events to the requesting application.
When all is done, the client signs out of the Communicator Web Access Server. At this stage, the client should also release other active resources, for example, stopping and releasing the polling thread for receiving events and clearing the authentication ticket cached in memory.
In addition, the client must be prepared to handle errors or exceptions thrown by the server.