Export (0) Print
Expand All

Sample: Create a mail app to display in Outlook hierarchy information from Active Directory

apps for Office

Learn from this prototype sample mail app how to access basic hierarchy information from Active Directory. Extend this prototype to customize the mail app for your organization.

Last modified: February 17, 2014

Applies to: Exchange Online | Exchange Server 2013 | Outlook 2013 | Outlook 2013 RT | Outlook Web App | OWA for Devices

   Office.js: v1.0

   Apps for Office manifests schema: v1.0

Based on a code sample provided by: Trang Luu, Microsoft Corporation

When you select an email message in Outlook or Outlook Web App, you can choose the Who’s Who AD mail app to display Active Directory information about the sender and other recipients. The mail app appears in the app bar when you are viewing an email in the Reading Pane or in the mail inspector.

When you open this mail app, it retrieves and displays the sender’s detailed professional and hierarchical information from Active Directory—name, job title, department, alias, office number, telephone number, and a profile picture. If the sender has a manager or direct reports, the mail app also displays the name, job title, and number of direct reports, if applicable, for each of them. Figure 1 shows an example of the Who’s Who AD app. The figure displays information for Belinda Newman, her manager Alicia Thornber, and some of her direct reports (Ben Miller, Jeff Price, and Robin Wood). The mail app allows you to scroll to view all the direct reports.

Figure 1. Who’s Who AD mail app displaying Active Directory information for the message sender

Who's Who AD mail app in Outlook app pane

The mail app provides a navigation bar that allows you to choose a recipient and view detailed professional and hierarchy information that is stored in Active Directory. You can also choose any manager or direct report and in turn view that person’s details and hierarchy information.

Behind the scenes, when you select a sender or recipient, the mail app calls a web service, named Who, to get that person’s data from Active Directory. The web service includes an Active Directory wrapper, which uses Active Directory Domain Services (AD DS) to access information from Active Directory. After getting the data, the Who web service serializes the data in JSON format and sends it back as the web service response. The mail app then pulls the data and displays it in the app pane. Figure 2 summarizes the relationships among the Outlook user, mail app, Who web service, and Active Directory. Notice that the Who’s Who AD mail app and the Who web service are on the same domain hosted on the same web server.

Figure 2. Relationships among the Outlook user, mail app, Who web service, and Active Directory

Relationships between the user, mail app and AD.
Note Note

The Who web service serves only as a prototype and shows a few basic features of Active Directory that are familiar to most Active Directory users. Hopefully this example provides a good starting point for you to extend and support features that are specific to your organization. For more information, see the section Future extension.

This topic assumes that you have experience in web development using HTML and JavaScript, and familiarity with Windows Communication Foundation (WCF) web services. It does not assume prior knowledge in AD DS.

The following are requirements to install and run any mail app, including the Who's Who AD mail app:

  • The user's mailbox must be on Exchange Server 2013 or a later version.

  • The mail app must run on Outlook 2013 or a later version, or Outlook Web App.

You can use any web development tool that you’re familiar with to extend the Who’s Who AD mail app.

The following tools were used to develop the Who web service, and to deploy the Who’s Who AD mail app and web service:

  • Visual Studio 2012

  • .NET Framework 4.0

  • Windows Server 2008

  • Internet Information Server (IIS) 7.5

This section describes the XML manifest and HTML files of the Who’s Who AD mail app. It covers only points of interest that are specific to this mail app. For general information about creating mail apps, see Mail apps for Outlook.

XML manifest

An XML manifest defines the following metadata for an app for Office:

  • Identity.

  • Capability required of the host application.

  • Form factors.

  • Corresponding HTML file for possibly each form factor.

  • Display requirements.

  • Necessary permissions.

  • Activation rules.

