Part 2: Getting Friends Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility

The Microsoft Outlook Social Connector (OSC) provides a communication hub for personal and professional communications. Just by selecting an Outlook item such as an email or meeting request and clicking the sender or a recipient of that item, users can see, in the People Pane, activities, photos, and status updates for the person on their favorite social networks.

The OSC obtains social network data by calling an OSC provider, which behaves like a translation layer between Outlook and the social network. The OSC provider model is open, and you can develop a custom OSC provider by implementing the required OSC provider extensibility interfaces. To retrieve social network data, the OSC makes calls to the OSC provider through these interface members. The OSC provider communicates with the social network and returns the social network data to the OSC as a string or as XML that conforms to the Outlook Social Connector XML schema. Figure 1 shows the various components of the sample OfficeTalk OSC provider reviewed in this Visual How To.

Figure 1. Relationships of the sample OfficeTalk OSC provider with related components

This Visual How To focuses on returning friend social network data from OfficeTalk. OfficeTalk is not publicly available and is being used as an example of the kind of social network you might want to develop a custom OSC provider for. You can use the techniques to return friend social network data from OfficeTalk to return friend social network data from any social network.

The OfficeTalk provider uses the Outlook Social Connector Provider Proxy Library to simplify the implementation of the OSC provider extensibility interfaces. The OSC Provider Proxy Library implements all of the OSC provider extensibility interface members. These interface members, in turn, call a consolidated set of abstract and virtual methods that provide the social network data that the OSC requires. To create a custom OSC provider that uses the OSC Provider Proxy Library, a developer overrides these abstract and virtual methods with the business logic to communicate with the social network.

The sample solution for this article includes sample code for a custom OSC provider for OfficeTalk. However, this Visual How To does not show all of the code in the sample solution. Instead, it focuses on returning friend social network data from OfficeTalk.

The sample solution contains two projects:

• OSCProvider—This project is an unmodified version of the OSC Provider Proxy Library that is used to simplify the creation of the OfficeTalk OSC provider.

• OfficeTalkOSCProvider—This project includes the source code files that are specific to the OfficeTalk OSC provider.

The OfficeTalkOSCProvider project includes the following source code files:

• OfficeTalkHelper—This class contains helper methods that are used throughout the sample solution.

• OTProvider—This is a partial class that contains the OSC Provider Proxy Library override methods that return information about the OSC provider, information about the social network, and information for the currently logged-on user.

• OTProvider_Activities—This is a partial class that contains the OSC Provider Proxy Library override methods that return activity information.

• OTProvider_Friends—This is a partial class that contains the OSC Provider Proxy Library override methods that return friends information.

The following sections show the procedures to add OSC Provider Proxy Library override methods for friends-related methods in the OTProvider class for the OTProvider_Friends source file.

Creating the OfficeTalk OSC Provider Solution

Reviewing the steps to create a Visual Studio solution for an OfficeTalk OSC provider is outside the scope of this Visual How To. For information about creating a custom OSC provider solution, see Part 1: Developing a Real Outlook Social Connector Provider by Using a Proxy Library.

Creating the OTProvider_Friends Source File

Use the OSC Provider Proxy Library to create a subclass of the OSCProvider class, OTProvider, which represents the sample OSC provider. OTProvider is defined as a partial class so that the logic for OSC provider core methods, friends, and activities can be defined in separate source code files.

The OTProvider_Friends source file extends the OTProvider partial class and contains the override methods for providing OfficeTalk friends information. Add a class named OTProvider_Friends to the OfficeTalkOSCProvider project. Replace the class definition with the following code. The code example starts with the using statements for the OSC Provider Proxy Library and OfficeTalk API. The code example then defines the OTProvider partial class. The OTProvider source file defines inheriting from the OSCProvider class.

using System;
using System.Globalization;
using System.Collections.Generic;

// Using statements for the OSC Provider Proxy Library.
using OSCProvider;
using OSCProvider.Schema;

// Using statements for the social network.
using OfficeTalkAPI;

namespace OfficeTalkOSCProvider
{
    public partial class OTProvider
    {
        ...
    }
}

Allowing for Debugging

To debug the OfficeTalkOSCProvider, you must modify the OfficeTalkOSCProvider project to start using Outlook and register the OfficeTalkOSCProvider as an Outlook Social Connector.

To set up the OfficeTalkOSCProvider project for debugging

