Register contextual conversation packages

Beyond the basics topic

Learn about the concept of Conversation Window Extension registration using Microsoft Lync 2013 SDK.

Applies to: Lync 2013 | Lync Server 2013

In this article
Understanding Install and Runtime Registration
Register the contextual conversation package
Additional resources

Contextual conversation packages

A contextual conversation registration package registers an application with the local system registry so that the identity of the application can be validated before the application can send or receive contextual data in a conversation. A registration package can set up to eight registry key values, depending on the type of contextual application to be registered. A contextual application can be one of the following types:

Conversation window extension application.

This is a Silverlight browser application that access contextual data through a hosting conversation. ExtensibilityWindowSize, InternalURL, ExternalURL, and InstallLink values should be set.
Lync 2013 Conversation-specific WPF or Windows forms desktop application.

This is an application that is started by Lync 2013when a new conversation with the appropriate context is opened. The instance of this application that is started should get only the conversation context of the associated conversation. This type of application requires that its contextual conversation registration includes a Path to the executable to be started.
User-started WPF window, Windows forms desktop application, or service.

This application is not started by the Microsoft Lync 2013 client. Instead, the application is started by another agent such as the local user. The application uses the Lync 2013 API to start or accept new conversations and then sends and receives contextual data. This type of application requires that the Name value is set in its contextual package. An example of this type of application is a custom client that runs in a UI suppression scenario and replaces the suppressed UI of Lync 2013.

The Path, InternalURL, and ExternalURL values must not be set. If any of these values are set, Lync 2013 starts a new instance of the application for any conversation conveying context whose application Id matches the subkey GUID of the registration package.

Understanding Install and Runtime Registration

Contextual software installation is designed to be flexible and support security for enterprises, independent software vendors, and system integrators.

There are two ways to register a contextual application:

Install Registration
Runtime Registration

These two choices are compatible. In fact, the recommended practice is to perform Install Registration to install the contextual application, and then Runtime Registration every time that the application starts.

Important
Runtime Registration provides extra security around the GUID used in registration. The GUID can only be used in the same thread where Runtime Registration is used. If another thread tries to use that GUID to identify the contextual application, access the contextual context, or open Microsoft Lync 2013 CWE, an access denied exception is thrown. To use the GUID in more than one thread, use Install Registration. In this case, consider that your contextual data can be accessed by other applications running on the same computer as long as they have access to the Lync 2013 API.

Runtime Registration provides extra security around the GUID used in registration. The GUID can only be used in the same thread where Runtime Registration is used. If another thread tries to use that GUID to identify the contextual application, access the contextual context, or open Microsoft Lync 2013 CWE, an access denied exception is thrown. To use the GUID in more than one thread, use Install Registration. In this case, consider that your contextual data can be accessed by other applications running on the same computer as long as they have access to the Lync 2013 API.

Install Registration

Install Registration uses a setup application or Group Policy to position entries into the registry. In this case, package registration data persists after Lync 2013 signs out or exits. Use Install Registration for better control of package setup. For more information, see How to: Install a CWE application in Lync SDK.

Install Registration is a good choice for scenarios such as the following:

Anytime a sales manager gets a call from an outside customer, she wants to see, by default, her Customer Relationship Management (CRM) record for that person. However, the particular view of that application that she sees is based on her role and the administrator has set up pools of Group Policy object (GPO) settings to ensure different roles see different views of the CRM application.

Runtime Registration

In contrast with Install Registration, Runtime Registration uses an application to modify package registration data at runtime. Use Runtime Registration for flexible package setup and the security advantages. In this case, package registration data is added to the Lync 2013 registration pool and resets after the Lync 2013 user signs out. Use the ApplicationRegistration class to perform Runtime Registration. For more information, see How to: Install a CWE application in Lync SDK.

Runtime Registration is a good choice for scenarios such as the following:

An application only wants to provide a contextual experience when it's running. For example, Sam is a financial advisor who uses Lync 2013 to talk with his clients. When his market tracking software is open and he gets a call from a customer, it changes the application view to show the customer’s portfolio. This call is automatically noted in the finance software for auditing reasons. Because of auditing requirements, a customized view is not available unless the finance software is running.

Interaction between Runtime and Install Registration

