How to: Install sample mail apps in Outlook

apps for Office

This topic describes how to install the sample mail apps — YouTube, Phone Dialer, Debug, and Who's Who AD — for a mailbox on Exchange 2013 or a later version. After reviewing these samples, learn more about mail apps and fundamental concepts for developing mail apps in Outlook.

This topic shows how to install the sample mail apps by specifying the file name of the manifest in the Exchange Admin Center (EAC).

This topic does not assume any of the following tools:

  • Office 365 developer tenant

  • "Napa" Office 365 Development Tools

  • Visual Studio

In general, if you are not using any of the above tools, and you do not have at minimum the "My Custom Apps" role for your Exchange Server, then you can install mail apps only from the Office Store. To install these sample mail apps by specifying the corresponding app manifest file name, you should first request your Exchange administrator to provide the necessary permissions for you.

The Exchange administrator can run the following PowerShell cmdlet to assign a single user the necessary permissions. 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 multiple users the similar necessary permissions:

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

Using Office 365, "Napa" Office 365 Development Tools, or Visual Studio to develop mail apps assigns you the organization administrator role which allows you to install mail apps by file or URL in the EAC, or by Powershell cmdlets.

This section describes where to obtain and place the code files for the YouTube mail app, and how to install the app using the EAC. After installing the mail app, proceed to Sample: Create a mail app to view YouTube videos in Outlook for a description of the code.

Obtaining the code files

You can download the source code files for the YouTube mail app at Mail apps for Outlook: Create a mail app to view YouTube videos. As part of the download, you will find the following files that are specific to this YouTube mail app:

  • manifest.xml

  • strings_en-us.js

  • strings_fr-fr.js

  • YouTube.htm

  • YouTubeLogo.png

And the following files that generally other apps for Office use as well:

  • MicrosoftAjax.js

  • Outlook.css

Notice that this sample mail app requires the following files as well, and gets them from the Content Delivery Network (CDN) at https://appsforoffice.microsoft.com/lib/1.0/.

  • Office.js

  • Outlook-15.js

  • OutlookWebApp-15.js

  • Office_strings.js, in a subfolder named en-us

Use the following steps to place the files in the appropriate locations:

  1. Copy manifest.xml to C:\YouTubeManifest.

    Generally, you can choose to keep the manifest file wherever Outlook and Exchange can access (for example, on a local drive, network share, or web server). For the purpose of this documentation, create a folder C:\YouTubeManifest and copy manifest.xml to that folder.

  2. Create a folder called YouTube on your web server and copy the following JavaScript library, CSS, string and sample mail app files to that YouTube folder.

    • MicrosoftAjax.js

    • Outlook.css

    • strings_en-us.js

    • strings_fr-fr.js

    • YouTube.htm

    • YouTubeLogo.png

    The preceding list of files must reside on a web server for a mail app. For convenience in this example, place them in the same folder on the web server.

  3. Update manifest.xml to reflect the location of the YouTube.htm file, by replacing webserver in the following line with the server path of the YouTube folder you created in Step 2.

    <SourceLocation DefaultValue="https://webserver/youtube/youtube.htm"/>
    

    The manifest file of an app for Office specifies the location of the HTML file, and the HTML file specifies the location of the JavaScript library files and any other JavaScript files that the HTML refers to. For the specific web server setup that you are using, you should always be sure that the manifest file and HTML file specify the respective locations appropriately.

Installing the app

The following procedure describes how to use the Outlook rich client and the EAC to install the YouTube app for use by the same Outlook account in the Outlook rich client, Outlook Web App, or OWA for Devices. 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 below. In general, as long as the manifest file specifies the applicable form factors, once you have installed an app for a mailbox in the EAC, the app is available for use for that account in the Outlook rich client, Outlook Web App or OWA for Devices on the form factors that the app supports.

Note Note

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

  1. In the Outlook rich client, choose File, and then choose 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 1.

    Figure 1. Installing an 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 C:\YouTubeManifest, choose Open, and then choose Next.

You should then see the YouTube app in the list of apps for Outlook, as shown in Figure 2. Proceed to Sample: Create a mail app to view YouTube videos in Outlook for a description of the code.

