Merge branch 'main' into live

Author: github-actions

.openpublishing.redirection.json

@@ -1317,6 +1317,10 @@
         {
             "source_path": "docs/outlook/item-data.md",
             "redirect_url": "/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets"
+        },
+        {
+            "source_path": "docs/outlook/privacy-and-security.md",
+            "redirect_url": "/office/dev/add-ins/concepts/privacy-and-security"
         }
     ]
 }

docs/concepts/privacy-and-security.md

@@ -1,7 +1,7 @@
 ---
 title: Privacy and security for Office Add-ins
 description: Learn about the privacy and security aspects of the Office Add-ins platform.
-ms.date: 02/12/2025
+ms.date: 06/17/2025
 ms.localizationpriority: medium
 ---
 
@@ -66,10 +66,23 @@ You can make your Office Add-ins available to the public by publishing them to A
 
 End users and IT admins can turn off [optional connected experiences in Office](/deployoffice/privacy/optional-connected-experiences) desktop and mobile clients. For Office Add-ins, the impact of disabling the **Optional connected experiences** setting is that users can no longer access add-ins or the Microsoft 365 and Copilot store through these clients. However, certain Microsoft add-ins that are considered essential or business-critical, and add-ins deployed by an organization's IT admin through [Centralized Deployment](/microsoft-365/admin/manage/centralized-deployment-of-add-ins) will still be available. Additionally, add-ins and the Microsoft 365 and Copilot store remain available in Outlook on the web, regardless of the status of the setting.
 
