Welcome to The Modality Systems Blog

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:

• Office Communicator Automation API (2007 and R2)
• Unified Communications Client API (2007 and R2)
• Unified Communications AJAX API (2007 and R2)
• Communicator Custom Tabs (2007 and R2)

Server side:

• Unified Communications Managed API 1.0 (2007 only)
• Unified Communications Managed API 2.0 Core (R2 only)
• Unified Communications Managed API 2.0 Workflow (R2 only)
• Unified Communications Managed API 2.0 Speech (R2 only)
• Office Communications Server Application API (2007 only)
• Office Communications Server Application R2 API (R2 only)
• Office Communications Server Management API (2007 and R2)

 

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

There are two kinds of people in this world:  Those who have tried to install and configure the "Microsoft Office Communicator, Phone Edition Software Update Service" (aka, the Tanjay Update Server)… and those who haven’t.

If you have, you’re probably smirking because you know what I’m talking about.  If you haven’t yet, I might suggest you let sleeping monsters lie. 

Though if you’re a brave knight and want to test your luck, help is available.  I’ve been working with Microsoft and we’re documenting solutions to the most common problems. 

TomL (LCSKid) has posted our work over on his blog : http://blogs.technet.com/toml/archive/2008/06/02/update-server-problems-with-configupdateserver-vbs.aspx

Thomas Lee (from Global Knowledge) also has an excellent post on his blog that covers the infrastructure requirements.  http://cacorner.blogspot.com/2008/05/getting-tanjay-working.html

If you have any questions or issues not covered in these blog posts, please post a comment or email me.  We’re tracking the problems and will post updates with solutions.  Thanks!

-John Lamb, Modality Systems

At Modality Systems, we like to experiment with technology.  (Actually, that’s not exactly true – we like to abuse technology.   You don’t get good orange juice by being nice to an orange.)

One of the things that’s captured our fascination recently is the utter elegance and simplicity of the software and hardware coming out of Cupertino.  The "creative types" have known this secret for quite some time, but as a Enterprise-centric company, we’ve had our heads in the sand to some extent. 

James decided to buy an iPhone recently and we’ve all be wowed by the web browsing experience.  Outlook Web Access looks so good on this thing that he’s not entirely missing Active Sync yet.   With ActiveSync on the roadmap for the iPhone, it begs the question:  Will the iPhone become the de facto corporate communications device?  It’s not unthinkable.

For us, the important question is how this will integrate with your Unified Communications infrastructure.   There is no Communicator Mobile software for the iPhone, so the logical the logical question is how well web-based UC applications will work.

We started by running Communicator Web Access.  After you manage to get pop-up blocking disabled, it runs really well in the iPhone’s Safari browser.   The contact list doesn’t appear for some reason (though CWA works fine using Safari on a Mac or PC), but the search function works nicely and allows the user to look up a contact and send an IM.

                       

We’ll continue to test the Microsoft UC stack on Apple products and report back our findings in a series of posts.

-John Lamb, Modality Systems

Special Thanks to Steven Westwell for his knowledge and experience with Windows and Office localisation.  His assistance was instrumental in discovering the information contained in this article.  Steven’s blog can be found here: http://stevenwestwell.wordpress.com/2008/02/21/ocs-localisation/

Generally speaking, the documentation for the Office Communications Server 2007 product suite is very good.  One of the areas that is lacking however is information required for large-scale client deployments.

We’re currently in the midst of an 80,000 user global roll-out of the Office Communicator 2007 and Live Meeting 2007 clients.  In the absence of comprehensive documentation on language localisation (or “localization”, depending on which side of the Atlantic Ocean you’re on), we’ve done some extensive testing.  Here’s what we’ve learned:

I.  First things first

There are 3 client components required for OCS 2007:

1. Office Communicator 2007 – supports IM and Presence, Audio/Video conferencing, Telephony Call-Control, Voice calls, and File Transfer.
2. Live Meeting 2007 – supports Web Conferencing, Audio/Video conferencing, Whiteboard, and other forms of data collaboration.  This client is also required if you plan to deploy the RoundTable device.
3. Outlook Add-In for Conference Scheduling – This enables a user to schedule conferences using the Outlook calendar. 

Office Communicator 2007 and Live Meeting 2007 behave differently with respect to language localization.

II.  Office Communicator 2007 – Language & Localisation Settings 

Office Communicator 2007 now supports the full set of 37 Microsoft Office languages:

	Office Communicator 2007 Language	Hex Value	Decimal Value
