Merge pull request #653 from OfficeDev/main

[admin] Publish

Author: AlexJerabek

docs/develop/power-automate-integration.md

@@ -2,7 +2,7 @@
 title: Run Office Scripts with Power Automate
 description: How to get Office Scripts for Excel working with a Power Automate workflow.
 ms.topic: integration
-ms.date: 08/10/2023
+ms.date: 09/19/2023
 ms.localizationpriority: medium
 ---
 
@@ -42,8 +42,11 @@ This opens a task pane with several options to begin connecting your Office Scri
 > [!NOTE]
 > The **Run script** Power Automate action only supports scripts stored in your OneDrive. To run scripts shared in SharePoint libraries, use the **Run script from SharePoint library (Preview)** action. This action is currently in preview and is subject to change based on feedback. If you encounter any issues with this action, please report them through the **Help** > **Give Feedback** option in Power Automate.
 
-> [!IMPORTANT]
-> The "Run script" action gives people who use the Excel connector significant access to your workbook and its data. Additionally, there are security risks with scripts that make external API calls, as explained in [External calls from Power Automate](external-calls.md). If your admin is concerned with the exposure of highly sensitive data, they can either turn off the Excel Online connector or restrict access to Office Scripts through the [Office Scripts administrator controls](/microsoft-365/admin/manage/manage-office-scripts-settings).
+### Data security in Office Scripts with Power Automate
+
+The "Run script" action gives people who use the Excel connector significant access to your workbook and its data. Additionally, there are security risks with scripts that make external API calls, as explained in [External calls from Power Automate](external-calls.md). If your admin is concerned with the exposure of highly sensitive data, they can either turn off the Excel Online connector or restrict access to Office Scripts through the [Office Scripts administrator controls](/microsoft-365/admin/manage/manage-office-scripts-settings).
+
+For admins who have enabled Conditional Access policies for unmanaged devices in their tenant, it's a best practice to disable Power Automate on unmanaged devices. This process is detailed in the blog post [Control Access to Power Apps and Power Automate with Azure AD Conditional Access Policies](https://devblogs.microsoft.com/premier-developer/control-access-to-power-apps-and-power-automate-with-azure-ad-conditional-access-policies/).
 
 ## Data transfer in flows for scripts
 

docs/images/data-validation-error.png

@@ -1,21 +1,25 @@
 ---
-title: Create a dropdown list using data validation
+title: "Data validation: dropdown lists, prompts, and warning pop-ups"
 description: Learn how to add data validation to a cell and give the user a selection of values to enter.
-ms.date: 09/08/2023
+ms.date: 09/20/2023
 ms.localizationpriority: medium
 ---
 
-# Create a dropdown list using data validation
+# Data validation: dropdown lists, prompts, and warning pop-ups
 
-This script creates a dropdown selection list for a cell. It uses the existing values of the selected range as the choices for the list.
+Data validation helps the user ensure consistency in a worksheet. Use these features to limit what can be entered into a cell and provide warnings or errors to users when those conditions aren't met. To learn more about data validation in Excel, see [Apply data validation to cells](https://support.microsoft.com/office/29fecbcc-d1b9-42c1-9d76-eff3ce5f7249).
+
+## Create a dropdown list using data validation
+
+The following sample creates a dropdown selection list for a cell. It uses the existing values of the selected range as the choices for the list.
 
 :::image type="content" source="../../images/sample-data-validation.png" alt-text="A worksheet showing a range of three cells containing color choices 'red, blue, green' and next to it, the same choices shown in a dropdown list.":::
 
 ```TypeScript
 function main(workbook: ExcelScript.Workbook) {
   // Get the values for data validation.
-  let selectedRange = workbook.getSelectedRange();
-  let rangeValues = selectedRange.getValues();
+  const selectedRange = workbook.getSelectedRange();
+  const rangeValues = selectedRange.getValues();
 
   // Convert the values into a comma-delimited string.
   let dataValidationListString = "";
@@ -29,8 +33,8 @@ function main(workbook: ExcelScript.Workbook) {
   selectedRange.clear(ExcelScript.ClearApplyTo.contents);
 
   // Apply the data validation to the first cell in the selected range.
-  let targetCell = selectedRange.getCell(0,0);
-  let dataValidation = targetCell.getDataValidation();
+  const targetCell = selectedRange.getCell(0,0);
+  const dataValidation = targetCell.getDataValidation();
 
   // Set the content of the dropdown list.
   dataValidation.setRule({
@@ -41,3 +45,72 @@ function main(workbook: ExcelScript.Workbook) {
     });
 }
 ```