Figure 2. YouTube app installed on the Exchange Admin Center

YouTube app on Unified Management Console

This section describes where to obtain and place the code files for the Phone Dialer mail app, and how to install the app by using the EAC. After installing the mail app, proceed to Sample: Create a mail app for Voice Over IP dialing in Outlook for a description of the code.

Obtaining the code files

You can download the source code files for the Phone Dialer mail app at Mail apps for Outlook: Create a mail app for VoIP dialing. As part of the download, you will find the following files that are specific to this Phone Dialer mail app:

  • dialer.htm

  • manifest.xml

  • Images\Icon.png

  • Images\Icon_narrow.png

  • Scripts\dialer.js

And the following files that generally other apps for Office use as well:

  • Css\Outlook.css

  • Scripts\jquery-1.4.2.js

  • Scripts\json2.js

  • Scripts\MicrosoftAjax.js

Notice that this sample mail app requires the following files as well, and gets them from the Content Delivery Network (CDN) at https://appsforoffice.microsoft.com/lib/1.0/.

  • Office.js

  • Outlook-15.js

  • OutlookWebApp-15.js

  • Office_strings.js, in a subfolder named en-us

Use the following steps to put the files in the appropriate locations:

  1. Copy manifest.xml to C:\PhoneDialerManifest.

    Generally, you can choose to keep the manifest file wherever Outlook and Exchange can access (for example, on a local drive, network share, or web server). For the purpose of this documentation, create a folder C:\PhoneDialerManifest and copy manifest.xml to that folder.

  2. Create a folder called PhoneDialer on your web server and copy the following sample mail app, CSS, JavaScript library and string files to that PhoneDialer folder.

    • dialer.htm

    • Css\Outlook.css

    • Images\Icon.png

    • Images\Icon_narrow.png

    • Scripts\dialer.js

    • Scripts\jquery-1.4.2.js

    • Scripts\json2.js

    • Scripts\MicrosoftAjax.js

    The preceding list of files for a mail app must reside on a web server. For convenience in this example, place the hierarchy of files under the same folder on the web server.

  3. Update the manifest.xml to reflect the location of the dialer.htm file, by replacing webserver in the following line with the server path of the PhoneDialer folder you created in Step 2.

    <SourceLocation DefaultValue="https://webserver/dialer/dialer.htm"/>
    

    The manifest file for an app for Office specifies the location of the HTML file, and the HTML file specifies the location of the JavaScript library files and any other JavaScript files that the HTML refers to. For the specific web server setup that you are using, you should always be sure that the manifest file and HTML file specify the respective locations appropriately.

Installing the app

The following procedure describes how to use the Outlook rich client and the EAC to install the Phone Dialer app for use by the same Outlook mailbox in the Outlook rich client, and Outlook Web App. The procedure to install an app from Outlook Web App through the EAC is similar, once you are in the EAC as described in Step 3 below. In general, as long as the manifest file specifies the applicable form factors, once you have installed an app for a mailbox in the EAC, the app is available for use for that account in the Outlook rich client or Outlook Web App on the supporting form factors.

Note Note

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

  1. In the Outlook rich client, choose File, and then choose 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, choose the drop-down box that is adjacent to the + button, and then choose Add from file.

  4. In the add from file dialog box, browse to the location of manifest.xml in C:\PhoneDialerManifest, choose Open, and then choose Next.

You should then see the Phone Dialer app in the list of apps for Outlook, as shown in Figure 2. Proceed to Sample: Create a mail app for Voice Over IP dialing in Outlook for a description of the code.

This section describes where to obtain and place the code files for the set of 2 Debug mail apps, and how to install the apps by using the EAC. After installing the mail apps, proceed to Sample: Debug properties of Outlook items for a description of the code.

Obtaining the code files

You can download the source code files for the Debug mail apps at Mail apps for Outlook: Debug item properties. In this sample, there are 2 mail apps: Debug (Restricted) and Debug (Other). As part of the download, you will find the following files that are specific to the Debug (Restricted) mail app:

  • itemPropsRS.html

  • itemPropsRS.xml

  • css\itemPropsRS.css

  • js\itemPropsRS.js

