Share via

Simplified Presence Publication for Endpoints

  • Article

Presence publication for user endpoints and application endpoints has been simplified in Microsoft Unified Communications Managed API (UCMA) 3.0. Applications can opt to automatically publish presence information for either endpoint type at the time the endpoint is established. This is especially useful for applications that publish commonly used presence categories such as state and endpoint capabilities once, as well as for those that rarely change their published information. These applications do not need to directly deal with the underlying subscription (which is managed by LocalOwnerPresence).

The actual nature of the data published for each type of endpoint differs and is discussed in the subsequent sections of this topic. In addition, there are simplified APIs to maintain the presence information for the duration of the endpoint’s lifetime. This presence information is available through the endpoint’s PresenceServices property—PresenceServices on an application endpoint, and PresenceServices on a user endpoint. These properties are references, respectively, to ApplicationEndpointPresenceServices and UserEndpointPresenceServices objects.

To "bootstrap" (publish initial presence information automatically when the endpoint is established), the AutomaticPresencePublicationEnabled property on the settings object (UserEndpointSettings for user endpoints and ApplicationEndpointSettings for application endpoints) should be set to true and the data to be published should be provided. If no data is specified, a default behavior is assumed. If for any reason there is an exception during the publication process (such as when the user services cluster in the enterprise is down), the establishment process is allowed to continue and publication is retried after a specified duration (about 15 minutes unless the registrar requests a different duration).

Applications that require the actual state of the auto-publishing request can track the AutomaticPublicationState property on a LocalOwnerPresence object, or can register for notification when the AutomaticPublicationStateChanged event is raised. A value of Published for the AutomaticPublicationState property indicates successful publication, while a value of WaitingForRetry indicates that the publication operation will be retried.

Publishing Presence for a UserEndpoint

For user endpoints, setting the AutomaticPresencePublicationEnabled property to true in the settings object causes the following actions to be taken.

  • Subscribe to LocalOwnerPresence and potentially bootstrap the endpoint owner's containers with default presence publications and container memberships, as determined by the server manifest. For more information, see Unified Communications Enhanced Presence Schemas for Microsoft Lync Server 2010.

  • Publish an initial endpoint state of EndpointOnline, a static value of the PresenceState class. In addition, publish a user presence state, provided that UserEndpointSettings.Presence.UserPresenceState is non-null.

  • Publish the endpoint's basic device capabilities, as specified by the PreferredServiceCapabilities property, if supported by the underlying platform. No device capabilities are published if PreferredServiceCapabilities is set to null. This property can be accessed from the Presence property on a UserEndpointSettings instance.

In the event of any exception being thrown during publication, all of the preceding steps are repeated.

In UCMA 3.0, presence state values can be modified by the use of the following methods on the PresenceServices property on the endpoint.

In addition, the LocalOwnerPresence property on an endpoint provides access to a LocalOwnerPresence object, which has methods and properties that can be used for more advanced scenarios.

Publishing Presence for an ApplicationEndpoint

UCMA 3.0 has simplified APIs for bots or automata applications that are intended to persist their presence information because they rarely change. Such applications must set the AutomaticPresencePublicationEnabled property on the ApplicationEndpointSettings object to true and must provide any optional information that is to be published. The following categories are automatically published to container 0. For more information about containers, see “Containers and Categories Used by Microsoft Lync” in Unified Communications Enhanced Presence Schemas for Microsoft Lync Server 2010.

In the event of an exception being thrown during publication, all of the preceding steps are repeated. The values in the preceding list can be accessed through the PresenceServices property on the endpoint after endpoint establishment.

UCMA 3.0 allows the PresentityType and Description properties of a ContactCard instance to be modified, provided that automatic presence publication is enabled. The UpdatePublishedData(String, String) method on the PresenceServices property can be used for this purpose.

In the following example, an ApplicationEndpoint instance is created and initialized with several properties on an ApplicationEndpointSettings instance that are appropriate for a bot.

ApplicationEndpointSettings endpointSettings = new ApplicationEndpointSettings("sip:bot@contoso.com");
endpointSettings.AutomaticPresencePublicationEnabled = true;
endpointSettings.Presence.PresentityType = "automaton";
endpointSettings.Presence.Description = "this is a test bot";
endpointSettings.PreferredServiceCapabilities.InstantMessagingSupport = CapabilitySupport.Supported;
ApplicationEndpoint endpoint = new ApplicationEndpoint(platform, endpointSettings);