+
+## Add a prompt to a range
+
+This example creates a prompt note that appears when a user enters the given cells. This is used to remind users about input requirements, without strict enforcement.
+
+:::image type="content" source="../../images/data-validation-prompt.png" alt-text="A prompt with the title 'First names only' and the message 'Only enter the first name of the employee, not the full name.' next to a worksheet with some names in cells.":::
+
+```TypeScript
+/**
+ * This script creates a text prompt that's shown in C2:C8 when a user enters the cell.
+ */
+function main(workbook: ExcelScript.Workbook) {
+    // Get the data validation object for C2:C8 in the current worksheet.
+    const selectedSheet = workbook.getActiveWorksheet();
+    const dataValidation = selectedSheet.getRange("C2:C8").getDataValidation();
+
+    // Clear any previous validation to avoid conflicts.
+    dataValidation.clear();
+
+    // Create a prompt to remind users to only enter first names in this column.
+    const prompt: ExcelScript.DataValidationPrompt = {
+      showPrompt: true,
+      title: "First names only",
+      message: "Only enter the first name of the employee, not the full name."
+    }
+    dataValidation.setPrompt(prompt);
+}
+```
+
+## Alert the user when invalid data is entered
+
+The following sample script prevents the user from entering anything other than positive numbers into a range. If they try to put anything else, an error message pops up and indicates the problem.
+
+:::image type="content" source="../../images/data-validation-error.png" alt-text="An error message with the title 'Invalid data' and the message 'Positive numbers only.' next to a cell with a negative number.":::
+
+```TypeScript
+/**
+ * This script creates a data validation rule for the range B2:B5.
+ * All values in that range must be a positive number.
+ * Attempts to enter other values are blocked and an error message appears.
+ */
+function main(workbook: ExcelScript.Workbook) {
+    // Get the range B2:B5 in the active worksheet.
+    const currentSheet = workbook.getActiveWorksheet();
+    const positiveNumberOnlyCells = currentSheet.getRange("B2:B5");
+
+    // Create a data validation rule to only allow positive numbers.
+    const positiveNumberValidation: ExcelScript.BasicDataValidation = {
+        formula1: "0",
+        operator: ExcelScript.DataValidationOperator.greaterThan
+    };
+    const positiveNumberOnlyRule: ExcelScript.DataValidationRule = {
+      wholeNumber: positiveNumberValidation
+    };
+
+    // Set the rule on the range.
+    const rangeDataValidation = positiveNumberOnlyCells.getDataValidation();
+    rangeDataValidation.setRule(positiveNumberOnlyRule);
+
+    // Create an alert to appear when data other than positive numbers are entered.
+    const positiveNumberOnlyAlert: ExcelScript.DataValidationErrorAlert = {
+        message: "Positive numbers only.",
+        showAlert: true,
+        style: ExcelScript.DataValidationAlertStyle.stop,
+        title: "Invalid data"
+    };
+    rangeDataValidation.setErrorAlert(positiveNumberOnlyAlert);
+}
+```

docs/images/data-validation-prompt.png

@@ -1,7 +1,7 @@
 ---
 title: Office Scripts samples
 description: Available Office Scripts samples and scenarios.
-ms.date: 09/08/2023
+ms.date: 09/20/2023
 ms.localizationpriority: medium
 ---
 