You will find the following files that are specific to the Debug (Other) mail app:

  • itemPropsRD.html

  • itemPropsRD.xml

  • css\itemPropsRD.css

  • js\itemPropsRD.js

And for each of the 2 Debug mail apps, the following files that generally other apps for Office use as well:

  • js\jquery\jquery-1.7.2.min.js

  • js\office\MicrosoftAjax.js

Notice that these 2 mail apps require the following files as well, and get them from the Content Delivery Network (CDN) at https://appsforoffice.microsoft.com/lib/1.0/.

  • Office.js

  • Outlook-15.js

  • OutlookWebApp-15.js

  • Office_strings.js, in a subfolder named en-us

  • outlook_strings.js, also in the subfolder named en-us

Use the following steps to put the files for the 2 Debug mail apps in the appropriate locations:

  1. Copy the 2 manifest XML files, itemPropsRS.xml and itemPropsRD.xml, to a local folder C:\DebugManifests.

  2. Copy the code files of each of the 2 Debug mail apps to the corresponding folder on the web server:

    • Create a folder called ItemPropertiesMailAppRestricted on your web server and copy the hierarchy of the CSS and JavaScript library files of the Debug (Restricted) mail app listed below to that ItemPropertiesMailAppRestricted folder:

      • itemPropsRS.html

      • css\itemPropsRS.css

      • js\itemPropsRS.js

      • js\jquery\jquery-1.7.2.min.js

      • js\office\MicrosoftAjax.js

    • Create a folder called ItemPropertiesMailAppOtherPerms on your web server and copy the hierarchy of the CSS and JavaScript library files of the Debug (Other) mail app listed below to that ItemPropertiesMailAppOtherPerms folder:

      • itemPropsRD.html

      • css\itemPropsRD.css

      • js\itemPropsRD.js

      • js\jquery\jquery-1.7.2.min.js

      • js\office\MicrosoftAjax.js

  3. Update the manifest files to reflect the location of the corresponding HTML file:

    • Replace webserver in the following line in itemPropsRS.xml with the server path of the ItemPropertiesMailAppRestricted folder you created in Step 2.

      <SourceLocation DefaultValue="https://webserver/ItemPropertiesMailAppRestricted/itemPropsRS.html"/>
      
    • Similarly, replace webserver in the following line in itemPropsRD.xml with the server path of the ItemPropertiesMailAppOtherPerms folder you created in Step 2.

      <SourceLocation DefaultValue="https://webserver/ItemPropertiesMailAppOtherPerms/itemPropsRD.html"/>
      

    The manifest file for an app for Office specifies the location of the HTML file, and the HTML file specifies the location of the JavaScript library files and any other JavaScript files that the HTML refers to. For the specific web server setup that you are using, you should always be sure that the manifest file and HTML file specify the respective locations appropriately.

Installing the apps

The following procedure describes how to use the Outlook rich client and the EAC to install the set of 2 Debug mail apps for use by the same Outlook mailbox in the Outlook rich client, and Outlook Web App. The procedure to install an app from Outlook Web App through the EAC is similar, once you are in the EAC as described in Step 3 below.

Note Note

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

  1. In the Outlook rich client, choose File, and then choose 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, choose the drop-down box that is adjacent to the + button, and then choose Add from file.

  4. In the add from file dialog box, choose Browse to navigate to the location of the manifest files in C:\DebugManifests. Install the 2 manifest files one after another, by choosing one manifest file each time, then Open, and then Next.

You should then see the Debug (Restricted) and Debug (Other) mail apps in the list of apps for Outlook, as shown in Figure 2. Proceed to Sample: Debug properties of Outlook items for a description of the code.

For information about obtaining the code files, installing the Who's Who AD mail app and deploying the Who web service, see the section Installation and deployment in Sample: Create a mail app to display in Outlook hierarchy information from Active Directory.

You can make a copy of these sample code files and use them as starter files for your own mail app. Pay attention to the tips suggested in Best practices for developing apps for Office and FAQ for developing apps for Office.

Show:
© 2014 Microsoft