Register Contextual Conversation Packages

[This is preliminary documentation and is subject to change.]

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

  • 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 note 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 2013 Preview 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 2013 Preview signs out or exits. Use Install Registration for better control of package setup. For more information, see How to: Perform Install Registration for an Extensibility Application.

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 2013 Preview registration pool, and resets after the Lync 2013 Preview user signs out. Use the ApplicationRegistration class to perform Run-Time Registration. For more information, see How to: Perform Run-Time Registration for an Extensibility Application.

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 2013 Preview 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 2013 Preview registration pool until the current Lync 2013 Preview 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 note 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

  • 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.

  • 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

  1. Install the context application.

  2. Add registry keys as appropriate.

  3. 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 2013 Preview 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 2013 Preview 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” ="http://localhost/Test/sample2.html""Name"="Blue Yonder Airlines"
"ExtensibilityWindowSize"=dword:00000001
"Parameters"="%AppData%,%AppId%"

Community Additions

Show:
© 2014 Microsoft