@@ -26,6 +26,7 @@ This section contains [Office Scripts](../../overview/excel.md) based solutions
 | [Add comments in Excel](add-excel-comments.md) | This sample adds comments to a cell including @mentioning a colleague. |
 | [Add images to a workbook](add-image-to-workbook.md) | This sample adds an image to a workbook and copies an image across sheets.|
 | [Copy multiple Excel tables into a single table](copy-tables-combine.md) | This sample combines data from multiple Excel tables into a single table that includes all the rows. |
+| [Data validation: dropdown lists, prompts, and warning pop-ups](data-validation-samples.md) | These samples show how to use data validation to mandate specific conditions for cell data and how the user is alerted to these rules. |
 | [Create a workbook table of contents](table-of-contents.md) | This sample creates a table of contents with links to each worksheet. |
 | [JavaScript `Date` samples](javascript-dates.md) | A collection of samples that show how to translate between JavaScript and Excel date formats. |
 | [Record day-to-day changes in Excel and report them with a Power Automate flow](report-day-to-day-changes.md) | This sample uses a scheduled Power Automate flow to record daily readings and report the changes. |

docs/resources/samples/data-validation-samples.md

@@ -2,7 +2,7 @@
 title: Platform limits and requirements with Office Scripts
 description: Resource limits and browser support for Office Scripts when used with Excel.
 ms.topic: limits-and-quotas
-ms.date: 09/08/2023
+ms.date: 09/19/2023
 ms.localizationpriority: medium
 ---
 
@@ -78,13 +78,16 @@ Your browser needs third-party cookies enabled to show the **Automate** tab in E
 
 ## Conditional Access
 
-[Conditional Access](/azure/active-directory/conditional-access/overview) policies can restrict access to SharePoint and OneDrive for [unmanaged devices](/sharepoint/control-access-from-unmanaged-devices). If your device isn't managed by the tenant, you may not have access to specific scripts, or may only be able to access them through the browser.
+[Conditional Access](/azure/active-directory/conditional-access/overview) policies restrict access to SharePoint and OneDrive for [unmanaged devices](/sharepoint/control-access-from-unmanaged-devices). If your device isn't managed by the tenant, you may not have access to specific scripts, or may only be able to access them through the browser.
 
 If you script is blocked by Conditional Access policies, you'll receive one of two error messages. These messages also surface in Power Automate if your flow is run from an unmanaged device.
 
 - "Due to organizational policies, you can’t access this resource from this untrusted device."
 - "We can't find this script. It may have been deleted by another user." (If your version of Excel is older.)
 
+> [!IMPORTANT]
+> Administrators should consider blocking all access to Power Automate from unmanaged devices. This process is detailed in the blog post [Control Access to Power Apps and Power Automate with Azure AD Conditional Access Policies](https://devblogs.microsoft.com/premier-developer/control-access-to-power-apps-and-power-automate-with-azure-ad-conditional-access-policies/).
+
 ## API support on older Excel versions
 
 Some Office Scripts APIs may not be supported by Excel for Windows or Excel for Mac, especially older builds. These include newer APIs and APIs for web-only features. If a script contains unsupported APIs, the Code Editor displays a warning. If you try to run such a script, it won't run. Instead, the **Script Run Status** task pane displays a warning message that says, "This script currently must be run on Excel for the web. Open the workbook in the browser then try again, or contact the script owner for help."

docs/resources/samples/samples-overview.md

@@ -78,7 +78,7 @@ items:
         href: resources/samples/add-image-to-workbook.md
       - name: Copy multiple tables into single table
         href: resources/samples/copy-tables-combine.md
-      - name: Create a drop-down list using data validation
+      - name: "Data validation: dropdown lists, prompts, and warning pop-ups"
         href: resources/samples/data-validation-samples.md
       - name: Create a workbook table of contents
         href: resources/samples/table-of-contents.md