The manifest uses the OfficeApp element as the root element to enclose various child elements of the MailApp complex type in a sequential order. This section highlights a few areas of interest in the manifest that characterize the Who’s Who AD app.

  • The type of this app—The OfficeApp element in the following XML line specifies that this app is of the MailApp complex type, which extends the base complex type OfficeApp.

    <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="MailApp">
    
  • The identifier of the app—The Id element in the following XML line uniquely identifies and differentiates this app from other apps for Office.

    <Id>69CC567C-6737-4C49-88DD-123334574567</Id>
    
  • The label on the app button—The DisplayName element in the following XML line specifies "Who’s Who AD" as the label. Outlook displays the app button in the app bar if the current item in Outlook satisfies the activation conditions, as specified in the manifest.

    <DisplayName DefaultValue="Who’s Who AD"/>
    
  • A verbose description for the app—In the next set of XML lines, the Description element is a summary description for what the mail app does. It contains a DefaultValue attribute that typically describes the purpose of the app. The DefaultValue attribute corresponds to the en-us locale specified by the DefaultLocale element. For information about supporting multiple locales, see Designing an app for Office for specific locales.

      <DefaultLocale>en-US</DefaultLocale> 
    
      <Description DefaultValue="Show people and their organizations 
        using data from Active Directory. Corp Net or Direct Access 
        connection is required to use this mail app."/>
    
  • The icon image—The IconUrl element provides a URL to an image that represents the logo of the app in the Exchange Admin Center (EAC).

      <IconUrl DefaultValue="https://webserver/WhosWhoAD/img/app_icon.png"/> 
    
    

    If you intend to extend and create a new version of the app, see How to: Create an effective Office Store listing for your app for Office or SharePoint for information about effectively creating a description and icon to market the app.

  • The capabilities that this app requires of a host application—The Capabilities element includes one Capability element in the following XML lines. This means the app requires only one capability, the Mailbox capability. An application that supports the Mailbox capability can become a host application for this app.

    <Capabilities>
      <Capability Name="Mailbox"/>
    </Capabilities>
    
  • The form factors supported by this app, the corresponding location of the HTML file, and the default display height, in pixels—The DesktopSettings element in the following XML lines specifies that this app supports the desktop form factor. The corresponding SourceLocation element specifies that Outlook can obtain the WhoMailApp.html file at https://webserver/WhosWhoAD/WhoMailApp.html. The corresponding RequestedHeight element specifies that Outlook should try to display an app pane that is 260 pixels high on the desktop by default.

    Note Note

    Before you run this app, you should replace the URL for the HTML file, https://webserver/WhosWhoAD/WhoMailApp.html, with the actual location of the HTML file in your configuration.

     <DesktopSettings> 
      <SourceLocation DefaultValue="https://webserver/WhosWhoAD/WhoMailApp.html"/> 
      <RequestedHeight>260</RequestedHeight> 
     </DesktopSettings>
    
    
  • The permission requested by this app—The Permissions element in the following XML line specifies that this app needs the read item permission. As seen in the next bullet point, this app needs this permission to use regular expressions in its activation rules.

    <Permissions>ReadItem</Permissions>
    
  • The activation rule—This app specifies a composite rule related by an And operation. The first rule is of the ItemIs complex type with the ItemType attribute of Message. The second rule is of the ItemHasRegularExpressionMatch complex type, and specifies a regular expression, named addressMatches. This composite rule looks for the existence of the "@" character in the sender’s SMTP address of the selected email, meeting request, meeting response, or meeting cancellation item.

      <Rule xsi:type="RuleCollection" Mode="And">
        <Rule xsi:type="ItemIs" ItemType="Message" />
        <Rule xsi:type="ItemHasRegularExpressionMatch" RegExValue="@" 
          RegExName="addressMatches" PropertyName="SenderSMTPAddress" />
      </Rule>
    
    

See Appendix A: XML manifest for a complete listing of the XML manifest.

HTML and JavaScript implementation

