Using Lync Controls to Send Contextual Data

Summary:   This article and the accompanying video describe how to use a Microsoft Lync 2010 control to send contextual data in an IM message, and then retrieve the contextual data in the Lync Conversation Window Extension on another computer.

Applies to:   Microsoft Lync 2010 SDK | Microsoft Lync 2010 | Published:   December 2010 | Provided by:   John Clarkson, Microsoft | About the Author

Contents

  • Introduction

  • Creating a Lync Controls Application to Send Contextual Data

  • Registering the Lync Controls Application

  • Creating a Lync API Application to Receive Contextual Data

  • Registering the Lync API Application

  • Sending an Instant Message with Contextual Data

  • Conclusion

  • Additional Resources

Introduction

By now you likely are familiar with the Microsoft Lync 2010 user interface.

Microsoft Lync 2010

When the Unified Communications group created the Microsoft Lync 2010 SDK they wanted to make it as easy as possible for you to add the Lync UI to your application. So they included a series of twenty or so Microsoft Windows Presentation Foundation (WPF) and Microsoft Silverlight controls to enable you to add Lync features right into your application. Often, adding a control needs no more than a simple drag-and-drop operation.

You may have heard about contextual conversations, which is an added feature of the Lync SDK. Briefly, it enables you to more quickly share added data with whomever you're calling. For example, say that you answer a customer call in Lync. An application opens in the Conversation Window Extension, displaying data about the customer and the issue they called about. Maybe the data includes their credit rating, account number, and a summary of purchases or other interactions over the last few months. The following image shows the Conversation Window Extension displaying a Lync controls sample application.

Extensibility window

In this article, I demonstrate how to create a Lync controls application that uses a couple lines of XAML to send an IM message that, when the message is answered, opens an application and displays data packaged with the call. The application and data add context to the IM message.

To do this, you must have Microsoft Visual Studio 2010 development system, and the Lync 2010 SDK. To send messages back and forth you'll need two computers signed in to Lync with different identities. At Microsoft, we are lucky enough to have test domains complete with accounts, so I was able to do this with fictional user identities.

You'll need to do two things on both the sending and receiving computers.

  1. Add a Lync application.

  2. Register the Lync application.

Creating a Lync Controls Application to Send Contextual Data

The application described in this section sends the IM and the contextual data. If you are following along, add a WPF application on the sending computer that contains a StartInstantMessagingButton control.

To add the Lync controls application

  1. In Visual Studio, use the Lync WPF Application template to create a new project.

  2. In Window1.xaml in the XAML pane there is automatically a PresenceIndicator control that is contained in a StackPanel control. Add the following XAML code following the existing StackPanel control.

    <StackPanel>
         <StackPanel.Resources>
         <controls:ConversationContextualInfo 
          x:Key="contextualInfo" 
          ApplicationId="{}{55058F71-6ACF-48D0-B20E-BC7668695371}"
          ApplicationData="your contextual data here"
          Subject="Try out this customized subject!"
        />
         </StackPanel.Resources>
         <controls:StartInstantMessagingButton 
          x:Name="startInstantMessaging"
          Source="mary@contoso.com"
          ContextualInformation="{StaticResource contextualInfo}"
        />
    </StackPanel>
    

    The ConversationContextualInfo class is a data structure that contains the contextual data. In this code, the ConversationContextualInfo properties specify the GUID of the contextual application, and the data you're sending. The empty braces in the ApplicationId property escape the following ‘{’.

    The MSDN Library topic Create GUID (guidgen.exe) describes how to create an application GUID.

  3. In the XAML pane, change the value of the Source property of the StartInstantMessagingButton control to the SIP address of the IM’s destination. Also note the ContextualInformation property, which is set to the value of the ConversationContextualInfo control.

  4. Build and run your application, and note the path of the .exe file.

Registering the Lync Controls Application

Use Registry Editor to register the context applications that you created by using the previous instructions.

To register the Lync Controls application

  1. Add the 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

  2. Add a Name entry as a string, containing an application name.

  3. Add a Path entry as a string, containing the path of the .exe file:

    [HKEY_CURRENT_USER\Software\Microsoft\Communicator\ContextPackages\{55058F71-6ACF-48D0-B20E-BC7668695371}]
    "Path"="C:\Temp\IM_Application.exe"
    "Name"="Blue Yonder Airlines"
    

Creating a Lync API Application to Receive Contextual Data

The application described in this section receives the data sent by the Lync controls application. If you are following along, on the receiving computer add a Lync API application embedded in an HTML page that opens in the Lync 2010 Conversation Window Extension.

To create the Web Host

  • Use Notepad to create a simple HTML page and save it to a convenient location. For demonstration purposes, I use the root folder on drive C. The HTML page should include an object element to embed the Silverlight plug in. As an alternative, consider using one of your own web applications as a host.

    Note

    In the next section, you may find it easier to choose to host the Silverlight application in a website. In that case, Visual Studio creates an HTML page for you, and your registry entry should use a file path entry to point to that page.

    <html>
    <head>
    </head>
    <body>
    <object width="300" height="300" 
    data="data:application/x-silverlight-2," 
    type="application/x-silverlight-2" >
    <param name="source" value="myApplication.xap"/>
    </object>
    <p>Text in an HTML paragraph element</p>
    </body>
    </html>
    

