Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Troubleshoot mail apps activation

apps for Office

Explore the possible reasons why an installed mail app may fail to activate for some or all items in the Outlook rich client, Outlook Web App, or OWA for Devices.

Last modified: April 01, 2014

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

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article
Is the user mailbox on a version of Exchange Server that is at least Exchange 2013?
Is the mail app disabled?
Does the tested item support mail apps? Is the selected item delivered by a version of Exchange Server that is at least Exchange 2013?
Is the app manifest installed properly, and does Outlook have a cached copy?
Are you using the appropriate activation rules?
If you use a regular expression, is it properly specified?
If you use a regular expression, is the read app activating in Outlook Web App or OWA for Devices, but not in the Outlook rich client?
If you use an ItemIs, ItemHasAttachment, or ItemHasRegularExpressionMatch rule, have you verified the related item property?
Does the host application apply all the regular expressions to the portion of the item body as you expect?
Next steps
Additional resources

Mail app activation is contextual and is based on the activation rules in the mail app manifest. When conditions for the currently selected item satisfy the activation rules for the mail app, the host application activates and displays the app button in the Outlook user interface (app selection pane for compose apps, app bar for read apps). However, if your mail app doesn’t activate as you expect, you should look into the following areas for possible reasons.

First, ensure that the user’s email account you’re testing with is on a version of Exchange Server that is at least Exchange 2013. If you are using specific features that are released after Exchange 2013, for example, activating compose apps which debuts in Exchange 2013 Service Pack 1, then make sure the user's account is on the appropriate version of Exchange.

You can verify the version of Exchange 2013 by using one of the following approaches:

  • Check with your Exchange Server administrator.

  • If you are testing the mail app on Outlook Web App or OWA for Devices, in a script debugger (for example, the JScript Debugger that comes with Internet Explorer), look for the src attribute of the script tag that specifies the location from which scripts are loaded. The path should contain a substring owa/15.0.516.x/owa2/…, where 15.0.516.x represents the version of the Exchange Server, such as 15.0.516.2.

  • Alternatively, you can use the hostVersion property of the Diagnostics object to verify the version. On Outlook Web App and OWA for Devices, this property returns the version of the Exchange Server.

  • If you can test the mail app on only the Outlook rich client, you can use the following simple debugging technique that uses the Outlook object model and Visual Basic Editor:

    1. First, verify that macros are enabled for Outlook. Choose File, Options, Trust Center, Trust Center Settings, Macro Settings. Ensure that Notifications for all macros is selected in the Trust Center. You should have also selected Enable Macros during Outlook startup.

    2. On the Developer tab of the ribbon, choose Visual Basic.

      Note Note

      Not seeing the Developer tab? See How to: Show the Developer Tab on the Ribbon to turn it on.

    3. In the Visual Basic Editor, choose View, Immediate Window.

    4. Type the following in the Immediate window to display the version of the Exchange Server. The major version of the returned value must be equal to or greater than 15.

      • If there is only one Exchange account in the user’s profile:

        ?Session.ExchangeMailboxServerVersion
        
      • If there are multiple Exchange accounts in the same user profile:

        ?Session.Accounts.Item(emailAddress).ExchangeMailboxServerVersion
        

        emailAddress represents a string that contains the user’s primary STMP address. For example, if the user’s primary SMTP address is randy@contoso.com, type the following:

        ?Session.Accounts.Item("randy@contoso.com").ExchangeMailboxServerVersion
        

The Outlook rich client can disable a mail app for performance reasons, including exceeding usage thresholds for CPU core or memory, tolerance for crashes, and length of time to process all the regular expressions for a mail app. When this happens, the Outlook rich client displays a notification that it is disabling the mail app.

Note Note

Only the Outlook rich client monitors resource usage, but disabling a mail app in the Outlook rich client also disables the app in Outlook Web App and OWA for Devices.

Use one of the following approaches to verify whether a mail app is disabled:

  • In Outlook Web App, sign in directly to the email account, choose the Settings icon, and then choose Manage apps to go to the Exchange Admin Center, where you can verify whether the app is enabled.

  • In the Outlook rich client, go to the Backstage view and choose Manage apps. Sign in to the Exchange Admin Center to verify whether the app is enabled.