Each mail app must implement an event handler for the Office.initialize event, which occurs when the runtime environment is loaded. In the initialize event handler of the Who’s Who AD app, the mail app gets the currently selected email message in _mailboxItem. It ensures that the DOM is loaded before proceeding to do more on the app pane. Because this mail app activates only for mail messages, _mailboxItem is always a Message object.


Office.initialize = function () {
try {
    _mailboxItem = Office.context.mailbox.item;
    // Check for the DOM to load before proceeding.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        AddContactsToNavBar();
        });
    }
    catch (err) {
        ShowErrorMessage();
    }
}

The AddContactsToNavBar function uses the sender, to, and cc properties of the Message object to initialize the navigation bar with thumbnail pictures and primary SMTP addresses of the sender and recipients. The function also calls FindPerson to initially get and display details for the sender.

function AddContactsToNavBar() {
    AddContactToNavBar(_mailboxItem.sender.emailAddress);

    for (var index in _mailboxItem.to) {
        AddContactToNavBar(_mailboxItem.to[index].emailAddress);
    }

    for (var index in _mailboxItem.cc) {
        AddContactToNavBar(_mailboxItem.cc[index].emailAddress);
    }

    // Format each thumbnail picture.
    $('#contactBar img').each(function () {
        $(this).addClass(this.width > this.height ? 'landscape' : 'portrait');
    });
    // Get and display information about the sender by passing 
    // the sender's primary SMTP address.
    FindPerson(_mailboxItem.sender.emailAddress);
}

When you choose a person on the navigation bar, the mail app identifies the person with his or her primary SMTP address. The FindPerson function does the following to display the person’s details and hierarchy information:

  1. Uses AJAX to call the FindPerson web operation, passing the operation the primary SMTP address of the selected person.

  2. Gets the Active Directory data of the selected person in JSON as the web response.

  3. Parses the JSON to form a PersonContext object. This object consists of details for the selected person, and information for the person’s manager and any direct reports, as stored in Active Directory.

  4. Calls UpdateLayout to appropriately adjust and display the HTML on the app pane.

The Who web service is a Windows Communication Foundation (WCF) web service that takes the primary SMTP address of a person as input, accesses AD DS to get details and hierarchy information about that person, and returns the data in JSON format in the web service response. For simplicity and to avoid cross-domain issues, the Who’s Who AD mail app and the Who web service are hosted on the same web server.

The Who web service consists of the following components:

  • IWhoService interface.

  • WhoService class.

  • Active Directory wrapper, which consists of the ActiveDirectorySource and ActiveDirectorySearcher classes.

Figure 3 describes the interactions of the Who web service with the Who’s Who AD mail app and with Active Directory, and interactions among the components within the web service.

Figure 3. Interactions with and within the Who web service

Interactions within components of the web service.

IWhoService interface

This interface specifies the service contract for the Who web service. This service contract specifies the FindPerson operation, which takes an emailAddress as input and returns a PersonContext in JSON format as a web service response.

namespace Service.Who
{
    [ServiceContract(Name = "WhoService", Namespace = "Service.Who")]
    public interface IWhoService
    {
        [OperationContract]
        [WebInvoke(Method = "GET",
            UriTemplate = "/FindPerson?emailAddress={emailAddress}",
            ResponseFormat = WebMessageFormat.Json
        )]
        Data.ActiveDirectory.PersonContext FindPerson(string emailAddress);
    }
…
}

WhoService class

The WhoService class implements the service contract specified by the IWhoService interface. It provides a FindPerson method, which calls into the Active Directory wrapper to get a PersonContext object for the specified person, and then returns the object as a web response. See Step A in Figure 3.

Active Directory wrapper

The ActiveDirectorySource and ActiveDirectorySearcher classes form an Active Directory wrapper allowing the Who web service to access AD DS by using the LDAP provider. The Active Directory wrapper makes the actual call to AD DS to get the detailed professional and hierarchical information for the specified person from Active Directory, and returns the information in a PersonContext object.

ActiveDirectorySource class

