UCMA Endpoints: Choosing between Application and User Endpoints

If you’re creating UCMA applications, fairly early on in the process you’ll need to make a decision: what type of endpoint do you need?

An endpoint is not technically required…but if you’re building a UCMA application, you’ll almost certainly need one. It’s your route into the Lync Server environment: all your communication will be via one or more endpoints.

There are two different types of endpoint: User Endpoints and Application Endpoints. They’re both set up in the same way, although they act quite differently.

User Endpoints

I find it easier to think of using User Endpoints as logging in as a user. You’ll need a username and password for that user. Once logged in, you can do all the things that user can do … but not much more. In lots of cases though, that’s ideal. If you’re writing an application to act on behalf on a user, replying to their messages or contacting people pretending to be that user, a User Endpoint will work fine. You can also use User Endpoints to represent lots of users: for instance I recently wrote a load-test app that created hundreds of User Endpoints, each with their own separate login, which then performed randomly timed requests against a Lync Server.

One of the great things about User Endpoints is that there’s no infrastructure setup involved. Provided you have a Lync system to access and the UCMA SDK installed, you can run a User Endpoint application from your desktop, in Visual Studio. You don’t need a special server, and you don’t need to jump through any of the setup tasks.

Application Endpoints

For anything you might struggle to do as a user, you’ll probably need an Application Endpoint. Application Endpoints are very powerful. For instance, you can impersonate other users and send messages pretending to be from them, join conferences without permission and throw people out, or join invisibly and record everything that’s said. Application Endpoints are also highly scalable, in a way that User Endpoints are not. You can write an application that accepts incoming Instant Messages and processes them, and roll it out to thousands of users without (m)any problems.

The flip side of all this extra functionality however, is setup. Because Application Endpoints can do pretty much anything, you can’t just compile one, point it at a Lync environment and expect it to start working. That would be like me being allowed to take a supercomputer into a Maths exam – it’s just not allowed, for all sorts of good reasons.

Instead – applications created with Application Endpoints need to be trusted. This is a fairly complicated process, but at a high level it’s split into two parts:

• The application must be running on a server which has previously been denoted a Trusted Application Server.
• The application must identify itself using a unique ID which has previously been registered with Lync, as a Trusted Application. When the application starts, Lync will then tell it about any Application Endpoints which have previously been set up for that application. Setting these endpoints up is a process known as creating Trusted Application Endpoints.

The combination of these two things mean that Lync will trust that whatever the application wants to do, is all-right by the administrator of the Lync system. For that reason, Application Endpoints don’t have to provide any login credentials: they aren’t tied to a specific user in the same way that User Endpoints are.

Dealing with the first part (sorting out the Application Server) is outside the scope of this blog, and is the reason you can’t just run Application Endpoint-based code on your developer machine. Dealing with the second part (creating Trusted Applications and Application Endpoints) is covered in a previous walkthrough I did.

Pick a Platform

In order to create an endpoint (of either type), you need to have a Collaboration Platform. This is, well – it’s a collaboration platform, allowing your application to collaborate with Lync.

There are three types of collaboration platform. They’re all created with new CollaborationPlatform, but the type of settings class you pass in will determine what sort of platform is created.

Client Platform

Use a Client Platform with User Endpoints. Because of this, the settings class takes in information about the transport type to use when making and authentication the connections to the Lync Server:

Provisioned Application Platform

Use a Provisioned Application Platform with Application Endpoints. Because of this, this settings class takes the applicationID – the identity of the Trusted Application as previously registered in Lync.

Server Platform

Outside the scope of this post, but use a Server Platform when creating applications which are neither Application Endpoints or User Endpoints, and in fact don’t connect to Lync at all! They’re useful if you just need something to deal in SIP messages, such as re-routing incoming calls for an IVR for instance. See Michael Greenlee’s excellent blog post on the subject for more.

Creating the Endpoint

Once you’ve created the Collaboration Platform and it’s established, you can create the endpoints. This is done differently, depending on what sort of endpoint you’re creating.

User Endpoints

You’ll need to know the SIP Address, Username, Password and Domain of the user you want your endpoint to sign in to Lync as:

That’s all you need to do. Following a successful establish, your endpoint will be set up. You can establish multiple endpoints using the same Collaboration Platform if you need to.

Application Endpoints

There’s no actual code to create an Application Endpoint. If you remember, Lync already knows what the Application Endpoints are – you would have had to specify them as Trusted Application Endpoints. So, Lync will tell you what the endpoints are!

If you look back to how the Provisioned Application Collaboration Platform is set up, you’ll see that there’s a event registration for new application endpoints. It’s this event which gets called when Lync tells us about one or more endpoints. Once we get told about them, we can establish them:

Using the Endpoints

Once your endpoints are established, you can use them fairly interchangeably – they both derive from the same class. Be aware, however, that you can end up writing code that won’t work. For instance, you can establish a User Endpoint, and then attempt to impersonate a conversation. This will compile, but will produce a run-time error because a User Endpoint isn’t allowed to impersonate conversations.

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.

---

Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Related posts:

Walkthrough: Creating a UCMA Application & Application Endpoint Creating UCMA Applications with a UserApplication instance. Example: sending IMs. UCMA App Error: Microsoft.Lync.Model.LyncClientException: Generic COM Exception. Code is 0x80EF01F8 Learning to dive: UCMA Coding UCMA Workflow 1 – Introduction