For more information about the circumstances in which Outlook can disable a mail app, see Following resource usage rules in apps for Office.

If your mail app is a read app and is supposed to be activated when the user is viewing a message (including email messages, meeting requests, responses, and cancellations) or appointment, even though these items generally support mail apps, there are exceptions if the selected item is one of the following:

  • Protected by Information Rights Management (IRM).

  • In S/MIME format or encrypted in other ways for protection.

  • A draft (does not have a sender assigned to it), or is in the Outlook Drafts folder.

  • In the Junk Email folder.

  • A delivery report or notification that has the message class IPM.Report.*, including delivery and Non-Delivery Report (NDR) reports, and read, non-read, and delay notifications.

  • A .msg file that is attached to another message or was opened from the file system.

Also, because appointments are always saved in Rich Text Format, an ItemHasRegularExpressionMatch rule that specifies a PropertyName value of BodyAsHTML would not activate a mail app on an appointment or message that is saved in plain text or Rich Text Format.

Even if a mail item is not one of the above types, if the item was not delivered by a version of Exchange Server that is at least Exchange 2013, known entities and properties such as sender’s SMTP address would not be identified on the item. Any activation rules that rely on these entities or properties would not be satisfied, and the mail app would not be activated.

If your mail app is a compose app and is supposed to be activated when the user is authoring a message or meeting request, make sure the item is not protected by IRM.

This scenario applies to only the Outlook rich client. Normally, when you install a mail app for a mailbox, the Exchange Server copies the app manifest from the location you indicate to the mailbox on that Exchange Server. Every time the Outlook rich client starts, Outlook reads all the manifests installed for that mailbox into a temporary cache at the following location:

%LocalAppData%\Microsoft\Office\15.0\WEF

For example, for the user John, the cache might be at C:\Users\john\AppData\Local\Microsoft\Office\15.0\WEF.

If a mail app does not activate for any items, the manifest might not have been installed properly on the Exchange Server, or Outlook has not read the manifest properly on startup. Using the Exchange Admin Center, ensure that the app is installed and enabled for your mailbox, and reboot the Exchange Server, if necessary.

Figure 1 shows a summary of the steps to verify whether Outlook has a valid version of the manifest.

Figure 1. Flow chart of the steps to verify whether Outlook properly cached the manifest

Flow chart to check manifest

The following procedure describes the details.

  1. If you have modified the manifest while Outlook is open, and you are not using "Napa" Office 365 Development Tools, Visual Studio 2012, or a later version of Visual Studio to develop the app, you should uninstall the mail app and reinstall it using the Exchange Admin Center.

  2. Restart Outlook and test whether Outlook now activates the app.

  3. If Outlook doesn’t activate the app, check whether Outlook has a properly cached copy of the manifest for the app. Look under the following path:

    %LocalAppData%\Microsoft\Office\15.0\WEF

    You can find the manifest in the following subfolder:

    [GUID]\[BASE 64 Hash]]\Manifests\[ManifestID]_[ManifestVersion]

    Note Note
    • [GUID] is provided by the WefCacheId key that is stored in the Windows registry in the following location:

      HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Wef\Providers

      The following is an example of the data that the WefCacheId key contains:

      8D8445A4-80E4-4D6B-B7AC-D4E6AF594E73

    • [BASE 64 Hash] is an internal GUID that Outlook generates for the current Exchange account. Each Exchange account in a profile has its own GUID.

    • [ManifestID] is a string of the UUID type specified in the Id element in the manifest.

    • [ManifestVersion] is a string of the Version type specified in the Version element in the manifest.

    The following is an example of a path to a manifest installed for a mailbox for the user John:

    C:\Users\john\appdata\Local\Microsoft\Office\15.0\WEF\{8D8445A4-80E4-4D6B-B7AC-D4E6AF594E73}\GoRshCWa7vW8+jhKmyiDhA==\Manifests\b3d7d9d5-6f57-437d-9830-94e2aaccef16_1.2

    Verify whether the manifest of the app you’re testing is among the cached manifests.

  4. If the manifest is in the cache, skip the rest of this section and consider the other possible reasons following this section.

  5. If the manifest is not in the cache, check whether Outlook indeed successfully read the manifest from the Exchange Server. To do that, use the Windows Event Viewer:

    1. Under Windows Logs, choose Application.

    2. Look for a reasonably recent event for which the Event ID equals 63, which represents Outlook downloading a manifest from an Exchange Server.

    3. If Outlook successfully read a manifest, the logged event should have the following description:

      The Exchange web service request GetAppManifests succeeded.

      Then skip the rest of this section and consider the other possible reasons following this section.

    For information about opening the Event Viewer in Windows 7, see Open Event Viewer.

  6. If you don’t see a successful event, close Outlook, and delete all the manifests in the following path:

    %LocalAppData%\Microsoft\Office\15.0\WEF\[GUID]\[BASE 64 Hash]]\Manifests\

    Start Outlook and test whether Outlook now activates the app.

  7. If Outlook doesn’t activate the app, go back to Step 3 to verify again whether Outlook has properly read the manifest.

