From d265be5508c000fb31042285ce77aff6b5d0dc8c Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Fri, 30 Aug 2024 16:37:18 -0700 Subject: [PATCH 1/6] [All Hosts] (manifest) update 'requirements' article for get stated markup --- .../requirements-property-unified-manifest.md | 48 ++++++++++++++++++- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index efe33cc785..67dc76b079 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -1,7 +1,7 @@ --- title: Specify Office Add-in requirements in the unified manifest for Microsoft 365 description: Learn how to use requirements to configure on which host and platforms an add-in can be installed and which features are available. -ms.date: 07/03/2024 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -48,7 +48,7 @@ You can have more than one capability object. The following example shows how to ## Filter features -The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source of installation, such as [AppSource](/partner-center/marketplace-offers/submit-to-appsource-via-partner-center) or [Microsoft 365 Admin Center](/office/dev/add-ins/publish/publish). If the version of Office doesn't support the requirements specified for the feature, then the JSON node for the feature is removed from the manifest before it is installed in the Office application. +The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source at the time of add-in installation by Office. ### extensions.alternates.requirements @@ -167,6 +167,50 @@ For example, suppose you want to show context menus only in Excel versions that ] ``` +### extensions.getStartedMessages.requirements + +The objects in the `extensions.getStartedMessages` array provide information about an Office add-in that appears in various places in Office, such as the callout that appears in Office when an Office add-in is installed. There can be up to three objects in the array. If there is more than one, use the `extensions.getStartedMessages.requirements` property to ensure that no more than one of these objects is used in any given Office client. If `extensions.getStartedMessages` is omitted or all of the objects in the array are filtered out, the callout uses the values from the "name.short" and "description.short" manifest properties instead. + +For example, suppose an Excel add-in simplifies the process of adding conditional formatting to ranges. Some of the APIs that the add-in uses were introduced with the **ExcelApi 1.17** requirement set, but the add-in still provides useful functionality that only requires the **ExcelApi 1.6** requirement set. The `extensions.getStartedMessages` array can be configured to provide one description of the add-in for Excel clients that support the requirement sets from **1.6** to **1.16**, but a different description for clients that support **1.17** and later. The following is an example. Note that in this example, if the add-in is configured to be installable on Excel clients that don't support requirement set **1.6**, then on those clients neither of these getStartedMessage objects would be used. Instead, Office would use the "name.short" and "description.short" properties. + +```json +"extensions": [ + ... + { + ... + "getStartedMessages": [ + { + "title": "Contoso Excel Formatting", + "description": "Use conditional formatting with our add-in.", + "learnMoreUrl": "https://contoso.com/simple-conditional-formatting-details.html", + "requirements": { + "capabilities": [ + { + "name": "ExcelApi", + "minVersion": "1.6", + "maxVersion": "1.16" + } + ] + } + }, + { + "title": "Contoso Advanced Excel Formatting", + "description": "Use conditional formatting and dynamic formatting changes with our add-in.", + "learnMoreUrl": "https://contoso.com/advanced-conditional-formatting-details.html", + "requirements": { + "capabilities": [ + { + "name": "ExcelApi", + "minVersion": "1.17" + } + ] + } + } + ] + } +] +``` + ### extensions.ribbons.requirements The "extensions.ribbons" property is used to customize the Office application ribbon when the add-in is installed. The "requirements" subproperty can be used to prevent the customizations in some versions of Office. From c226611ef1f4c19733dfd44d2c963e4cde8cb048 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Fri, 30 Aug 2024 16:49:38 -0700 Subject: [PATCH 2/6] better date --- docs/develop/requirements-property-unified-manifest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index 67dc76b079..f36ff6d146 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -1,7 +1,7 @@ --- title: Specify Office Add-in requirements in the unified manifest for Microsoft 365 description: Learn how to use requirements to configure on which host and platforms an add-in can be installed and which features are available. -ms.date: 09/19/2024 +ms.date: 09/4/2024 ms.topic: how-to ms.localizationpriority: medium --- From eb9ed7ec694ab37a6b9a30b0582626b1c65c72b3 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Sat, 31 Aug 2024 10:36:42 -0700 Subject: [PATCH 3/6] restore passage --- docs/develop/requirements-property-unified-manifest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index f36ff6d146..ccefc9d7ab 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -48,7 +48,7 @@ You can have more than one capability object. The following example shows how to ## Filter features -The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source at the time of add-in installation by Office. +The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source of installation, such as [AppSource](/partner-center/marketplace-offers/submit-to-appsource-via-partner-center) or [Microsoft 365 Admin Center](/office/dev/add-ins/publish/publish). If the version of Office doesn't support the requirements specified for the feature, then the JSON node for the feature is removed from the manifest before it is installed in the Office application. ### extensions.alternates.requirements From ac586ef87919940a562198c1653481974c709a79 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Sat, 31 Aug 2024 11:00:47 -0700 Subject: [PATCH 4/6] add tip --- docs/develop/requirements-property-unified-manifest.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index ccefc9d7ab..cbe9d34c0d 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -50,6 +50,9 @@ You can have more than one capability object. The following example shows how to The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source of installation, such as [AppSource](/partner-center/marketplace-offers/submit-to-appsource-via-partner-center) or [Microsoft 365 Admin Center](/office/dev/add-ins/publish/publish). If the version of Office doesn't support the requirements specified for the feature, then the JSON node for the feature is removed from the manifest before it is installed in the Office application. +> [!TIP] +> Don't include a capability, formFactor, or scope requirement in a descendant object of "extensions" that is *less* restrictive than the corresponding capability, formFactor, or scope requirement in the ancestor "extensions.requirements" property, if there is one. Since the add-in can't be installed on clients that don't meet the ancestor requirement, no feature filtering would occur anyway. For example, if a "extensions.requirements.capabilities" property requires **Mailbox 1.10**, there is no point in requiring **Mailbox 1.9** or less in any descendant objects. + ### extensions.alternates.requirements The "extensions.alternates" property enables add-in developers to do the following: From 8f3fe6a44459dc222b9f26e451db2681d21650a5 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Sat, 31 Aug 2024 11:04:32 -0700 Subject: [PATCH 5/6] clarify --- docs/develop/requirements-property-unified-manifest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index cbe9d34c0d..c204406d81 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -51,7 +51,7 @@ You can have more than one capability object. The following example shows how to The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source of installation, such as [AppSource](/partner-center/marketplace-offers/submit-to-appsource-via-partner-center) or [Microsoft 365 Admin Center](/office/dev/add-ins/publish/publish). If the version of Office doesn't support the requirements specified for the feature, then the JSON node for the feature is removed from the manifest before it is installed in the Office application. > [!TIP] -> Don't include a capability, formFactor, or scope requirement in a descendant object of "extensions" that is *less* restrictive than the corresponding capability, formFactor, or scope requirement in the ancestor "extensions.requirements" property, if there is one. Since the add-in can't be installed on clients that don't meet the ancestor requirement, no feature filtering would occur anyway. For example, if a "extensions.requirements.capabilities" property requires **Mailbox 1.10**, there is no point in requiring **Mailbox 1.9** or less in any descendant objects. +> Don't include a capability, formFactor, or scope requirement in a descendant object of "extensions" that is *less* restrictive than the corresponding capability, formFactor, or scope requirement in the ancestor "extensions.requirements" property, if there is one. Since the add-in can't be installed on clients that don't meet the ancestor requirement, no feature filtering would occur anyway. For example, if a "extensions.requirements.capabilities" property requires **Mailbox 1.10**, there is no point in requiring **Mailbox 1.9** in any descendant objects. ### extensions.alternates.requirements From b6e62b659b46e7f3cbcac1b26e8b370ee9518423 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Wed, 4 Sep 2024 10:51:53 -0700 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Elizabeth Samuel --- docs/develop/requirements-property-unified-manifest.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index c204406d81..d4d0f10a60 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -51,7 +51,7 @@ You can have more than one capability object. The following example shows how to The "requirements" properties in descendant objects of "extensions" are used to block some features of an add-in while still allowing the add-in to be installed. The implementation of this filtering is done at the source of installation, such as [AppSource](/partner-center/marketplace-offers/submit-to-appsource-via-partner-center) or [Microsoft 365 Admin Center](/office/dev/add-ins/publish/publish). If the version of Office doesn't support the requirements specified for the feature, then the JSON node for the feature is removed from the manifest before it is installed in the Office application. > [!TIP] -> Don't include a capability, formFactor, or scope requirement in a descendant object of "extensions" that is *less* restrictive than the corresponding capability, formFactor, or scope requirement in the ancestor "extensions.requirements" property, if there is one. Since the add-in can't be installed on clients that don't meet the ancestor requirement, no feature filtering would occur anyway. For example, if a "extensions.requirements.capabilities" property requires **Mailbox 1.10**, there is no point in requiring **Mailbox 1.9** in any descendant objects. +> Don't include a capability, formFactor, or scope requirement in a descendant object of "extensions" that's *less* restrictive than the corresponding capability, formFactor, or scope requirement in the ancestor "extensions.requirements" property, if there is one. Since the add-in can't be installed on clients that don't meet the ancestor requirement, no feature filtering would occur anyway. For example, if an "extensions.requirements.capabilities" property requires **Mailbox 1.10**, there's no point in requiring **Mailbox 1.9** in any descendant objects. ### extensions.alternates.requirements @@ -172,7 +172,7 @@ For example, suppose you want to show context menus only in Excel versions that ### extensions.getStartedMessages.requirements -The objects in the `extensions.getStartedMessages` array provide information about an Office add-in that appears in various places in Office, such as the callout that appears in Office when an Office add-in is installed. There can be up to three objects in the array. If there is more than one, use the `extensions.getStartedMessages.requirements` property to ensure that no more than one of these objects is used in any given Office client. If `extensions.getStartedMessages` is omitted or all of the objects in the array are filtered out, the callout uses the values from the "name.short" and "description.short" manifest properties instead. +The objects in the `extensions.getStartedMessages` array provide information about an Office Add-in that appears in various places in Office, such as the callout that appears in Office when an Office Add-in is installed. There can be up to three objects in the array. If there's more than one, use the `extensions.getStartedMessages.requirements` property to ensure that no more than one of these objects is used in any given Office client. If `extensions.getStartedMessages` is omitted or all of the objects in the array are filtered out, the callout uses the values from the "name.short" and "description.short" manifest properties instead. For example, suppose an Excel add-in simplifies the process of adding conditional formatting to ranges. Some of the APIs that the add-in uses were introduced with the **ExcelApi 1.17** requirement set, but the add-in still provides useful functionality that only requires the **ExcelApi 1.6** requirement set. The `extensions.getStartedMessages` array can be configured to provide one description of the add-in for Excel clients that support the requirement sets from **1.6** to **1.16**, but a different description for clients that support **1.17** and later. The following is an example. Note that in this example, if the add-in is configured to be installable on Excel clients that don't support requirement set **1.6**, then on those clients neither of these getStartedMessage objects would be used. Instead, Office would use the "name.short" and "description.short" properties.