OCS Development – The APIs

Paul N | Development,Office Communications Server,Office Communicator | Wednesday, March 25th, 2009

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

5 Comments »

  1. [...] recently blogged about the APIs that are available for developing against and extending OCS, and how choosing the [...]

    Pingback by Overview of the OCS APIs - GotUC - GotUC.Net — 16 April, 2009 @ 2:17 pm

  2. I’m currently working on a SharePoint project and need to do something as simple as to make a button – a C# webpart – that initiates an intranet Live Meeting. We have a complete setup with AD, Exchange and OCS that is running and the Outlook “Meet now” works perfectly. What I need to know is where to start :)

    Maybe you can tell me which API to use?

    Thanks in advance!

    Comment by Toke — 17 April, 2009 @ 7:28 pm

  3. Hi Toke, I didn’t mention the Live Meeting APIs above as I was concentrating on the core OCS APIs, and didn’t want to further muddy the waters.

    Anyway, there are two APIs available for Live Meeting – the API you want is the Live Meeting Service API. The API uses XML/HTTP so should be a breeze to integrate with Sharepoint ;o)

    An overview of the LM APIs can be found here – http://msdn.microsoft.com/en-us/office/aa905513.aspx

    …and the reference documentation for the Service API can be found here – http://msdn.microsoft.com/en-us/library/bb894159.aspx

    Hope this helps,

    Paul

    Comment by Paul N — 20 April, 2009 @ 11:34 am

  4. FYI – Custom Tabs are no longer dynamic

    I opened a ticket w/ Microsoft and here is their answer I received – below. Basically The RTC Team reassigned the purpose of ContactID and removed the OnSelectionChange Function. So there are no more dymanic tabs in which you can send the contact SIP URI to a webpage and update your tab – now there is only static web pages . Also the OCS R2 documentation is incorrect in that it states OnSelectionChange is still avaiable but it is not. Also RTC went back to using GET and POST statements on the Contact Cards which open up a web browser.

    ************************************************************

    Microsoft Replies

    The Communicator R2 client tab functionality has changed from what it was in Communicator 2007. In OC 2007 you could pass the contactID parameter to tabs that were listed at the bottom of the Communicator contacts display. Microsoft has changed the use of tabs in OC 2007 R2 such that you can only display static tabs at the bottom of the Communicator contacts display area. The previous functionality has been moved to the tabs at the bottom of the contact card for each user. So if you wanted to access contact sensitive data you need right-click on the user and choose “View Contact card”.

    See Configuring Custom Tabs in Communicator 2007 R2

    ELEMENT contactid (“true” | “false”)
    Determines whether the tab appears in the contact card. Tabs defined without contactid or with contactid=false will appear only in the Communicator window. Tabs defined with contactid=true will appear in the contact card, and Communicator will pass the selected contact to the defined page. The default value is “false.”

    If you have set

    true => the tabs that would normally be present at the bottom of the OC 2007 display area is now moved to the contactcards, and then the contact sip URI will be passed to the tabs that now appear in the contact card.

    Here is a statement from RTC Core:

    In R2 the extensibility of Communicator enforces a more strictly defined user experience. In our product roadmap going forward, the Contact Card will gain prominence, and in order to prepare for those upcoming changes, we slightly modified the API behavior of the Custom tabs to display tabs using the ContactId=true to appear in the Contact Card and to be contact specific.

    Comment by voipen — 21 April, 2009 @ 4:29 pm

  5. Hello

    Interesting post.

    I have a question, I have a ocs 2007 R2 with CWA basically I have an asp.net app and I want to provide a link to the CWA client passing their credentials via forms authentication and automatically sign them in. I have all the valid credentials.

    As far I have managed to sign into the server and recieve the CWA-Ticket authentication ticket how do I then open the client? Is this the correct approach?

    With Thanks

    Richard

    Comment by Richard james — 30 July, 2010 @ 9:46 am

RSS feed for comments on this post. TrackBack URI

Leave a comment

© 2007–2008 Modality Systems Limited