The Outlook Social Connector will not call the OfficeTalkOSCProvider until it is registered as an OSC Provider. The sample solution includes a file named RegisterProvider.reg that updates the registry with the entries that are required to register the OfficeTalkOSCProvider as an OSC provider. You can update the registry by opening the RegistryProvider.reg file in Windows Explorer.

The RegisterProvider.reg file assumes that the sample solution is located in the C:\temp directory. If the sample solution is located in a different directory, update the CodeBase entry in the RegisterProvider.reg file to point to the correct location.

Adding Helper Methods

The OfficeTalkHelper class contains helper methods, including the GetOfficeTalkClient and ConvertUserToPerson methods, that are used throughout the sample solution.

The following GetOfficeTalkClient method returns an OfficeTalkClient object that is used to communicate with OfficeTalk. If the OfficeTalkClient has not been initialized, GetOfficeTalkClient creates and configures a new OfficeTalkClient by using the API_URL and API_VERSION constants that are defined in OTProvider.

// Returns a reference to the OfficeTalk client.
private static OfficeTalkClient officeTalkClient = null;
internal static OfficeTalkClient GetOfficeTalkClient()
{
    if (officeTalkClient == null)
    {
        officeTalkClient =
          new OfficeTalkClient(OTProvider.API_URL);
        OfficeTalkClient.UserAgent =
          @"OfficeTalkOSC/" + OTProvider.API_VERSION;
    }
    return officeTalkClient;
}

The ConvertUserToPerson method converts an OfficeTalk User object to an OSC Provider Proxy Library Person object that is usable within the OSC Provider Proxy Library. The ConvertUserToPerson method creates a new OSC Provider Proxy Library Person and then maps the User properties to the related Person properties.

// Converts an Office Talk User to an OSC Provider Proxy Library Person.
internal static Person ConvertUserToPerson(OfficeTalkAPI.OTUser user)
{
    // Create the OSC Provider Proxy Library Person.
    Person person = new Person();

    // Map the User properties to the Person properties.
    person.FullName = user.name;
    person.Email = user.email;
    person.Company = user.department;
    person.UserID = user.id.ToString(CultureInfo.InvariantCulture);
    person.Title = user.title;
    person.CreationTime = user.created_atAsDateTime;

    // FriendStatus is based on whether the user is being followed 
    // by the currently logged-on user.
    person.FriendStatus = 
        user.following ? FriendStatus.friend : FriendStatus.notfriend;

    // Set the PictureUrl if a profile picture is loaded in OfficeTalk.
    if (user.image_url != null)
    {
        person.PictureUrl = new Uri(OTProvider.API_URL + user.image_url);
    }

    // WebProfilePage is set to the user's home page in OfficeTalk.
    person.WebProfilePage = 
        OTProvider.API_URL + @"/Home/index/" + user.alias + "#User";

    return person;
}

Overriding the GetPeopleDetails Method

The OfficeTalk OSC provider in the sample solution supports hybrid synchronization of friend social network data. With hybrid synchronization, the OSC calls the ISocialSession2.GetPeopleDetails method to return person and picture details for each person displayed in the People Pane.

To support the ISocialSession2.GetPeopleDetails method, the OSC Provider Proxy Library provides a GetPeopleDetails virtual method that you can override to return information from the social network. The GetPeopleDetails virtual method returns people information as a list of friends to match the format that the OSC requires.

The OSC calls the ISocialSession2.GetPeopleDetails method with a list of the people who are displayed in the People Pane. Each person can have multiple email addresses, and the email addresses will be hashed.

The GetPeopleDetails override method shown in the following code completes these steps:

1. It first gets an OfficeTalkClient object to communicate with OfficeTalk.

2. The GetPeopleDetails override method then calls the OfficeTalk GetUserFromHash method for each email address.

3. If the GetPeopleDetails override method finds an OfficeTalk User by using the email address, it calls the ConvertUserToPerson helper method to convert the OfficeTalk User to a Person that can be used within the OSC Provider Proxy Library.

4. After the conversion is complete, the GetPeopleDetails override method sets the Person.Index property to the same index value that the person had in the list of people that was passed into the method. The friends collection returned to the OSC will include only people who exist in the social network. The GetPeopleDetails override method sets the Person.Index property to allow the OSC to identify which person the social network data is for.