Starting in version 1.1 of the apps for Office manifests schema, you can create mail apps that are activated when the user is in a compose form (compose apps) or in a read form (read apps). Make sure you specify the appropriate activation rules for each type of form that your mail app is supposed to activate in. For example, you can activate compose apps using only ItemIs rules with the FormType attribute set to Edit or ReadOrEdit, and you cannot use any of the other types of rules, such as ItemHasKnownEntity and ItemHasRegularExpressionMatch rules for compose apps. For more information, see Activate mail apps in Outlook clients.

Because regular expressions in activation rules are part of the XML manifest file for a read app, if a regular expression uses certain characters, be sure to follow the corresponding escape sequence that XML processors support. Table 1 lists these special characters.

Table 1. Escape sequences for regular expressions

Character

Description

Escape sequence to use

"

Double quotation mark

"

&

Ampersand

&

Apostrophe

'

<

Less-than sign

&lt;

>

Greater-than sign

&gt;

The Outlook rich client uses a regular expression engine that's different from the one used by Outlook Web App and OWA for Devices. The Outlook rich client uses the C++ regular expression engine provided as part of the Visual Studio standard template library. This engine complies with ECMAScript 5 standards. Outlook Web App and OWA for Devices use regular expression evaluation that is part of JavaScript, is provided by the browser, and supports a superset of ECMAScript 5. While in most cases, these host applications find the same matches for the same regular expression in an activation rule, there are exceptions:

  • The Outlook rich client supports look-ahead, but does not support look-behind (?<=text) and negative look-behind (?<!text), assertions in regular expressions. Outlook Web App and OWA for Devices support look-ahead and look-behind assertions in regular expressions.

  • If the regex includes a custom character class based on predefined character classes, the Outlook rich client may return results different from Outlook Web App and OWA for Devices. For example, character classes that contain shorthand character classes [\d\w] within them return different results. Instead, use (\d|\w).

Test your regular expression thoroughly. If it returns different results, rewrite the regular expression for compatibility with both engines. To verify evaluation results on the Outlook rich client, write a small C++ program that applies the regular expression against a sample of the text you are trying to match. Running on Visual Studio, the C++ test program would use the standard template library, simulating the behavior of the Outlook rich client when running the same regular expression. To verify evaluation results on Outlook Web App or OWA for Devices, use your favorite JavaScript regular expression tester.