Runtime Registration does not configure Microsoft Windows registry entries. Instead, it creates a new application package that exists in the Lync 2013 registration pool until the current Lync 2013 user signs out. Runtime Registration can exist without Install Registration, but if you use Runtime Registration consider using Install Registration as well. In a case where Runtime Registration and Install Registration occur with the same application ID, Runtime Registration overrides Install Registration during the life of the session. When the user signs out, Runtime Registration resets and Install Registration starts.

Conversation package location restrictions

Contextual conversation packages can be installed to a UNC, URL, or file path. To simplify management of the package, install it to a URL or UNC.

Important
By default, contextual links in the form of UNC paths are not trusted. The untrusted UNC path must be added to the list of Trusted Sites maintained by Microsoft Internet Explorer to start the contextual application in CWE. Internal URLs resolving to Localhost, computer name, local loopback address, or actual IP address must be added to Trusted Sites.

The following table summarizes the security status of contextual conversation packages installed on specified UNC paths.

Location	Permission
Local file	Allowed
Network share	Blocked
Network share in Trusted Site	Allowed
Network drive	Blocked
Network drive with computer name on Trusted Site	Allowed
Virtual drive pointing to local drive	Allowed
Local drive from Visual Studio	Allowed
Network drive pointing to local computer share	Blocked

Register the contextual conversation package

Specify a default application to provide a context when none is available. For example, when a sales manager gets a call, a CRM application automatically starts and displays key information about the caller. For more information, see Understand the role of the default CWE application registration package.

Specify rich context handling and applications. For example, when two oil field engineers consult about a field, the company’s line-of-business application automatically starts to run and it provides various graphical displays that represent geological data. For more information, see Consume data and handle events in a contextual conversation.

To register a context package

Install the context application.
Add registry keys as appropriate.
Perform steps 1 and 2 on both the sending and receiving computers.

Registration data values

Add the context application GUID as a key under this path:

HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Lync\Addins

For more information about application GUIDs, see Create GUID (guidgen.exe).

The following table lists the case-sensitive values to add to this key.

Value name	Type	Description
Name	REG_SZ	Required. The name of the context application. For example, "Blue Yonder Airlines."
InstallLink	REG_SZ	Optional. Specifies a URL pointing to an installation file that you provide. A clickable link displays if a package is not installed on the receiving computer.
DefaultContextPackage	REG_DWORD	Optional, defaults to 0. Specifies whether this package is the default package for all unassigned calls. 0 = false, 1 = true.
ExtensibilityWindowSize	REG_DWORD	Optional, defaults to 0. Sets the minimum size of CWE. 0 = small (300 x 200 pixels), 1 = medium (400 x 600 pixels), 2 = large (800 x 600 pixels).
InternalURL	REG_SZ	Required only for applications running inside CWE. Specifies a context application URL in the Lync Server 2013 domain. The application automatically detects which URL to use, InternalURL or ExternalURL, based on the client location. This entry also accepts the three optional parameters described in the following table.
ExternalURL	REG_SZ	Optional. Specifies a context application URL located outside the Lync Server 2013 domain and is required when a client signs in from outside that domain. The application automatically detects which URL to use, InternalURL or ExternalURL, based on the client location. This entry also accepts the three optional parameters described in the following table.
Path	REG_SZ	Optional. Specifies the path of a desktop application and determines whether the start link appears. If not present, the start link does not appear.
Parameters	REG_SZ	Optional. Specifies one or more parameters for the Path value. This entry also accepts the three optional parameters described in the following table.

The following table describes the three optional parameters for the Parameters value, as mentioned in the previous table.

Parameter	Description
%AppData%	Use this parameter to obtain the application data sent in a contextual conversation. The value is the same as the value of the ConversationContextualInfo.ApplicationData property. The size limit's 2 KB.
%AppId%	Use this parameter to obtain the application GUID sent in a contextual conversation. The value is the is the same as the value of the ConversationContextualInfo.ApplicationId property. The size limit's 38 characters, which is the size of an application GUID.
%AppName%	Use this parameter to obtain the application name sent in a contextual conversation. The value is the same as the Name value in the Windows Registry. The size limit's 50 characters.

Sample registry entries

HKEY_CURRENT_USER\Software\Microsoft\Communicator\ContextPackages\{55058F71-6ACF-48D0-B20E-BC7668695371}]
"DefaultContextPackage"=dword:00000000
"Path" ="http://localhost/Test/sample2.html""Name"="Blue Yonder Airlines"
"ExtensibilityWindowSize"=dword:00000001
"Parameters"="%AppData%,%AppId%"