• Article

Managed Folder Selector

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Topic Last Modified: 2007-05-30

By Michael Mainer, Programming Writer

Microsoft® Exchange Server 2007 provides a set of exciting new features, many of which are complimented by new APIs, to enhance collaboration and communication in your organization. This includes messaging records management (MRM), which enables users to more easily comply with organizational policy, government regulations, and legal requirements for e-mail retention by using managed folders for the storage of e-mail and other communication. One important part of this strategy is for users to be able to select which managed folders they include in their mailbox; this way, users can take advantage of the appropriate managed folders based on their own e-mail retention needs, without the help of an administrator. To enable this functionality, you must design and deploy a Managed Folder Selector application that implements the new Exchange Web Services API.

This article describes how to set up a Managed Folder Selector sample application. This sample application can be used to create a managed folder home page that integrates with client applications such as Microsoft Outlook 2007. The home page enables users to add, delete, and view managed folders in their mailboxes. You can also use the Managed Folder Selector sample application to allow a user to manage another user's managed folders by means of delegated access.

Messaging records management is a multi-step process that involves the creation and management of e-mail folders folder policies, content settings, and e-mail management schedules. Before you attempt to program or customize MRM, we recommend that you familiarize yourself with the MRM process. For information about MRM, see Managing Messaging Records Management.

Prerequisites

The following are the prerequisites that are required before you can use the Managed Folder Selector sample application:

  • Access to Exchange 2007 computers that are running the Client Access and Mailbox server roles.
  • Access to a Microsoft Windows Server® 2003 Web server to host the Managed Folder Selector sample. The Web server must be installed in the same forest as the mailboxes of the users who access the application.
  • Exchange Administrator access to the Client Access server to enable Exchange impersonation, set up delegate access, and set up the Managed Folder home page for Exchange clients.
  • A user account that can access the Messaging Records Management Folders container in the Configuration object. This account should be a member of the Exchange ReadOnly Administrators group. You can use this account to look up information in the Active Directory® directory service. We suggest you create an account that is used only to access Active Directory. We also suggest you name this user account so that it is apparent that it is used for only one purpose. For example, you can name the account ManagedFolderROAdmin.
  • Two mail-enabled accounts that are located in the mailbox database on the Mailbox server. These two accounts will be used to demonstrate delegate access. For more information about creating these accounts, see How to Create a New Mail-Enabled User.
  • Microsoft Visual Studio 2005 Visual Web Developer tool, to build the sample application.

Setting Up the Managed Folder Selector Sample Application

Setting up the Managed Folder Selector sample application involves the following steps:

  1. Using Visual Studio 2005 to add a Web reference to Exchange Web Services. Adding a Web reference initiates the creation of a proxy class library that the sample client application uses to communicate with the Client Access server that hosts Exchange Web Services. The Web Reference is named exchangeWebService so that it matches the reference in the code files.
  2. Customizing the sample code. The sample code must be customized for the environment that is hosting the application. This includes updating the code to identify the Client Access server and an account that has permission to view Active Directory.
  3. Deploying the Managed Folder Selector sample application on the Windows Server 2003 Web server.
  4. Changing the file access to Anonymous. After you deploy the sample, some of the sample files require that anonymous access be enabled. The remaining administrative tasks are all performed on the computer running Exchange 2007.
  5. Creating managed folders. This makes the managed folders available in Active Directory so that they can be added to users' mailboxes.
  6. Setting up impersonation for the Managed Folder Selector sample application. This enables the Web server to perform actions on behalf of the user who is accessing the Web site. If users use different Client Access servers to access their mailboxes, you must set up impersonation for each Client Access server in the organization.
  7. Setting the managed folder home page. This sets the URL of the sample application that is running on the Web server as the location of the Managed Folder Selector application.
  8. Setting up delegate access for administrative users that manage other users’ managed folders. This enables one user to act on behalf of another user. Delegate access is used in the sample application to add managed folders to another user’s mailbox.

Adding a Web Reference to the Exchange Web Services Location

The computer that runs Visual Studio 2005 must have access to the Web services URL before you can add a Web reference to the Exchange Web Services location. For more information about adding a Web reference, seeHow to: Add and Remove Web References.