If you use an ItemHasRegularExpressionMatch activation rule, verify whether the value of the PropertyName attribute is what you expect for the selected item. The following are some tips to debug the corresponding properties:

  • If the selected item is a message and you specify BodyAsHTML in the PropertyName attribute, open the message, and then choose View Source to verify the message body in the HTML representation of that item.

  • If the selected item is an appointment, or if the activation rule specifies BodyAsPlaintext in the PropertyName, you can use the Outlook object model and the Visual Basic Editor in the Outlook rich client:

    1. Ensure that macros are enabled and the Developer tab is displayed in the ribbon for Outlook. If you’re not sure how to do this, see Steps 1 and 2 under Is the user mailbox on a version of Exchange Server that is at least Exchange 2013?

    2. In the Visual Basic Editor, choose View, Immediate Window.

    3. Type the following to display various properties depending on the scenario.

      • The HTML body of the message or appointment item selected in the Outlook explorer:

        ?ActiveExplorer.Selection.Item(1).HTMLBody
        
      • The plain text body of the message or appointment item selected in the Outlook explorer:

        ?ActiveExplorer.Selection.Item(1).Body
        
        
      • The HTML body of the message or appointment item opened in the current Outlook inspector:

        ?ActiveInspector.CurrentItem.HTMLBody
        
      • The plain text body of the message or appointment item opened in the current Outlook inspector:

        ?ActiveInspector.CurrentItem.Body
        

If the ItemHasRegularExpressionMatch activation rule specifies Subject or SenderSMTPAddress, or if you use an ItemIs or ItemHasAttachment rule, and you are familiar with or would like to use MAPI, you can use MFCMAPI to verify the value in Table 2 that your rule relies on.

Table 2. Activation rules and corresponding MAPI properties

Type of rule

Verify this MAPI property

ItemHasRegularExpressionMatch rule with Subject

PidTagSubject

ItemHasRegularExpressionMatch rule with SenderSMTPAddress

PidTagSenderSmtpAddress and PidTagSentRepresentingSmtpAddress

ItemIs

PidTagMessageClass

ItemHasAttachment

PidTagHasAttachments

After verifying the property value, you can then use a regular expression evaluation tool to test whether the regular expression finds a match in that value.

This section applies to all activation rules that use regular expressions—particularly those that are applied to the item body, which may be large in size and take longer to evaluate for matches. You should be aware that even if the item property that an activation rule depends on has the value you expect, the host application may not be able to evaluate all the regular expressions on the entire value of the item property. To provide reasonable performance and to control excessive resource usage by a read app, Outlook, Outlook Web App and OWA for Devices observe the following limits on processing regular expressions in activation rules at run time:

  • The size of the item body evaluated—There are limits to the portion of an item body on which the host application evaluates a regular expression. These limits depend on the host application, form factor, and format of the item body. See the details in Table 2 in Limits for activation and JavaScript API for mail apps in Outlook.

  • Number of regular expression matches—The Outlook rich client, Outlook Web App and OWA for Devices each returns a maximum of 50 regular expression matches. These matches are unique, and duplicate matches do not count against this limit. Do not assume any order to the returned matches, and do not assume the order in the Outlook rich client is the same as that in Outlook Web App and OWA for Devices. If you expect many matches to regular expressions in your activation rules, and you're missing a match, you may be exceeding this limit.

  • Length of a regular expression match—There are limits to the length of a regular expression match that the host application would return. The host application does not include any match above the limit and does not display any warning message. You can run your regular expression using other regex evaluation tools or a stand-alone C++ test program to verify whether you have a match that exceeds such limits. Table 3 summarizes the limits. For more information, see Table 3 in Limits for activation and JavaScript API for mail apps in Outlook.

    Table 3. Length limits for a regular expression match

    Limit on length of a regex match

    Outlook rich client

    Outlook Web Appor OWA for Devices

    Item body is plain text

    1.5 KB

    3 KB

    Item body is HTML

    3 KB

    3 KB

  • Time spent on evaluating all regular expressions of a read app—For the Outlook rich client: By default, for each read app, Outlook must finish evaluating all the regular expressions in its activation rules within 1 second. Otherwise Outlook retries up to three times and disables the app if Outlook cannot complete the evaluation. Outlook displays a message in the notification bar that the app has been disabled. The amount of time available for your regular expression can be modified by setting a group policy or a registry key. For more information, see Overriding resource usage settings for performance of apps for Office.

    Note Note

    Note that if the Outlook rich client disables a read app, the read app is not available for use for the same mailbox on the Outlook rich client, Outlook Web App and OWA for Devices.

Troubleshooting activation is a common task in developing mail apps. You can consult the following topics for further debugging tips where applicable.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.