This class exposes the FindPersonContextBySMTPAddress method to the WhoService class, which calls AD DS and also returns a PersonContext object for the specified email address. This PersonContext object contains detailed professional and hierarchical information for that email address. This is illustrated by Step B in Figure 3.

The class contains a helper method, FindPersonByDistinguishedName, which also calls AD DS and returns a Person object for a specified person.

ActiveDirectorySearcher class

This class exposes a PersonFromSearchResult method that takes a SearchResult object as input, extracts the data, and creates and returns a Person object. This is shown as part of Step D in Figure 3.

Getting and returning the Active Directory data

This section describes how the Active Directory wrapper gets and returns detailed professional and hierarchical data for the chosen person.

First, the common data structures—The Active Directory wrapper defines the Person class, which represents the data that the Who’s Who AD mail app attempts to get from Active Directory.

[Serializable]
public class Person
{
    public string Alias;

    public string FirstName;
    public string LastName;
    public string DisplayName;

    public string EmailAddress;
    public string Title;
    public string Office;
    public string Telephone;

    public int DirectsCount;
    public string Department;

    [XmlIgnore]
    public string DistinguishedName;

    [XmlIgnore]
    public string Manager;

    [XmlIgnore]
    public List<string> Directs;

    [XmlIgnore]
    public byte[] ThumbnailPhoto;
…
}

The members of this class correspond to the list of LDAP display names, AdProperties, which represents the properties to get from Active Directory for each filter result.

protected static readonly string[] AdProperties = new[]
{
    "mailnickname", "displayname", "mail", "givenname", "sn", 
    "telephoneNumber", "title", "physicalDeliveryOfficeName",
    "department", "distinguishedname", "manager", "directreports",
    "thumbnailphoto"
};