To create the Lync API application

  1. In Visual Studio, use the Lync Silverlight Application template to create a new project.

  2. Add a project reference to Microsoft.Lync.Model and using statements for Microsoft.Lync.Model.Extensibility and Microsoft.Lync.Model.Conversation.

  3. In Page.xaml, add a button and a text box control to the design pane. Name the text box control LoggerTextBox. Name the button control GetAppData. Of course you can use your own names, but these names work with the following sample code.

  4. Add the following code to Page.xaml.cs.

    public partial class Page : UserControl
    {
        // Create the Conversation object.
        Conversation _conversation;
        const string AppId = "{55058F71-6ACF-48D0-B20E-BC7668695371}";
    
        public Page()
        {
            InitializeComponent();
            Initialize();
        }
    
        // Print logging text to a text box control.
        private void Logger(string text)
        {
        LoggerTextBox.Text += text + "\n";
        }
    
        private void Initialize()
        {
        try
            {
                // When the application is launched in the Conversation Window Extension,
                // it first needs to find the Conversation object it belongs to.
                _conversation = (Conversation)Microsoft.Lync.Model.LyncClient.GetHostingConversation();
    
                // To handle context data the application needs to register for these two events.
                _conversation.InitialContextReceived += OnInitialContextReceived;
                _conversation.ContextDataReceived += OnContextDataReceived;
            }
            catch (Exception ex)
            {
                Logger("Exception1: " + ex);
            }
        }
    
        // Occurs when context data is received in a conversation.
        public void OnContextDataReceived(object sender, ContextEventArgs args)
        {
            try
            {
                Logger("OnContextDataReceived: AppId = " + args.ApplicationId +
                    " DataType = " + args.ContextDataType +
                    " Data = " + args.ContextData);
            }
            catch (Exception ex)
            {
                Logger("Exception2: " + ex);
            }
        }
    
        // Occurs when the initial context data is received in a conversation.
        // In the scenario described in this article, OnInitialContextReceived occurs 
        // before GetHostingConversation is called in the Initialize event.
        public void OnInitialContextReceived(object sender, InitialContextEventArgs args)
        {
            try
            {
                Logger("OnInitialContextReceived: AppId = " + args.ApplicationId + " AppData = " + args.ApplicationData);
            }
            catch (Exception ex)
            {
                Logger("Exception5: " + ex);
            }
        }
    
        // Use the GetApplicationData method to retrieve context data
        // cached in the Conversation object.
        private void GetAppData_Click(object sender, RoutedEventArgs e)
        {
            try
            {
                string appData = _conversation.GetApplicationData(AppId);
                Logger("AppData = " + appData);
            }
            catch (Exception ex)
            {
                Logger("Exception6: " + ex);
            }
        }
    }
    
  5. Build the application.

  6. Locate the Silverlight project .xap file, which should be located in the bin/debug folder. Copy it to the same folder as the HTML file.

  7. In the object element, add the .xap file name to the value attribute in the param element:

    <param name="source" value="myApplication.xap"/>
    
  8. Open the HTML file in Microsoft Internet Explorer and see that it contains the Lync Silverlight application. You may need to edit the Height and Width properties of the object element to get the desired appearance.

Registering the Lync API Application

Much as you did with the WPF application on the sending computer, use Registry Editor to register the web application on the receiving computer. The receiving and sending applications register using the same GUID.

To register the Lync API application

  1. In Registry Editor, add the 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

  2. Add a Name entry as a string, containing your application name, for example "Lync Controls Context".

  3. Add a InternalURL entry as a string, containing the path of the HTML file that you created earlier:

    [HKEY_CURRENT_USER\Software\Microsoft\Communicator\ContextPackages\{55058F71-6ACF-48D0-B20E-BC7668695371}]
    "InternalURL"="https://localhost/Test/sample.html"
    "Name"="Blue Yonder Airlines"
    

Sending an Instant Message with Contextual Data

Now, on one computer that you have a Lync WPF application prepared to send an IM with contextual data. On the other computer, you have a web application with Lync API code that receives the message and displays the contextual data.

To send the Instant Message

  1. On the sending computer, start the Lync controls application.

  2. Click the StartInstantMessagingButton control. Type some text in the IM pane and press Enter. In the conversation window you see your message text, and a notice that lists your application name and says that you started a contextual conversation.

  3. On the receiving computer, click the toast notification. The conversation window opens with your web application in the Conversation Window Extension.

  4. Click the GetAppData button. Your context data appears in the text box.

Contextual data in a conversation

Conclusion

In this article, you learned how to use the StartInstantMessagingButton control to send contextual data to a web application hosted in Lync on another computer. To explore further, consider adding the ability to reply with additional contextual data, sent from the web application to a TextBox control in the Lync controls application.

Additional Resources

For more information, see the following resources:

About the Author

John Clarkson is a technical writer with the Microsoft Lync product team.