MailBox api requirements for outlook & exchange versions are wrong / misleading

[ktvtrifork]

Article URL
https://learn.microsoft.com/en-us/office/dev/add-ins/outlook/outlook-on-send-addins?tabs=classic#supported-clients-and-platforms
https://learn.microsoft.com/en-us/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets?view=common-js-preview&tabs=jsonmanifest#exchange-server-support
https://learn.microsoft.com/en-us/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets?view=common-js-preview&tabs=jsonmanifest#outlook-client-support

Describe the problem
After extensive testing on various configurations etc., its quite clear that the documentation does not match reality.
Mostly related to this is that Office 2016 & Exchange 2016 supports quite a lot more than documented.

1. The OnSend feature is not only working in Exchange 2016 (CU 22), but its also working on OWA (which by all compatibility matrices) are NOT supported. Even when probing its supported MailBox version you get (screenshot from said OWA & an add-in)
   
   This means that the 1.8 requirement seems quite wrong and misleading. Perhaps its true for very old Exchange 2016 servers? but for updated (which is normally what you would expect) its not matching.

2. the compatibility matrix for Api requirements is wrong / missing entries (for updated outlook clients?)
   Running an updated outlook 2016 windows desktop client, can use up to and including 1.13
   
   
   This is for an Exchange online (O365). For the previous mentioned Exchange OnPrem server its as follows
   
   (since testing a couple of days ago, where it was 1.12 before I updated the client). Thus I would assume that 2019 etc. would also support a lot more than documented.

3. The compatibility matrix also states "Exchange on-premises" only supports 1.5 as max (seems right for OWA) however the other table states that "classic Outlook UI when connected to Exchange on-premises" for classic it goes to 1.6 which contradicts the other table. It also seems to be entirely client side dependent. This is both confusing as OWA goes to 1.5 and that the previous table should by the other definitions always limit it to 1.5 so 1.6 should never happen (but it is supported with desktop???)

4. The statement "If your target Exchange server and Outlook client support different requirement sets, then you may be restricted to the lower requirement set range." is then by these virtues wrong. It would seem that a most of the features are client side limited on the older versions and not server limited, meaning that it is more complicated than simply the lowest requirement number. It seems that most features are backported to the clients, and only OWA is actually limited (but could then in principle be updated as well?).

All in all it would be nice to have a more clear concise description of the limits/ supported versions and some of the misleading statements updated to reflect more precisely when they either apply or removed if they do not.
I might also have misunderstood some of the entries, most notably the one marked with a question mark. If this includes all versions of outlook it would be nice to add that to the entry to differentiate it.

Screenshots

[AlexJerabek]

Hi @ktvtrifork,

Thanks for reporting this. Let me assign @ElizabethSamuel-MSFT to investigate. One thing I'd like to clear up first is a non-obvious distinction in "2016".

"Retail perpetual" refers to the usual version of an Office product that's purchased when you get Office 2016. Despite being branded as a single version, the Office client still receives updates. These updates usually don't add functionality, but they do often add support for the JS APIs.

"Volume-licensed" refers to an enterprise-purchased SKU that doesn't follow the same update process. They're intended for businesses that need stability at all costs. These do not receive updates enabling JS features.

[ElizabethSamuel-MSFT]

@ktvtrifork Thanks again for asking about this. Hopefully, what AlexJerabek shared about the difference between "Retail perpetual" and "Volume-licensed perpetual" helped clarify your questions about that. Note that "retail perpetual" are Office 2016 and later since earlier versions of Office are currently out of Microsoft support. Based on what you've shared, you're likely using a retail perpetual version of Outlook.

Also, unlike Office Web Add-ins running in most of the other Office applications that have only client side, Outlook add-ins have both components - server side (Exchange) and client side (Outlook). However, all the features don't necessarily require both components in order to work. So, let's say you have a feature X that is fully client side. As long as the Outlook client you're using supports feature X, then it works. However, if the feature requires both components (like the on-send feature does), then both components need to be updated enough for the feature to work properly.

Now speaking specifically about the on-send feature. Agreed that the support matrix for the on-send feature doesn't quite match the general one for requirement set 1.8. The support table for the feature is your source of truth and from what you've shared, it seems to match the behavior you're actually seeing.

Does this help? Let us know if it does, or if you have further questions.

Thanks.

[ktvtrifork]

Hi @ElizabethSamuel-MSFT
Yes absolutly, your change is a lot easier to read, thanks! :)

Thanks for stating that indeed some features are fully client side dependent, and of cause some are affected by both.

You write "However, all the features don't necessarily require both components in order to work", where in the docs is that listed?

In fact from what I have read it sounds like the opposite, which is why I'm bringing it up :) I'm sure that the complexity of listing each feature from both a client and the exchange would be a huge table, and in the end not really feasible to maintain, but if say a feature requires both a client and exchange version then a simple note about the least exchange version would be nice (which by the look at the EWS api must be very few features, since most seems supported by most Exchange versions, but I could be wrong :) )

So if I read the table for OnSend correctly, basically any Office 2016 going forward (assuming it is updated) should be fine?

When reading it now vs before your comment, I can see that indeed the subtitle does say this is the minimum. Somehow the catchy Note seems to draw the attention, and I guess that is why I came to assume that 1.8 was the minimum, which by the table it is not. Especially the last line "However, note that the feature's support matrix is a superset of the requirement set's.", which by the matrix and the 1.8 requirement seems wrong. What part of onsend requires 1.8? in fact, if anything, it sounds like its a subset of 1.8?

Thanks again, it does help a lot! :)

[ElizabethSamuel-MSFT]

@ktvtrifork Glad to hear that our responses and updates have helped.

The importance of the requirement set is that it indicates general availability and guaranteed support. The add-in can safely include the features that shipped with the requirement set and, if you submit your add-in for validation through Microsoft AppSource and it's approved, it can be made available in the Microsoft AppSource marketplace and the in-app Office stores. To learn more about requirement sets, see Office versions and requirement sets.

You asked, "So if I read the table for OnSend correctly, basically any Office 2016 going forward (assuming it is updated) should be fine?" That's true for retail perpetual Office 2016. If the user is on a volume-licensed version, then that may not be the case. Also, the feature matrix is noted as a superset of 1.8 because these versions of Exchange on-premises don't support 1.8 but support the on-send feature, for example.

I'm leaving this thread open so that samantharamon can make further docs updates if needed.

Thanks again for your interest in Office Add-ins!