1	Arabic – Saudi Arabia	0×401	1025
2	Bulgarian	0×402	1026
3	Chinese (Simplified) – PRC	0×804	2052
4	Chinese (Traditional) – Hong Kong SAR	0xC04	3076
5	Chinese (Traditional) – Taiwan	0×404	1028
6	Croatian	0×41A	1050
7	Czech	0×405	1029
8	Danish	0×406	1030
9	Dutch – Netherlands	0×413	1043
10	English – United States	0×409	1033
11	Estonian	0×425	1061
12	Finnish	0×40B	1035
13	French – France	0×40C	1036
14	German – Germany	0×407	1031
15	Greek	0×408	1032
16	Hebrew	0×40D	1037
17	Hindi	0×439	1081
18	Hungarian	0×40E	1038
19	Italian – Italy	0×410	1040
20	Japanese	0×411	1041
21	Korean	0×412	1042
22	Latvian	0×426	1062
23	Lithuanian	0×427	1063
24	Norwegian	0×414	1044
25	Polish	0×415	1045
26	Portuguese – Brazil	0×416	1046
27	Portuguese – Portugal	0×816	2070
28	Romanian	0×418	1048
29	Russian	0×419	1049
30	Serbian – Latin	0×81A	2074
31	Slovak	0×41B	1051
32	Slovenian	0×424	1060
33	Spanish – International	0xC0A	3082
34	Swedish	0×41D	1053
35	Thai	0×41E	1054
36	Turkish	0×41F	1055
37	Ukrainian	0×422	1058

To set the Office Communicator language manually, first install the Communicator 2007 Multi-Language User Interface (MUI) Pack, which is available for download here:  http://www.microsoft.com/downloads/details.aspx?familyid=86DE1E77-3406-475A-9271-24F507E20972&displaylang=en

Then, use the Options > General configuration page to select the language as shown in this screenshot. (Note that Communicator must restarted for the changes to take effect.)

Optionally, the Office Communicator 2007 language can be set programmatically, by modifying the following registry key:

HKCU\software\Microsoft\Communicator\Language : REG_DWORD : <language code>

If you are planning to set the OC 2007 language to be machine-specific (rather than user-specific) , such as during the OS build process, you could use the following registry key instead:

HKLM\Software\Microsoft\Communicator MUI\Default Language : REG_DWORD : <language code>

III.  Live Meeting 2007 Console – Language & Localisation Settings

In the current version of the software, there is no integration between language settings for OC 2007 and LM 2007.   According to a source at Microsoft, this will change for the next version of the Live Meeting client when the LM client is re-written “from the ground up”.

The Live Meeting 2007 Client (aka LM 2007 Console) supports the following 14 languages:

	Live Meeting 2007 Console Language	Hex Value	Decimal Value
1	Chinese (Simplified) – PRC	0×804	2052
2	Chinese (Traditional) – Taiwan	0×404	1028
3	Danish	0×406	1030
4	Dutch – Netherlands	0×413	1043
5	English – United States	0×409	1033
6	Finnish	0×40B	1035
7	French – France	0×40C	1036
8	German – Germany	0×407	1031
9	Italian – Italy	0×410	1040
10	Japanese	0×411	1041
11	Korean	0×412	1042
12	Portuguese – Brazil	0×416	1046
13	Spanish – International	0xC0A	3082
14	Swedish	0×41D	1053

 

Note: There is no MUI Pack for LM 2007.  These 14 languages ship as part of the base LM 2007 installation executable.

Unfortunately, there is no way to manually set the LM 2007 client language.  If the Windows 2000, Windows XP, or Windows Vista operating system has a language pack installed, then the LM 2007 client will automatically detect the Operating System’s language and use that.  This is the language that is specified in Control Panel > Regional and Language Settings, as shown in the screenshot below:

For example, if you have the English, French, and Japanese OS language packs installed, you would select the regional option for the desired language.  If you only have a single language pack installed(for example, only Japanese), the LM 2007 console will use Japanese by default.

This means that you must have an OS Language Pack installed in order to change the LM 2007 language… and the LM 2007 client cannot be in a different from the OS language.

This also means that you could have Office Communicator set to a different language than LM.  The best practice for deployments would seem to be to automatically set OC to be the same language as the OS (rather than the same language as Office, if the OS and Office are in different languages) to ensure that OC and LM always end up being in the same language.

IV.    Outlook Add-In for Conferencing – Language & Localisation Settings

The Outlook Add-In for Conference Scheduling will automatically change to the default language that Office is configured to use.   We didn’t test all 37 of the supported Office languages to see if the add-in  supports all of them, but it did support the western and non-western languages that we tried.

V.  Previous Versions

For completeness, I’m including the languages supported by previous versions of the the clients, which is a subset of the languages supported in the current 2007 versions.

• Office Communicator 2005 supported the following 12 languages (in addition to English) via a MUI Pack:  Spanish, Korean, Japanese, Italian, German, French, Chinese – Traditional, Chinese – Simplified, Danish, Finnish, Portuguese (Brazil), Swedish
• The Office Live Meeting 2005 client supported the following 7 languages (no MUI Pack required): French, German, Spanish, English, Korean, Japanese, Chinese – Simplified
• The Office Live Meeting 2003 client supported only English. 

-John Lamb, Modality Systems

Technorati Tags: Office Communicator, Live Meeting, Software Localization