Providing satisfactory performance for mail apps in Outlook
Providing a good user experience is a joint effort of the underlying app for Office platform and the individual app. If you’re creating a mail app for Outlook, there are some safeguards that help guarantee satisfactory baseline response time for mail apps. I will present the scenarios that together we, as partners, should mitigate, and the corresponding safeguards that you should be aware of when designing and implementing your mail apps.
Hello, I am angelgolfer and a Content Developer for apps for Office. When our Office product groups designed apps for Office, we had customer experience and security high on our priorities. In particular for Outlook, we learned from supporting add-ins and put in safeguards to maintain a baseline response time for mail apps running on Outlook. Hopefully, as our valued partners, you share the goal of offering a good user experience, and we’d like you to be aware of these safeguards. These safeguards can affect the way you design the circumstances for Outlook to activate your mail app, and the way you call certain methods in the JavaScript API for Office to handle data.
Lifecycle of a mail app
Figure 1 shows the typical check stages that a mail app goes through, from the point of being submitted to the Office Store, through activation and running on Outlook.
I will identify the stage (I, II, III, IV, and V) when each safeguard occurs.
Scenario to mitigate |
Safeguard |
Stage |
Activation rules can slow down activation. |
Limit the size of the manifest to 32 KB. |
I, II |
Limit the number of activation rules to 15. |
II |
|
ItemHasKnownEntity rules look in only the first 1MB of the item body. If using such rules, be sure that the first 1MB of the item body is enough for your mail app to match for activation. |
IV |
|
Regular expressions in activation rules can consume excessive CPU or memory resources and freeze the user interface |
Limit the number of regular expressions in activation rules to 5. |
II |
Be sure the evaluation of all regular expressions for a mail app stays within 1 second in Outlook. If your mail app requires re-evaluation for more than 3 times, Exchange disables the mail app for that mailbox on both Outlook and Outlook Web App. |
IV |
|
Regular expressions can generate many matches in an item and results in a lot of data pushed cross-frame |
getRegExMatches returns only the first 50 matches that are within certain size limits. See Limits for activation and data in mail apps for Outlook for details. If using getRegExMatches to get matches, be sure the first 50 matches are enough for your mail app. |
V |
Depending on the form factor, type of item body, and host, Outlook, and Outlook Web App apply a regular expression on up to certain sizes of the item body. See Limits for activation and data in mail apps for Outlook for details. Be sure your mail app can get activated and get enough matches for your purposes. |
IV |
|
Mail apps can request large amounts of data to be sent cross-frame, freezing the user interface |
Limit custom properties to 2,500 characters. |
V |
Limit roaming settings to 32KB number of characters. |
V |
|
Be sure your mail app finds the following limits sufficient or can work around them: |
||
Mailbox.makeEwsRequestAsync returns a response of up to 1 MB of characters. |
V |
|
The to and cc properties in a Message object, and the recipients specified in the requiredAttendees or optionalAttendees properties for the Appointment or MeetingRequest object, contain up to 100 recipients. |
V |
|
The displayNewAppointmentForm method displays up to 255 characters for the subject in the form. |
V |
|
The displayNewAppointmentForm method displays up to 32 KB number of characters for the body in the form. |
V |
|
In addition, for Outlook Web App, the displayAppointmentForm and displayMessageForm methods also display up to 32KB number of characters for the body of the form. |
||
Do not rely on using regular expressions or the JavaScript API for Office to get the body of an item. |
||
Mail apps can make many concurrent calls to asynchronous APIs, hitting the browser limit of concurrent calls for a single domain |
Limit asynchronous calls at any one time to 3. |
V |
Putting the community in control
Apart from the above guidelines for activation and implementation, we also offer transparency to customers in the Office Store, which increases the overall level of confidence in apps. When customers choose apps in the Office Store, they can read about the requirements and permissions requested by individual apps. They can also share reviews and ratings with other customers, and that includes feedback for app response time.
Figure 2 is an example of what customers can see about the requirements of a mail app in the Office Store.
I hope this post explains some of the reasons for the performance requirements that you should be aware of when designing and implementing mail apps. With some common performance goals in mind, together let’s offer an experience that our customers love!
If you are just starting and interested in knowing more about creating and posting an app on the Office Store, see our Office Dev Center, at dev.office.com!
Additional resources
Privacy and security for mail apps in Outlook
Limits for activation and data in mail apps for Outlook
Creating a manifest for a mail app for Outlook
Defining rules to show a mail app in Outlook 2013
Using regular expressions to show a mail app in Outlook
Using well-known entities in a mail app for Outlook
How to: Extract entity strings from an item in a mail app for Outlook
How to: Persist data for the same mailbox by using roaming settings
Creating custom properties for a mail app in Outlook 2013
Calling web services from a mail app for Outlook