The following describes how the Active Directory wrapper works:

  1. First calling of AD DS for the chosen person

    The Active Directory wrapper method, FindPersonContextBySMTPAddress, loads AdProperties, and specifies the LDAP filter for the search. Because the input parameter is the primary SMTP address of the chosen person, the LDAP filter uses the proxyAddresses=smtp: attribute string. This method then calls the AD DS FindOne() method to get data for the chosen person from Active Directory. FindOne returns the data in a SearchResult object. This is illustrated as Step C in Figure 3.

    public class ActiveDirectorySource : ActiveDirectorySearcher
    {
        /// <summary>
        /// Finds the person context by searching in Active Directory 
        /// given the SMTP address.
        /// </summary>
        /// <param name="SMTPAddress">The SMTP address.</param>
        /// <returns>PersonContext object or null if not found.</returns>
        public PersonContext FindPersonContextBySMTPAddress(string SMTPAddress)
        {
            PersonContext context = null;
    
            if (!string.IsNullOrWhiteSpace(SMTPAddress))
            {
                // Specify AdProperties as the properties to retrieve 
                // from Active Directory during the search.
                this.Ds.PropertiesToLoad.Clear();
                this.Ds.PropertiesToLoad.AddRange(AdProperties);
    
                // Set the LDAP format filter string, because we're using LDAP as the
                // service provider for Active Directory Domain Services.
                this.Ds.Filter = "(&(proxyaddresses=smtp:" + SMTPAddress + 
                    ")(objectcategory=Person))";
    
                // Execute search in Active Directory and
                // get the first SearchResult object.
                SearchResult result = this.Ds.FindOne();
    
                // Create and initialize Person object from the 
                // SearchResult object.
                Person person = this.PersonFromSearchResult(result);
    ...
    }
    
  2. Getting a Person object for the chosen person

    FindPersonContextBySMTPAddress then calls an Active Directory wrapper helper method, PersonFromSearchResult, to get a Person object based on the SearchResult object returned by FindOne. This is illustrated as Step D in Figure 3.

    /// <summary>
    /// Create Person object from search result.
    /// </summary>
    /// <param name="result">The result.</param>
    /// <returns>Person object or null</returns>
    protected Person PersonFromSearchResult(SearchResult result)
    {
        if (result == null)
        {
            return null;
        }
    
        var person = new Person
        {
            DisplayName = GetResultProperty(result, "displayname"),
            EmailAddress = GetResultProperty(result, "mail"),
            FirstName = GetResultProperty(result, "givenname"),
            LastName = GetResultProperty(result, "sn"),
            Telephone = GetResultProperty(result, "telephoneNumber"),
            Title = GetResultProperty(result, "title"),
            Alias = GetResultProperty(result, "mailnickname"),
            Office = GetResultProperty(result, 
                "physicalDeliveryOfficeName"),
            Department = GetResultProperty(result, "department"),
            DistinguishedName = GetResultProperty(result, 
                "distinguishedname"),
            Manager = GetResultProperty(result, "manager"),
            Directs = null,
            ThumbnailPhoto = null
        };
    
        person.ThumbnailPhoto = ThumbnailFromSearchResult(result);
        if (person.ThumbnailPhoto != null)
        {
            // Encoded thumbnail to be used in data:image/jpg;base64.
            person.EncodedThumbnail = 
                Convert.ToBase64String(person.ThumbnailPhoto);
        }
    
        person.DirectsCount = (result.Properties["directreports"] 
            != null) ? result.Properties["directreports"].Count : 0;
        if (person.DirectsCount > 0)
        {
            person.Directs = new List<string>(person.DirectsCount);
            for(int i = 0; i < person.DirectsCount; i++)
            {
                person.Directs.Add(
                    result.Properties["directreports"][i].ToString());
            }
         }
    
         return person;
    }
    
  3. Determining any hierarchy for the chosen person

    Based on the chosen person’s Active Directory information, if there is a manager and any direct reports, this method further calls FindPersonByDistinguishedName to get data for each person from Active Directory.

  4. Subsequent calling of AD DS for each person in the hierarchy

    Given the distinguished name of a manager or direct report, FindPersonByDistinguishedName loads AdProperties before calling the AD DS DirectorySearcher.FindOne method to get data for that person from Active Directory. This is illustrated as Step C in Figure 3.

  5. Getting a Person object for each person in the hierarchy

    FindPersonByDistinguishedName then calls PersonFromSearchResult to return the Active Directory data in a Person object. This is illustrated as Step D in Figure 3.

    /// <summary>
    /// Finds the person by searching in Active Directory given
    /// the distinguished name.
    /// </summary>
    /// <param name="distinguishedName">The distinguished name.</param>
    /// <returns>Person object or null if not found.</returns>
    protected Person FindPersonByDistinguishedName(string distinguishedName)
    {
        Person person = null;
    
        if (!string.IsNullOrWhiteSpace(distinguishedName))
        {
            // Specify AdProperties as the properties to retrieve 
            // from Active Directory during the search.
            this.Ds.PropertiesToLoad.Clear();
            this.Ds.PropertiesToLoad.AddRange(AdProperties);
    
            // Set the LDAP format filter string, because we're
            // using LDAP as the service provider 
            // for Active Directory Domain Services.
            this.Ds.Filter = "(&(distinguishedname=" + 
                EscapeLdap(distinguishedName) + ")
                (objectcategory=Person))";
    
            // Execute search in Active Directory and 
            // get the first SearchResult object.
            SearchResult result = this.Ds.FindOne();
    
            // Create and initialize Person object from the 
            // SearchResult object.
            person = this.PersonFromSearchResult(result);
        }
    
        return person;
    }
    
  6. Packing Person objects to return a PersonContext object for the chosen person

    The FindPersonContextBySMTPAddress method creates a PersonContext object that contains the Person objects for the chosen person and any manager and direct reports. It then returns a PersonContext object to the FindPerson web service operation. This is illustrated as Step B in Figure 3. The entire FindPersonContextBySMTPAddress method is listed in the following code for clarity.

    public class ActiveDirectorySource : ActiveDirectorySearcher
    {
        /// <summary>
        /// Finds the person context by searching in Active Directory 
        /// given the SMTP address.
        /// </summary>
        /// <param name="SMTPAddress">The SMTP address.</param>
        /// <returns>PersonContext object or null if not found.</returns>
        public PersonContext FindPersonContextBySMTPAddress(string SMTPAddress)
        {
            PersonContext context = null;
    
            if (!string.IsNullOrWhiteSpace(SMTPAddress))
            {
                // Specify AdProperties as the properties to retrieve 
                // from Active Directory during the search.
                this.Ds.PropertiesToLoad.Clear();
                this.Ds.PropertiesToLoad.AddRange(AdProperties);
    
                // Set the LDAP format filter string, because we're using LDAP as the
                // service provider for Active Directory Domain Services.
                this.Ds.Filter = "(&(proxyaddresses=smtp:" + SMTPAddress + 
                    ")(objectcategory=Person))";
    
                // Execute search in Active Directory and
                // get the first SearchResult object.
                SearchResult result = this.Ds.FindOne();
    
                // Create and initialize Person object from the 
                // SearchResult object.
                Person person = this.PersonFromSearchResult(result);
    
            if (person != null)
            {
                context = new PersonContext
                {
                    Person = person,
                    Manager = null,
                    Directs = null
                };
    
                // Find this person's manager.
                if (!string.IsNullOrWhiteSpace(context.Person.Manager))
                {
                    context.Manager = 
                        FindPersonByDistinguishedName 
                        (context.Person.Manager);
                }
    
                // Find this person's direct reports.
                if (context.Person.DirectsCount > 0)
                {
                    context.Directs = new 
                       List<Person>(context.Person.DirectsCount);
    
                    foreach (string direct in 
                        context.Person.Directs)
                    {
                        context.Directs.Add
                           (FindPersonByDistinguishedName(direct));
                    }
                }
            }
    
        return context;
    }
    

This section describes how to install the Who’s Who AD mail app and deploy the Who web service.

The deployment described in this section requires the following:

  • Visual Studio 2012 or later.

  • .NET Framework 4.0 or later.

  • Windows Server 2008 or later.

  • Internet Information Server (IIS) 7.5 or later on the web server.

Obtaining and configuring the code files

You can download the source code files for the Who’s Who AD mail app and Who web service at Mail apps for Outlook: Display hierarchy information from Active Directory.

Use the following steps to put the files in the necessary locations and modify their references as appropriate:

  1. On a local drive d:, create a folder called WhosWhoAD, and download the files there.

  2. Assuming the IIS web server you intend to host the Who’s Who AD mail app is called webserver, create a folder called WhosWhoAD under \\webserver\c$\inetpub\wwwroot\.

  3. Copy the img folder and its contents from d:\WhosWhoAD\WhoAgave\ to \\webserver\c$\inetpub\wwwroot\WhosWhoAD\.

    The remaining mail app and web service files will be appropriately copied to webserver when you deploy the web service, as described in the section Deploying the web service later in this article.

  4. Update the manifest file to reflect the actual location of the mail app HTML file.

    The mail app manifest file, manifest.xml, is directly under d:\WhosWhoAD. If your actual web server has a different name than webserver, update manifest.xml to reflect the actual location of the WhoMailApp.html file, by replacing webserver in the following line with the server path of the WhosWhoAD folder you created in Step 2.

    <SourceLocation DefaultValue="https://webserver/WhosWhoAD/WhoMailApp.html"/>
    

As part of the download, you will find the following source files that pertain to the Who’s Who AD mail app:

  • manifest.xml

  • WhoAgave\css\WhoMailApp.css

  • WhoAgave\img\anonymous.jpg

  • WhoAgave\img\app_icon.png

  • WhoAgave\img\envelop.png

  • WhoAgave\img\telephone.png

  • WhoAgave\WhoMailApp.html

Notice that the Who’s Who AD mail app also requires the following files and obtains them from hosted locations:

  • Office.js and related library and string files—accessed from the Content Delivery Network (CDN) at https://appsforoffice.microsoft.com/lib/1.0/hosted/.

  • jQuery-1.7.1.min.js—accessed from the CDN at https://ajax.aspnetcdn.com/ajax/jQuery/.

The rest of the files in the download pertain to the Who web service, including the Active Directory wrapper.

Installing the mail app

The following procedure describes how to use the Outlook rich client and the EAC to install the Who’s Who AD mail app. The procedure to install an app from Outlook Web App using the EAC is similar, once you are in the EAC as shown in Step 3 in the following procedure. You need to install the mail app only once on either client. Once the mail app is installed, you can use it on the same Exchange mailbox in the Outlook rich client and Outlook Web App.

Note Note

This procedure is applicable only if your Outlook account is on Exchange 2013 or a later version.

Also, in Step 3, if you do not see Add from file as an option, you need to request that your Exchange administrator provide the necessary permissions for you.

The Exchange administrator can run the following PowerShell cmdlet to assign the necessary permissions for a single user. In this example, wendyri is the user’s email alias.

New-ManagementRoleAssignment -Role "My Custom Apps" -User "wendyri"

If necessary, the administrator can run the following cmdlet to assign similar permissions for multiple users:

$users = Get-Mailbox *

$users | ForEach-Object { New-ManagementRoleAssignment -Role "My Custom Apps" -User $_.Alias}

For more information about the My Custom Apps role, see My Custom Apps role.

  1. In the Outlook rich client, choose File, Manage Apps.

    This opens a browser for you to log on to Outlook Web App to go to the EAC.

  2. Log on to your Exchange account.

  3. In the EAC, select the drop-down box that is adjacent to the + button, and then choose Add from file, as shown in Figure 4.

    Figure 4. Installing a mail app from a file in the Exchange Admin Center

    Installing an app from a file
  4. In the add from file dialog box, browse to the location of manifest.xml in d:\WhosWhoAD, choose Open, and then choose Next.

    You should then see the Who’s Who AD app in the list of apps for Outlook, as shown in Figure 5.

    Figure 5. Who’s Who AD app installed on the Exchange Admin Center

    Who's Who AD mail app installed in EAC.
  5. If Outlook is running, close and reopen Outlook.

    Outlook reads manifest files of installed mail apps only on startup. So if you install a mail app while Outlook is running, you should restart Outlook so that Outlook is aware of the new mail app.

Deploying the web service

This section uses Visual Studio to deploy the web service to an IIS web server named webserver, under a folder named WhosWhoAD. Do the following to deploy the Who web service and WhoMailApp.html mail app file:

  1. In Visual Studio, open WhoWebService.csproj.

  2. Choose Build, Publish WhoWebService.

  3. In the Profile tab of the Publish Web dialog box, specify a profile of your choice.

  4. In the Connection tab, choose File System as the Publish method.

  5. Type \\webserver\c$\inetpub\wwwroot\WhosWhoAD as the Target location.

  6. Choose Publish.

  7. On the webserver computer, start IIS Manager.

  8. In the Connections pane, choose Sites, Default Web Site.

  9. Choose the WhosWhoAD folder, and choose Convert to Application.

  10. In the Add Application dialog box, under Application pool with the DefaultAppPool listed by default, choose Select.

  11. In the Select Application Pool dialog box, under Properties, ensure that .Net Framework Version: 4.0 or a later version of the .NET Framework is displayed. Choose a different application pool, if necessary, to ensure that the pool uses at least .NET Framework 4.0. Choose OK.

  12. In the Add Application dialog box, ensure that you see Pass-through authentication, as shown in Figure 6. Choose OK. Proceed to Step 14.

    Figure 6. Add Application dialog box to convert the Who web service as an application in the appropriate application pool on IIS

    IIS Add Application dialog box.
  13. As an alternative to steps 10 through 12, you can create a new application pool that uses .NET Framework 4.0 (or a later version) and pass-through authentication. Select that application pool and proceed to Step 14.

  14. In the middle pane of the IIS Manager, choose Authentication. Verify that Windows Authentication is enabled; choose it to enable it, if necessary.

The deployment procedure copies the following files to \\webserver\c$\inetpub\wwwroot\WhosWhoAD\:

  • bin\ActiveDirectoryWrapper.dll

  • bin\WhoWebService.dll

  • css\WhoMailApp.css

  • img\anonymous.jpg

  • img\app_icon.png

  • img\envelop.png

  • img\telephone.png

  • Web.config

  • WhoMailApp.html

  • WhoService.svc

The Who web service can now be accessed on webserver, and you can now use the Who’s Who AD mail app in Outlook or Outlook Web App.

This example shows the basic technique of connecting a mail app with a web service that calls AD DS to display professional and hierarchy information for the sender and recipients on an email message. The example is intended to be a prototype for interested developers to further customize the solution for their needs. This section suggests a few areas of further extension.

Displaying distinct thumbnails in navigation bar

The navigation bar of the mail app displays a list of the sender and recipients of the selected email, from which you can choose to display one person’s details and hierarchical information as stored in Active Directory. Currently, the navigation bar displays the same generic thumbnail for each person, as implemented in the following AddContactToNavBar function:

function AddContactToNavBar(contactEmail) {
    // Enhancement opportunity: reorganize code to get and 
    // display person's picture in navigation bar.
    // Store the SMTP address as data-id.
    $('#contactBar').append('<div class="contact contactPreview" 
        data-id="' + contactEmail + '" title="' + contactEmail + '">
        <img class="contactThumbnail" src="img/anonymous.jpg"/></div>');
}

You can extend the mail app to display each person’s profile picture as a thumbnail on the navigation bar. You may consider using the second operation defined in the IWhoService service contract, GetImage.

Supporting additional Active Directory properties

You can extend the mail app to display other attributes that your setup of Active Directory enables. You can find the list of attributes that Active Directory enables by default in Common Default Attributes Set for Active Directory and Global Catalog.

For information about the attributes used in this mail app and other attributes that AD supports, see the section "2 Attributes" of the following documents. Each attribute is listed with the corresponding LDAP display name, which you can specify in the AdProperties list of LDAP display names.

The following is a listing of the XML manifest for the Who’s Who AD mail app.

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>69CC567C-6737-4C49-88DD-123334574567</Id> 
  <Version>1.0</Version> 
  <ProviderName>Microsoft</ProviderName> 
  <DefaultLocale>en-US</DefaultLocale> 
  <DisplayName DefaultValue="Who's Who AD"/> 
  <Description DefaultValue="Show people and organization data from Active Directory. Corporate network connection is required to use this mail app."/> 
  <!-- Change the following line to specify the web server -->
  <!-- where the icon file is hosted. -->
  <IconUrl DefaultValue="https://webserver/WhosWhoAD/img/app_icon.png"/> 
  <Capabilities>
    <Capability Name="Mailbox" />
  </Capabilities>
  <DesktopSettings> 
    <!-- Change the following line to specify the web server -->
    <!-- where the HTML file is hosted. -->
    <SourceLocation DefaultValue="https://webserver/WhosWhoAD/WhoMailApp.html"/> 
    <RequestedHeight>260</RequestedHeight> 
  </DesktopSettings> 
  <Permissions>ReadItem</Permissions> 
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message" />
    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExValue="@" 
      RegExName="addressMatches" PropertyName="SenderSMTPAddress" />
  </Rule>
  <DisableEntityHighlighting>false</DisableEntityHighlighting>
</OfficeApp>
Show:
© 2014 Microsoft