To add a Web reference to the Exchange Web Services location

  1. Open the Managed Folder Selector Sample Application solution file, ManagedFolderSelector.sln.

  2. In the Solution Explorer, right-click the App_WebReferences folder.

  3. Select Add Web Reference from the context menu.

  4. Enter the location of Exchange Web Services into the URL field. This URL will take the following form: https://<Client Access server*>*/EWS/Services.wsdl, where <Client Access server> is the location of the Client Access server that hosts Exchange Web Services for this sample client Web server application.

  5. Enter Go to find the Web service.

    Note

    The first time that the computer that has Visual Studio 2005 installed attempts to connect to the Client Access server to add the Web reference, a Security Alert appears. The following figure shows the security alert.

    Security Alert for certificates

  6. Select View Certificate. The Certificate window appears.

  7. Select Install Certificate. The following figure shows the certificate window.

    Certificate Information Window

  8. The Certificate Import Wizard appears. Accept all the default settings. Click Install to install the certificate.

  9. In the Web reference name field, enter exchangeWebService as the name of the Web reference. Click Add Reference.

    Note

    The AddFolder.aspx.cs, AdditionalMailbox.aspx.cs, and Summary.aspx.cs files include using directives that refer to the added Web reference. Each file references "using exchangeWebService."

Customizing the Sample Code

To customize the sample code

  1. Change the string value of the exchangeServiceBindingURL to the location of the Exchange Web Services binding. This string represents the computer and file that are used to access Exchange Web Services. Get this URL from the administrator who set up the Client Access server that hosts Exchange Web Services. This URL will take the following form: https://<Client Access server*>*.<DOMAIN>**/EWS/exchange.asmx, where <Client Access server> is the name of the Client Access server that hosts Exchange Web Services, and <DOMAIN> is the domain of the Client Access server. These changes need to be made to the exchangeServiceBindingURL in the following files:

    • AddFolder.aspx.cs
    • AdditionalMailbox.aspx.cs
    • Summary.aspx.cs

  2. Change the user name, domain, and password that is passed to the LogonUser function called in the GetAllOrganizationalFolders() method found in the AddFolder.aspx.cs file. This account must have permission to view the list of managed folders in Active Directory. The account should be a member of the Exchange ReadOnly Administrators group. We suggest that you name the user account ManagedFolderROAdmin. For information about adding a user account to a group, see Add a member to a group.

  3. Build the solution.

Deploying the Managed Folder Selector Sample Application on the Web Server

To deploy the Managed Folder Selector sample application

  1. Create the Web application root directory. For information about creating the Web application root directory, see Walkthrough: Creating ASP.NET Web Application Root Directories in IIS.

  2. Copy all the files from the Managed Folder Selector sample and place the files in the root directory that you created.

  3. In Internet Information Services (IIS) Manager, right-click the Web application root directory that you created. From the context menu, select Properties.

  4. In the Properties window, select the Directory Security tab. In the Authentication and access control section, select Edit.

  5. In the Authentication Methods window, uncheck Enable anonymous access. In the Authenticated access section, check Integrated Windows authentication. Click OK to save changes and close the window.

  6. In the Properties window, select the Documents tab. Check Enable default content page. In the same section, add main.aspx to the list of default content pages.

Note

For this sample to work, you must enable Session Variables.

Enabling Anonymous Access

You must enable anonymous access on the following in the application virtual directory:

  • Header_left.gif (File Security tab)
  • Header_repeater.gif (File Security tab)
  • Header_right.gif (File Security tab)
  • statusprog.js (File Security tab)
  • App_Themes (Directory Security tab)

If you do not enable anonymous access on these items, the user may be prompted for credentials.

To enable anonymous access

  1. Open Internet Information Services (IIS) Manager on the Web server that hosts the sample application.

  2. In the left pane, select the virtual directory or Web site that hosts the sample application.

  3. In the right pane, right-click the file or directory, and then from the context menu, select Properties.

  4. Select the File Security tab and then, from the Authentication and access control section, choose Edit. If you are performing this step on a directory, select the Directory Security tab, and then from the Authentication and access control section, choose Edit.

  5. Select Enable anonymous access. Do not change the default Windows user account.

Authentication Methods Window

Creating Managed Folders

You can use the New-ManagedFolder cmdlet to create a managed folder in Active Directory.

To create a managed folder

  1. Enter the following cmdlet into the Exchange Management Shell on the Client Access server:

    New-ManagedFolder -Name Name -FolderName FolderName

  2. Change the value of Name to the name of the managed folder. The Name parameter specifies a unique name for the folder for use by the administrator. It does not appear in users' mailboxes.

  3. Change the value of FolderName to the folder name of the managed folder. This specifies the name of the folder as it appears in users' mailboxes.

  4. Run the cmdlet.