-For more about Outlook-specific behavior, see [Privacy, permissions, and security for Outlook add-ins](../outlook/privacy-and-security.md#optional-connected-experiences).
-
 Note that if an IT admin disables the [use of connected experiences in Office](/deployoffice/privacy/manage-privacy-controls#policy-setting-for-most-connected-experiences), it has the same effect on add-ins as turning off just optional connected experiences.
 
+### Optional connected experiences in Outlook
+
+The following table describes the availability of add-ins on Outlook clients when optional connected experiences is turned off.
+
+|Client|Behavior when optional connected experiences is turned off|
+|-----|-----|
+|<ul><li>Web browser</li><li>[new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627)</li></ul>|Availability of add-ins and access to AppSource are unaffected, so users can continue to [manage their add-ins](https://support.microsoft.com/office/1ee261f9-49bf-4ba6-b3e2-2ba7bcab64c8), including admin-deployed ones.|
+|<ul><li>Windows (classic)<sup>1</sup></li><li>Mac</li></ul>|The **All Apps**<sup>2</sup> or **Get Add-ins** button isn't displayed, so users aren't able to manage their add-ins or access AppSource.|
+|<ul><li>Android</li><li>iOS</li></ul>|The **Get Add-ins** dialog shows only admin-deployed add-ins.|
+
+> [!NOTE]
+> <sup>1</sup> On Windows, support for this experience is available from Version 2008 (Build 13127.20296). For more details on your client version, see the update history page for [Microsoft 365](/officeupdates/update-history-office365-proplus-by-date) and how to [find your Office client version and update channel](https://support.microsoft.com/office/932788b8-a3ce-44bf-bb09-e334518b8b19).<br>
+>
+> <sup>2</sup> Starting in classic Outlook on Windows Version 2303 (Build 16215.10000), the **All Apps** button is used to manage add-ins and access AppSource.
+
 ## Addressing end users' privacy concerns
 
 This section describes the protection offered by the Office Add-ins platform from the customer's (end user's) perspective, and provides guidelines for how to support users' expectations and how to securely handle users' personally identifiable information (PII).
@@ -109,7 +122,31 @@ The add-in platform addresses end users' privacy concerns in the following ways.
 
   - Running in a web browser control allows the add-in to do almost anything a regular web page running in a browser can do but, at the same time, restricts the add-in to observe the same-origin policy for domain isolation and security zones.
 
-Outlook add-ins provide additional security and performance features through Outlook add-in specific resource usage monitoring. For more information, see [Privacy, permissions, and security for Outlook add-ins](../outlook/privacy-and-security.md).
+#### End users' perspective in Outlook
+
+The following points address end users' privacy concerns specific to Outlook.
+
+- End user's messages that are protected by Outlook's Information Rights Management (IRM) won't interact with add-ins in the following instances.
+
+  - When the IRM-protected message is accessed from Outlook on mobile devices.
+
+  - When the IRM-protected message contains a sensitivity label with the **Allow programmatic access** custom policy option set to `false`.
+
+  For more information on IRM support in add-ins, see [Mail items protected by IRM](../outlook/outlook-add-ins-overview.md#mail-items-protected-by-irm).
+
+- Granting the **restricted** permission allows the Outlook add-in to have limited access on only the current item. Granting the **read item** permission allows the Outlook add-in to access personal identifiable information, such as sender and recipient names and email addresses, on only the current item. For more information on Outlook add-in permissions, see [Understanding Outlook add-in permissions](../outlook/understanding-outlook-add-in-permissions.md).
+
+- Manifest files of installed Outlook add-ins are secured in the user's email account.
+
+- Outlook on Windows (classic) and on Mac monitor the performance of installed Outlook add-ins, exercise governance control, and make add-ins unavailable when they exceed limits in the following areas.
+
+  - Response time to activate
+
+  - Number of failures to activate or reactivate
+
+  - Memory usage
+
+  - CPU usage
 
 ### Developer guidelines to handle PII
 
@@ -178,11 +215,7 @@ The following example shows how a task pane add-in specifies the **read document
 
 For more information about permissions for task pane and content add-ins, see [Requesting permissions for API use in add-ins](../develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md).
 
-For more information about permissions for Outlook add-ins, see the following topics.
-
-- [Privacy, permissions, and security for Outlook add-ins](../outlook/privacy-and-security.md)
-
-- [Understanding Outlook add-in permissions](../outlook/understanding-outlook-add-in-permissions.md)
+For more information about permissions for Outlook add-ins, see [Understanding Outlook add-in permissions](../outlook/understanding-outlook-add-in-permissions.md).
 
 ### Follow the same-origin policy
 
@@ -306,10 +339,11 @@ The management and enforcement of Office settings is done with group policy sett
 | Block Web Add-ins | Allows you to prevent users from running Office Add-ins that use web technologies. |
 | Block the Office Store |  Allows you to prevent users from getting or running Office Add-ins that come from [AppSource](https://appsource.microsoft.com). |
 
+To specify permissions to install and manage Outlook add-ins in an organization that uses Exchange Online, configure administrative and user roles in the Exchange admin center. For more information, see [Specify the administrators and users who can install and manage add-ins for Outlook in Exchange Online](/exchange/clients-and-mobile-in-exchange-online/add-ins-for-outlook/specify-who-can-install-and-manage-add-ins).
+
 ## See also
 
 - [Requesting permissions for API use in add-ins](../develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md)
-- [Privacy, permissions, and security for Outlook add-ins](../outlook/privacy-and-security.md)
 - [Understanding Outlook add-in permissions](../outlook/understanding-outlook-add-in-permissions.md)
 - [Limits for activation and JavaScript API for Outlook add-ins](../outlook/limits-for-activation-and-javascript-api-for-outlook-add-ins.md)
 - [Addressing same-origin policy limitations in Office Add-ins](../develop/addressing-same-origin-policy-limitations.md)

docs/design/voice-guidelines.md

@@ -1,16 +1,16 @@
 ---
-title: Voice and tone guidelines for Office Add-ins
+title: Writing and style guidelines for Office Add-ins
 description: Learn best practices in writing user help and other text for Office Add-ins.
-ms.date: 05/18/2023
+ms.date: 06/16/2025
 ms.topic: best-practice
 ms.localizationpriority: medium
 ---
 
-# Voice and tone guidelines
+# Writing and style guidelines
 
-As you design your Office Add-ins, consider the voice that you use in your UI text and elements. Strive to match the voice and tone of the Office UI, which is conversational, engaging, and accessible to users.
+As you design your Office Add-ins, consider the voice you use in your UI text and elements. Strive to match the voice and tone of the Office UI, which is conversational, engaging, and accessible to users.
 
-- **Use a natural style.** Write the way that you speak. Avoid jargon and overly technical words and phrases. Use terms that are familiar to your users.
+- **Use a natural style.** Write the way you speak. Avoid jargon and overly technical words and phrases. Use terms that are familiar to your users.
 - **Use simple, direct language.** Use short words and sentences, and active voice in your text.
 - **Be consistent.** Use the same words for the same concepts throughout.
 - **Engage the user.** Address the user as "you". Avoid using third person. Use imperatives for user tasks.

docs/develop/dialog-best-practices.md

@@ -1,7 +1,7 @@
 ---
 title: Best practices and rules for the Office Dialog API
 description: Provides rules, limitations, and best practices for the Office Dialog API, such as best practices for a single-page application (SPA).
-ms.date: 02/25/2025
+ms.date: 06/17/2025
 ms.topic: best-practice
 ms.localizationpriority: medium
 ---
@@ -66,6 +66,7 @@ When your add-in calls [Office.context.devicePermission.requestPermissions](/jav
 >
 > - Add-ins that run in Office desktop clients or in browsers not based on Chromium automatically show a dialog requesting for a user's permission. The developer doesn't need to implement the device permission API on these platforms.
 > - Add-ins that run in Safari are blocked from accessing a user's device capabilities. The device permission API isn't supported in Safari.
+> - Access to a user's geolocation is only supported in **Outlook on the web** and new **Outlook on Windows**.
 
 ### Don't use the \_host\_info value
 

docs/develop/requesting-permissions-for-api-use-in-content-and-task-pane-add-ins.md

@@ -1,7 +1,7 @@
 ---
 title: Requesting permissions for API use in add-ins
 description: Learn about different permission levels to declare in the manifest of an add-in to specify the level of JavaScript API access.
-ms.date: 02/12/2025
+ms.date: 06/17/2025
 ms.localizationpriority: medium
 ---
 
@@ -10,13 +10,12 @@ ms.localizationpriority: medium
 This article describes the different permission levels that you declare in your add-in's manifest to specify the level of JavaScript API access your add-in requires for its features.
 
 > [!IMPORTANT]
-> This article applies to only non-Outlook add-ins. To learn about permission levels for Outlook add-ins, see [Outlook permissions model](../outlook/privacy-and-security.md#permissions-model).
+> This article applies to only non-Outlook add-ins. To learn about permission levels for Outlook add-ins, see [Understanding Outlook add-in permissions](../outlook/understanding-outlook-add-in-permissions.md).
 
 ## Permissions model
 
 A five-level JavaScript API access-permissions model provides the basis for privacy and security for users of your add-ins. The following figure shows the five levels of API permissions you can declare in your add-in's manifest.
 
-
 ![Levels of permissions for add-ins.](../images/office15-app-sdk-task-pane-app-permission.png)
 
 These permissions specify the subset of the API that the add-in [runtime](../testing/runtimes.md) allows your add-in to use when a user inserts, and then activates (trusts) your add-in. To declare the permission level your add-in requires, specify one of the permission values in the manifest. The markup varies depending on the type of manifest.

docs/excel/custom-functions-data-types-concepts.md

@@ -1,7 +1,7 @@
 ---
 title: Custom functions and data types
 description: Use Excel data types with your custom functions and Office Add-ins.
-ms.date: 10/17/2022
+ms.date: 06/15/2025
 ms.topic: overview
 ms.custom: scenarios:getting-started
 ms.localizationpriority: medium
@@ -57,7 +57,7 @@ The following code sample shows a custom function that takes an [EntityCellValue
 /**
  * Accept an entity value data type as a function input.
  * @customfunction
- * @param {any} value
+ * @param {Excel.EntityCellValue} value
  * @param {string} attribute
  * @returns {any} The text value of the entity.
  */

docs/excel/custom-functions-json-autogeneration.md

@@ -1,7 +1,7 @@
 ---
 title: Autogenerate JSON metadata for custom functions
 description: Use JSDoc tags to dynamically create your custom functions JSON metadata.
-ms.date: 07/11/2023
+ms.date: 06/15/2025
 ms.localizationpriority: medium
 ---
 
@@ -34,7 +34,7 @@ The plugin is [CustomFunctionsMetadataPlugin](https://github.com/OfficeDev/Offic
 
 ### Multiple custom function source files
 
-If, and only if, you have organized your custom functions into multiple source files, there are additional steps. 
+If, and only if, you have organized your custom functions into multiple source files, there are additional steps.
 
 1. In the webpack.config.js file, replace the string value of `input` with an array of string URLs that point to each of the files. The following is an example:
 
@@ -395,6 +395,22 @@ By specifying a parameter type, Excel will convert values into that type before
 
 A single value may be represented using one of the following types: `boolean`, `number`, `string`.
 
+### Cell value type
+
+Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are:
+
+- `Excel.CellValue`
+- `Excel.BooleanCellValue`
+- `Excel.DoubleCellValue`
+- `Excel.EntityCellValue`
+- `Excel.ErrorCellValue`
+- `Excel.LinkedEntityCellValue`
+- `Excel.LocalImageCellValue`
+- `Excel.StringCellValue`
+- `Excel.WebImageCellValue`
+
+For a code sample using the `Excel.EntityCellValue` type, see [Input an entity value](custom-functions-data-types-concepts.md#input-an-entity-value).
+
 ### Matrix type
 
 Use a two-dimensional array type to have the parameter or return value be a matrix of values. For example, the type `number[][]` indicates a matrix of numbers and `string[][]` indicates a matrix of strings.

docs/excel/custom-functions-json.md

@@ -1,7 +1,7 @@
 ---
 title: Manually create JSON metadata for custom functions in Excel
 description: Define JSON metadata for custom functions in Excel and associate your function ID and name properties.
-ms.date: 10/10/2022
+ms.date: 06/15/2025
 ms.localizationpriority: medium
 ---
 
@@ -142,6 +142,8 @@ The `allowCustomDataForDataTypeAny` property is a boolean data type. Setting thi
 > [!NOTE]
 > Unlike most of the other JSON metadata properties, `allowCustomDataForDataTypeAny` is a top-level property and contains no sub-properties. See the preceding [JSON metadata code sample](#json-metadata-example) for an example of how to format this property.
 
+If your custom function uses the `cellValueType` [parameter](#parameters), then setting the `allowCustomDataForDataTypeAny` isn't required to accept data types as parameters and return values.
+
 ### allowErrorForDataTypeAny
 
 The `allowErrorForDataTypeAny` property is a boolean data type. Setting the value to `true` allows a custom function to process errors as input values. All parameters with the type `any` or `any[][]` can accept errors as input values when `allowErrorForDataTypeAny` is set to `true`. The default `allowErrorForDataTypeAny` value is `false`.
@@ -185,9 +187,24 @@ The `parameters` property is an array of parameter objects. The following table
 |  `dimensionality`  |  string  |  No  |  Must be either `scalar` (a non-array value) or `matrix` (a 2-dimensional array).  |
 |  `name`  |  string  |  Yes  |  The name of the parameter. This name is displayed in Excel's IntelliSense.  |
 |  `type`  |  string  |  No  |  The data type of the parameter. Can be `boolean`, `number`, `string`, or `any`, which allows you to use of any of the previous three types. If this property is not specified, the data type defaults to `any`. |
+| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the case-insensitive values `cellvalue`, `booleancellvalue`, `doublecellvalue`, `entitycellvalue`, `errorcellvalue`, `linkedentitycellvalue`, `localimagecellvalue`, `stringcellvalue`, and `webimagecellvalue`. <br/><br/>The `type` field must have the value `any` to use the `cellValueType` subfield. |
 |  `optional`  | boolean | No | If `true`, the parameter is optional. |
 |`repeating`| boolean | No | If `true`, parameters populate from a specified array. Note that functions all repeating parameters are considered optional parameters by definition.  |
 
+> [!TIP]
+> See the following code snippet for an example of how to format the `cellValueType` parameter in JSON metadata.
+>
+> ```json
+> "parameters": [
+>     {
+>         "name": "range",
+>         "description": "the input range",
+>         "type": "any",
+>             "cellValueType": "webimagecellvalue"
+>     }
+> ]
+> ```
+
 ### result
 
 The `result` object defines the type of information that is returned by the function. The following table lists the properties of the `result` object.

docs/excel/excel-data-types-entity-card.md

@@ -92,6 +92,9 @@ The entity value JSON in the next code snippet shows a `card` layout with nested
 
 Within each card section you can specify elements like `layout`, `title`, and `properties`. The `layout` key uses the [`CardLayoutListSection`](/javascript/api/excel/excel.cardlayoutlistsection) object and accepts the value `"List"`. The `properties` key accepts an array of strings. Note that the `properties` values, such as `"Product ID"`, have corresponding data types in the preceding [Card properties](#card-properties) article section. Sections can also be collapsible and can be defined with boolean values as collapsed or not collapsed when the entity card is opened in the Excel UI.
 
+> [!TIP]
+> The `layout` key also has additional display options available beyond `"List"` within card sections. Use `"Table"` for [Excel.CardLayoutTableSection](/javascript/api/excel/excel.cardlayouttablesection) and `"TwoColumn"` for [Excel.CardLayoutTwoColumnSection](/javascript/api/excel/excel.cardlayouttwocolumnsection). Note that the `"TwoColumn"` layout is only available in preview.
+
 > [!NOTE]
 > To experiment with this code snippet in a complete sample, open [Script Lab](../overview/explore-with-script-lab.md) in Excel and select [Data types: Create entity cards from data in a table](https://github.com/OfficeDev/office-js-snippets/blob/prod/samples/excel/20-data-types/data-types-entity-values.yaml) in our **Samples** library.
 

docs/includes/outlook-bundle-js.md

@@ -1,5 +1,4 @@
 > [!TIP]
 >
 > - There's no direct method to determine the Outlook profile GUID and mail account encoding used in the **bundle.js** file path. The most effective approach to locate your add-in's **bundle.js** file is to manually inspect each folder until you locate the **Javascript** folder that contains your add-in's ID.
->
-> - If the **bundle.js** file doesn't appear in the **Wef** folder and your add-in is installed or sideloaded, restart Outlook. Alternatively, [remove your add-in](../outlook/sideload-outlook-add-ins-for-testing.md#remove-a-sideloaded-add-in) from Outlook, then [sideload](../outlook/sideload-outlook-add-ins-for-testing.md) it again.
+> - The **bundle.js** file is downloaded to the local **Wef** folder when the add-in is first installed. It's refreshed every time the Outlook client starts or is restarted. If the **bundle.js** file doesn't appear in the **Wef** folder and your add-in is installed or sideloaded, restart Outlook. Alternatively, [remove your add-in](../outlook/sideload-outlook-add-ins-for-testing.md#remove-a-sideloaded-add-in) from Outlook, then [sideload](../outlook/sideload-outlook-add-ins-for-testing.md) it again.