public override Friends GetPeopleDetails(HashedAddresses hashedAddresses)
{
    Friends returnValue = new Friends();

    if (hashedAddresses != null)
    {
        // Get a client for interacting with OfficeTalk.
        OfficeTalkClient otClient = OfficeTalkHelper.GetOfficeTalkClient();

        // For each person in the HashedAddresses collection.
        foreach (PersonAddresses addresses in hashedAddresses.PersonAddresses)
        {
            // For each email address assigned to the person.
            foreach (string hashedEmail in addresses.HashedAddresses)
            {
                OTUser otUser = 
                    otClient.GetUserFromHash(hashedEmail, Format.JSON);

                // If a user was found, add them to the list of people.
                if (otUser != null)
                {
                    Person p = OfficeTalkHelper.ConvertUserToPerson(otUser);

                    // Set the index value for the person to the same index 
                    // position they had in the hashedAddresses list.
                    p.Index = addresses.Index;

                    returnValue.People.Add(p);
                    break;
                }
            }
        }
    }
    return returnValue;
}

Overriding the GetFriends Method

The OSC ISocialPerson and ISocialProfile interfaces contain members that are dependent on the currently logged-on user's friends on the social network. The OSC Provider Proxy Library provides the GetFriends abstract method, which you can override to return friends information from the social network. The OSC Provider Proxy Library limits how often the social network is contacted by storing this list of friends internally. This internal list of friends will be refreshed after 30 minutes.

The GetFriends override method shown in the following code completes these steps:

1. It gets an OfficeTalkClient object to communicate with OfficeTalk.

2. The GetFriends override method then calls the OfficeTalk GetFollowing method to obtain all OfficeTalk users who are friends of the current user.

3. The GetFriends override method calls the OfficeTalkHelper ConvertUserToPerson method to convert each OfficeTalk user who is a friend of the current user to a Person that can be used within the OSC Provider Proxy Library.

4. After the conversion is complete, the GetFriends override method sets the Person.FriendStatus property. The OSC uses the Person.FriendStatus property to identify whether a particular person is a friend of the current user.

public override Friends GetFriends()
{
    Friends returnValue = new Friends();

    // Get a client for interacting with OfficeTalk.
    OfficeTalkClient otClient = OfficeTalkHelper.GetOfficeTalkClient();

    // Get the list of users whom the currently logged-on user is following.
    List<OTUser> following =
      otClient.GetFollowing(System.Environment.UserName, Format.JSON);

    // Convert the OfficeTalk Users to OSC People and set 
    // their FriendStatus property.
    foreach (OTUser otUser in following)
    {
        Person p = OfficeTalkHelper.ConvertUserToPerson(otUser);
        p.FriendStatus = FriendStatus.friend;
        returnValue.People.Add(p);
    }
    return returnValue;
}

Overriding the FollowPersonEx Method

The OSC ISocialSession and ISocialSession2 interfaces contain methods to add a person as a friend of the currently logged-on user in the social network. Because the OSC Provider Proxy Library implements the ISocialSession2 interface, the OSC calls the ISocialSession2.FollowPersonEx method instead of the ISocialSession.FollowPerson method.

The OSC Provider Proxy Library provides the FollowPersonEx virtual method, which you can override to add a person as a friend of the current user in the social network.

The FollowPersonEx override method shown in the following code completes these steps:

1. It first verifies that email addresses for the person have been passed in.

2. If there are email addresses, the FollowPersonEx override method gets an OfficeTalkClient object to communicate with OfficeTalk.

3. The FollowPersonEx override method then hashes each of the email addresses passed in for the person and calls the OfficeTalk GetUserFromHash method to look up the OfficeTalk user.

4. If the FollowPersonEx method finds an OfficeTalk user and the user is not already a friend, it calls the OfficeTalk Follow method to mark the user as being a friend of the current user.

public override void FollowPersonEx(
    string[] emailAddresses, 
    string displayName)
{
    // Verify that email addresses have been passed in.
    if (emailAddresses == null || emailAddresses.Length == 0)
    {
        return;
    }

    // Get a client for interacting with OfficeTalk.
    OfficeTalkClient otClient = OfficeTalkHelper.GetOfficeTalkClient();

    // Try to find a user based on one of the email addresses.
    foreach (string emailAddress in emailAddresses)
    {
        // Hash the Email address to find the user in OfficeTalk.
        string hashedEmailAddress =
          OSCProvider.Helpers.Hash(emailAddress, HashFunction.SHA1);

        OTUser otUser = otClient.GetUserFromHash(hashedEmailAddress, Format.JSON);

        // If the user was found and is not already being followed, 
        // call the OfficeTalk API to mark the user as being followed.
        if (otUser != null && !otUser.following)
        {
            otClient.Follow(otUser.alias, Format.JSON);
            return;
        }
    }
}