Setting Up Impersonation

You must perform the following procedures on the Client Access server to set up impersonation. Use these procedures to grant Exchange impersonation rights to the Web server that hosts the Managed Folder Selector sample application. This allows the Web server to impersonate all users in an identified Mailbox store on the Client Access server.

To enable Exchange Impersonation on the Client Access server

  1. In the Exchange Management Shell on the Client Access server, type the following:

    add-adpermission -identity (Get-ExchangeServer -Id  CLIENTACCESSSERVER).DistinguishedName -user DOMAIN\WEBSERVERNAME$ -extendedrights ms-Exch-EPI-Impersonation

  2. Change the value of CLIENTACCESSSERVER to the name of the Client Access server.

  3. Change the value of DOMAIN to the domain of the Web server that hosts the sample application.

  4. Change the value of WEBSERVERNAME to the name of the Web server that hosts the client application. Make sure that the $ remains.

  5. Run the command.

To enable Exchange Impersonation on the Mailbox store

  1. In the Exchange Management Shell on the Client Access server, type the following:

    add-adpermission -identity (Get-MailboxDatabase -Server MAILBOXSERVER).DistinguishedName -user DOMAIN\WEBSERVERNAME$ -extendedrights ms-Exch-EPI-May-Impersonate

  2. Change the value of MAILBOXSERVER to the name of Mailbox server.

  3. Change the value of DOMAIN to the domain of Web server running the sample.

  4. Change the value of WEBSERVERNAME to the name of the Web server running the sample. Make sure that the $ remains.

  5. Run the command.

Setting the Managed Folder Home Page

Clients such as Outlook 2007 use the managed folder home page to integrate managed folder applications into the client user interface. You can use the Set-OrganizationConfig cmdlet on the Client Access server to set the managed folder home page for Outlook clients.

To set the managed folder home page

  1. In the Exchange Management Shell on the Client Access server, type the following:

    Set-OrganizationConfig -DomainController FQDN -ManagedFolderHomepage String

  2. Change the value of FQDN to the fully qualified domain name of the domain controller that stores the configuration information for the Client Access server.

  3. Change the value of String to the URL of the Web page that is displayed when users click the Managed Folders folder in Outlook.

  4. Run the command.

Setting Up Delegate Access

By setting up delegate access, you can enable a user to act on behalf of another user to add managed folders to that user’s account. In this way, administrators can add managed folders to user mailboxes.

To set up delegate access

  1. In the Exchange Management Shell on the Client Access server, type the following:

    Add-MailboxPermission -id 'User1' -accessright fullaccess -u 'User2' -inheritanceType all

  2. Change the value of User1 to the full name of the user that gives delegate access to User2.

  3. Change the value of User2 to the full name of the account that is given delegate access to the User1 account.

  4. Run the command.

Using the Managed Folder Selector Sample Application

After you have set up and deployed the Managed Folder Selector sample application, a user who is logged on to the hosting domain can access the application, either by using Microsoft Internet Explorer or Outlook 2007. In Internet Explorer, the user browses to the URL of the Web application. In Outlook, the user clicks the Managed Folders folder in their mailbox. The Managed Folders folder only appears in Outlook when a managed folder has been added to a mailbox. If a managed folder mailbox policy has not been applied to a mailbox, or a managed folder has not been added to the mailbox, you must use Internet Explorer to add the initial managed folder.

The Managed Folder Selector sample application contains the following three pages:

  • Add Folders
  • View/Delete Folders
  • Manage Additional Mailboxes

The Add Folders page enables the user to add managed folders to their mailbox. The managed folders that are displayed on this page do not currently exist in the mailbox.

The View/Delete Folders page shows all the managed folders in a user’s mailbox. Managed folders that have been administratively applied cannot be removed by the user and will appear grayed out. Users can delete any managed folders that they added by using this page.

Users who have delegate access can use the Manage Additional Mailboxes page to sign in to manage another user’s mailbox. A user who has delegate access to a mailbox can view, add, or delete managed folders from that mailbox.

Supportability

Microsoft strongly recommends that you perform thorough code and security reviews and testing before you deploy applications that are based on this sample in any production environment.

Additional Resources