When it comes to developing against Office Communications Server, choosing the appropriate API can be a task in itself. The number of available APIs can be a bit overwhelming at first glance, and the selection task is not helped by concerns over which APIs are compatible with which release.
This post aims to shine a small light on each of the APIs, and give an idea of which APIs can be used against which version of Office Communications Server. (Disclaimer: version compatibility was determined by the information available on MSDN at the time of writing, and a small amount of testing)
The APIs currently available are:
Client side:
Server side:
Office Communicator Automation API (2007 and R2)
This is a client side COM API that allows an application to automate the running instance of communicator. Communicator 2007/R2 must be installed on the target machine, and must be running in order for an application to make use of it.
Using this API, a custom application can perform the same tasks as communicator – for example:
- Sign into/out of communicator
- Display a list of contacts, with presence information (including the signed-in user’s presence) and profile information
- Manage contacts and contact groups
- Start voice/video/IM conversations (these will open a new Communicator conversation window, as if the call had been initiated from Communicator)
- Send text to an IM conversation
- Manipulate the main Communicator window (size, positioning)
This allow the developer to integrate presence and “click to communicate” functionality into applications, and also allows for the possibility of passing information from one instance of an application to another – for example, User A initiates a conversation about a customer with user B. User B’s application updates to show the customer records of the customer being discussed.
Unified Communications Client API (2007 and R2)
This is a client side COM API that allows custom applications to be written that include communication capabilities, without the restriction of having Communicator installed on the target machine. Although more complicated to use than the Communicator Automation API, it does allow full control over communications capabilities.
To contrast this API and the Communicator Automation API this example should give a flavour of the differences:
- When starting a conversation in an application using the Communicator Automation API, a new Communicator conversation window is opened (i.e. the conversation window is not integrated into the application).
- Using the Unified Communications Client API, we could start a conversation from an application, and also embed conversation windows into the application. While this is more development work, it provides a much more integrated feel.
This API allows the developer to integrate all of the same capabilities that Communicator provides into a custom application. As well as this, it gives the developer a lower-level insight into the SIP messages – for example, SIP headers can be examined.
Unified Communications AJAX API (2007 and R2)
This API allows custom web pages to be created that include communication capabilities. It requires that Communicator Web Access be enabled in the OCS environment.
The API allows the developer to include the following capabilities into web pages:
- Presence subscribing/publishing
- Contact management
- Start and accept IM conversations/conferences (no voice/video)
Communicator Custom Tabs (2007 and R2)
Custom Tabs can be added into communicator. These host an Internet Explorer control, so can be used to display a web page. The web page is sent the SIP URI of the signed-in user, and also the SIP URIs of any selected contacts.
This allows the developer to display further information related to the user and the user’s contacts, within the main communicator window. Not strictly an API, custom tabs are enabled through registry settings and xml config files.
Unified Communications Managed API 1.0 (2007 only)
This is a server-side API that can be used to create applications that interact with OCS, and appear as users with their own SIP URI. This is the API that is typically used for creating query/response agents (Bots), or Broadcast IM bots that send IMs in response to certain events.
This API allows the application to behave as a user, with the following limitations:
- There is no support for querying presence
- IM is the only modality supported
- There is no support for conferencing
Using this API, the developer can create applications that:
- Provide an end-point for users to query to get information – for example, a bot that responds to queries for stock prices
- Broadcast information to users when certain events happen – for example, when a stock price falls below a certain threshold
Unified Communications Managed API 2.0 Core (R2 only)
This API builds on UCMA 1.0 by adding the following support:
- Querying presence
- Audio
- Conferencing
As well as the application scenarios that UCMA 1.0 enables, this API allows the developer to create applications that:
- Ask users for information as part of a workflow – for example, User A submits an expense claim, the bot starts a conversation (IM or Voice) with User B when they are available, provides details of the expense claim, and asks User B for authorisation
- Initiate or join conferences – for example, schedules a conference and IM’s participants 15 minutes beforehand
Unified Communications Managed API 2.0 Speech (R2 only)
This API provides Speech Recognition and Text-to-Speech capabilities for applications, allowing the developer to create applications that:
- Place a voice call, and read textual information to the call recipient – for example, the contents of an email
- Understand and respond to voice commands
Unified Communications Managed API 2.0 Workflow Activities (R2 only)
Windows Workflow Foundation is a technology for building applications, which allows business processes to be modelled as Workflows (think Flow Charts). Each step in the workflow relates to an “Activity”, which is a block of code that performs a specific task – for example, email a user using this template. This (in theory) cuts development time and makes changes to the business process easier to accommodate.
The UCMA 2.0 Workflow Activities are pre-defined workflow activities which provide the following capabilities (and more):
- Answer an incoming call (Voice or IM)
- Ask the user questions
- Respond to commands
This primary scenario this API enables is Interactive Voice Response applications.
Office Communications Server Application API (2007 only)
This API allows modification of standard OCS functionality at the SIP message level.
Using this API, a developer can create applications that inspect messages as they pass through a given server, and take actions based on information in that message, for example:
- Modify the message in some way – for example, add a disclaimer to the body text
- Reject certain messages – for example, those that contain hyperlinks
- Log messages to a database
- Perform routing tasks
Office Communications Server Application R2 API (R2 only)
As above, but 64 bit, and with some minor additions.
Office Communications Server Management API (2007 and R2)
This API provides the ability to manage an OCS installation, via WMI. It can perform a huge range of tasks, for example:
- Modifying users Communicator contacts and groups
- Modifying edge server settings
The relevant WMI classes are installed on any machine that has the Office Communications Server administrative tools installed.
I hope this clarifies the options available. Quite a few already, and I haven’t even mentioned the APIs available to integrate with other server products e.g. Exchange, SharePoint, Live Meeting…!
- Paul Nearney, Modality Systems