Overriding the UnFollowPerson Method

The OSC ISocialSession interface contains the UnFollowPerson method to remove a person as a friend of the currently logged-on user in the social network.

The OSC Provider Proxy Library provides the UnFollowPerson virtual method, which you can override to remove a person as a friend of the current user in the social network.

The UnFollowPerson override method shown in the following code completes these steps:

1. It gets an OfficeTalkClient object to communicate with OfficeTalk.

2. Removing a user as a friend in OfficeTalk requires the user's alias and not the user ID passed by the OSC. To find the OfficeTalk user, the UnFollowPerson override method calls the OfficeTalk GetFollowing method to obtain all OfficeTalk users who are friends of the currently logged-on user.

3. For each of these OfficeTalk users, the UnFollowPerson override method checks to see whether the OfficeTalk ID matches the userID passed in by the OSC.

4. If the UnFollowPerson override method finds a match, it calls the OfficeTalk UnFollow method with the user's alias to remove the user as a friend of the current user.

public override void UnFollowPerson(string userID)
{
    // Get a client for interacting with OfficeTalk.
    OfficeTalkClient otClient = OfficeTalkHelper.GetOfficeTalkClient();

    // OfficeTalk does not support finding a user by the userID.
    // Search for the userID in the list of OfficeTalk users being 
    // followed by the currently logged-on user.
    List<OTUser> following = 
        otClient.GetFollowing(System.Environment.UserName, Format.JSON);

    // Find the OfficeTalk User by using the userID.
    foreach (OTUser otUser in following)
    {
        if (otUser.id.ToString() == userID)
        {
            // If the user is found, call the OfficeTalk API to unmark
            // the user as being followed.
            otClient.UnFollow(otUser.alias, Format.JSON);
            break;
        }
    }
}

Overriding OSC Provider Proxy Library Core Methods

A custom OSC Provider that uses the OSC Provider Proxy Library must override the abstract and virtual methods for returning information about the OSC provider, the social network capabilities, and the current user. In the sample solution, the overrides for these OTProvider methods are located in the OTProvider source file.

The core abstract and virtual methods are as follows:

• GetProviderData—Returns information about the OSC provider capabilities and information about the social network.

• GetMe—Returns information about the current user.

Reviewing these methods is outside the scope of this Visual How To. For more information, see Part 1: Developing a Real Outlook Social Connector Provider by Using a Proxy Library.

Overriding OSC Provider Proxy Library Activity Methods

A custom OSC Provider that uses the OSC Provider Proxy Library must override the abstract and virtual methods for returning activity social network data. In the sample solution, the overrides for these OTProvider methods are located in the OTProvider_Activities source file.

There is only one method to override for activities:

• GetActivities—Returns activities for all users who are identified by the email addresses that are passed into the method.

Covering these methods in detail is outside of the scope of this Visual How To. For more information about returning activities social network data, see Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility.

Creating a custom Outlook Social Connector (OSC) provider for a social network is a straightforward process of implementing the OSC Provider extensibility interfaces to return social network data. The OSC Provider Proxy Library simplifies this process by removing the requirement to implement each individual interface member. Instead the OSC Provider Proxy Library defines a consolidated set of abstract and virtual methods to provide social network data. The developer of the OSC provider can focus on overriding these methods with the business logic required to interface with the social network API.

The sample solution for this Visual How To includes sample code for a custom OSC provider for OfficeTalk. This Visual How To does not cover all of the code in the sample solution. This Visual How To focuses on returning friends social network data from OfficeTalk. The social network data that the OfficeTalk provider returns is shown in Figure 2.

Figure 2. OSC showing OfficeTalk social network data in the People Pane

For more information about creating the OfficeTalk OSC provider, see Part 1: Developing a Real Outlook Social Connector Provider by Using a Proxy Library.

For more information about returning activities social network data, see Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility.

Length: 13:46

Grab the Code

• Part 1: Developing a Real Outlook Social Connector Provider by Using a Proxy Library

• Part 3: Getting Activities Information by Using the Proxy Library for Outlook Social Connector Provider Extensibility

• Part 4: Building an Installation Package for a Real Outlook Social Connector Provider

• Outlook Social Connector 1.1 Provider Reference

• Getting Started with Developing an Outlook Social Connector Provider

• Getting Friends Information

• Outlook Social Connector Provider Proxy Library

• OfficeTalk

• Outlook Sample: Outlook Social Connector Provider

• Outlook Developer Center