Register Contextual Conversation Packages in Lync 2010

Article
01/20/2015

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

Understanding Install and Run-Time Registration

There are two ways to register a contextual application:

Install Registration
Run-Time Registration

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

Important

Run-Time Registration provides extra security around the GUID used in registration. The GUID can only be used in the same thread where Run-Time Registration is used. If another thread tries to use that GUID to identify the contextual application, access the contextual context, or open Microsoft Lync 2010 Conversation Window Extension (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 Microsoft Lync 2010 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 Microsoft Lync 2010 signs out or exits. Use Install Registration for better control of package setup. For more information, see Walkthrough: Perform Install Registration for an Extensibility Application (Lync 2010 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. But, 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.

Run-Time Registration

In contrast with Install Registration, Run-Time Registration uses an application to modify package registration data at run time. Use Run-Time Registration for flexible package setup and the security advantages. In this case, package registration data is added to the Lync 2010 registration pool, and resets after the Lync 2010 user signs out. Use the ApplicationRegistration class to perform Run-Time Registration. For more information, see Walkthrough: Perform Run-Time Registration for an Extensibility Application (Lync 2010 SDK).

Run-Time Registration is a good choice for scenarios such as the following:

An application only wants to provide a contextual experience when it is running. For example, Sam is a financial advisor who uses Lync 2010 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 Run-Time and Install Registration

Run-Time Registration does not configure Microsoft Windows registry entries. Instead it creates a new application package that exists in the Lync 2010 registration pool until the current Lync 2010 user signs out. Run-Time Registration can exist without Install Registration, but if you use Run-Time Registration consider using Install Registration also. In a case where Run-Time Registration and Install Registration occur with the same application ID, Run-Time Registration overrides Install Registration during the life of the session. When the user signs out, Run-Time 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 a 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 Package in Lync 2010.
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 Lync 2010 Contextual Conversation.

To register a context package

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

Registration Data Values

Add the context application GUID as a key under either of these two paths:

HKEY_CURRENT_USER\Software\Microsoft\Communicator\ContextPackages
HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Communicator\ContextPackages

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 the CWE. 0 = small (300 x 200 pixels), 1 = medium (400 x 600 pixels), 2 = large (800 x 600 pixels).
InternalURL	REG_SZ	Required for applications running inside the CWE. Specifies a context application URL in the Microsoft Lync Server 2010 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	Specifies a context application URL located outside the Microsoft Lync Server 2010 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	Required for desktop applications. Specifies the path of a desktop application and determines whether the start link appears. If not present, then the start link will 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. Size limit is 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. Size limit is 38 characters, the size of an application GUID.
%AppName%	Use this parameter to obtain the application name sent in a contextual conversation. The value is is the same as the Name value in the Windows Registry. Size limit is 50 characters.

Sample Registry Entries

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