Merge pull request #647 from OfficeDev/main

[admin] Publish

Author: AlexJerabek

docs/develop/user-input.md

@@ -1,7 +1,7 @@
 ---
 title: Get user input for scripts
 description: Add parameters to Office Scripts so users can control their experience. 
-ms.date: 08/22/2023
+ms.date: 09/14/2023
 ms.localizationpriority: medium
 ---
 
@@ -12,7 +12,7 @@ Adding parameters to your script lets other users provide data for the script, w
 :::image type="content" source="../images/user-input-example.png" alt-text="The dialog box shown to users when a script with parameters is run.":::
 
 > [!IMPORTANT]
-> Currently, only select users in preview will be prompted to enter data for parameterized scripts in Excel on the web. Power Automate flows also support giving data to scripts through parameters.
+> Currently, only Excel on the web users will be prompted to enter data for parameterized scripts. Power Automate flows also support giving data to scripts through parameters.
 
 ## Example - Highlight large values
 
@@ -113,3 +113,4 @@ When adding input parameters and return values, consider the following allowance
 
 - [Pass data to and from scripts in Power Automate](power-automate-parameters-returns.md)
 - [Run Office Scripts in Excel with buttons](script-buttons.md)
+- [Set conditional formatting for cross-column comparisons](../resources/samples/conditional-formatting-parameters.md)

docs/overview/script-storage.md

@@ -1,7 +1,7 @@
 ---
 title: Office Scripts file storage and ownership
 description: Information about how Office Scripts are stored in Microsoft OneDrive and transferred between owners.
-ms.date: 08/29/2023
+ms.date: 09/08/2023
 ms.localizationpriority: medium
 ---
 
@@ -11,6 +11,9 @@ Office Scripts are stored as **.osts** files in your Microsoft OneDrive or a Sha
 
 Excel only recognizes and runs a script if it's in your OneDrive folder, a Sharepoint folder, or shared with the workbook. This means Excel needs internet connectivity to access Office Scripts.
 
+> [!NOTE]
+> Admin settings for Conditional Access in OneDrive and SharePoint affect Office Scripts. For more information, see the [Conditional Access section of Platform limits and requirements with Office Scripts](../testing/platform-limits.md#conditional-access).
+
 ## OneDrive
 
 The default behavior is that Office Scripts are stored in your OneDrive. The **.osts** files are found in the **/Documents/Office Scripts/** folder. Any edits made to these **.osts** files, such as renaming or deleting files, will be reflected in the Code Editor and Script Gallery.
@@ -37,7 +40,7 @@ To save a copy of a script to SharePoint, go to the **More options (…)** menu
 
 ## Restore deleted scripts
 
-When you delete a script in Excel, it goes to your OneDrive or SharePoint recycle bin. To restore a deleted script, follow the steps listed in [How to recover missing, deleted or corrupted items in SharePoint and OneDrive for work or school](https://support.microsoft.com/office/how-to-recover-missing-deleted-or-corrupted-items-in-sharepoint-and-onedrive-for-work-or-school-3d748edf-c072-46c9-81a4-4989056ebc87). Restoring an **.osts** file returns it to the **All scripts** list.
+When you delete a script in Excel, it goes to your OneDrive or SharePoint recycle bin. To restore a deleted script, follow the steps listed in [How to recover missing, deleted or corrupted items in SharePoint and OneDrive for work or school](https://support.microsoft.com/office/3d748edf-c072-46c9-81a4-4989056ebc87). Restoring an **.osts** file returns it to the **All scripts** list.
 
 A deleted script is unshared with the workbook. When you restore a script, it does **not** retain its script access. You will need to share the script again.
 

docs/resources/samples/conditional-formatting-parameters.md

@@ -0,0 +1,92 @@
+---
+title: Set conditional formatting for cross-column comparisons
+description: Learn how to apply conditional formatting and get input from the user.
+ms.date: 09/07/2023
+ms.localizationpriority: medium
+---
+
+# Set conditional formatting for cross-column comparisons
+
+This sample shows how to apply conditional formatting to a range. The conditions used are comparing values to those in an adjacent column.  Additionally, this sample uses [parameters to get user input](../../develop/user-input.md). This lets the person running the script select the range, the type of comparison, and the colors.
+
+## Sample code: Set conditional formatting
+
+```TypeScript
+/**
+ * Formats a range on the current sheet based on values in an adjacent column.
+ * @param rangeAddress The A1-notation range to format.
+ * @param compareTo The adjacent column to compare against.
+ * @param colorIfGreater The color of the cell if the value is greater than the adjacent column.
+ * @param colorIfEqual The color of the cell if the value is equal to the adjacent column.
+ * @param colorIfLess The color of the cell if the value is less than the adjacent column.
+ */
+function main(
+  workbook: ExcelScript.Workbook,
+  rangeAddress: string, compareTo: "Left" | "Right",
+  colorIfGreater: "Red" | "Green" | "Yellow" | "None",
+  colorIfLess: "Red" | "Green" | "Yellow" | "None",
+  colorIfEqual: "Red" | "Green" | "Yellow" | "None"
+) {
+  // Get the specified range.
+  const selectedSheet = workbook.getActiveWorksheet();
+  const range = selectedSheet.getRange(rangeAddress);
+
+  // Remove old conditional formatting.
+  range.clearAllConditionalFormats();
+
+  // Get the address of the first adjacent cell of the adjacent column.
+  let adjacentColumn: string;
+  if (compareTo == "Left") {
+    adjacentColumn = range.getColumnsBefore().getCell(0, 0).getAddress();
+  } else {
+    adjacentColumn = range.getColumnsAfter().getCell(0, 0).getAddress();
+  }
+
+  // Remove the worksheet name from the address to create a relative formula.
+  let formula = "=$" + adjacentColumn.substring(adjacentColumn.lastIndexOf("!") + 1);
+
+  // Set the conditional formatting based on the user's color choices.
+  setConditionalFormatting(
+    range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue(),
+    colorIfGreater, 
+    formula, 
+    ExcelScript.ConditionalCellValueOperator.greaterThan);
+  setConditionalFormatting(
+    range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue(),
+    colorIfEqual, 
+    formula, 
+    ExcelScript.ConditionalCellValueOperator.equalTo);
+  setConditionalFormatting(
+    range.addConditionalFormat(ExcelScript.ConditionalFormatType.cellValue).getCellValue(),
+    colorIfLess, 
+    formula, 
+    ExcelScript.ConditionalCellValueOperator.lessThan);
+}
+
+function setConditionalFormatting(
+  conditionalFormat: ExcelScript.CellValueConditionalFormat,
+   color: "Red" | "Green" | "Yellow" | "None", 
+   formula: string, 
+   operator: ExcelScript.ConditionalCellValueOperator
+) {
+  // Pick the fill and font colors based on the preset color choices.
+  if (color == "Red") {
+    conditionalFormat.getFormat().getFont().setColor("#9C0006");
+    conditionalFormat.getFormat().getFill().setColor("#FFC7CE");
+  } else if (color == "Green") {
+    conditionalFormat.getFormat().getFont().setColor("#001600");
+    conditionalFormat.getFormat().getFill().setColor("#C6EFCE");
+  } else if (color == "Yellow") {
+    conditionalFormat.getFormat().getFont().setColor("#9C5700");
+    conditionalFormat.getFormat().getFill().setColor("#FFEB9C");
+  } else { /* None */
+    return;
+  }
+
+  // Apply the conditional formatting.
+  conditionalFormat.setRule({ 
+    formula1: formula,
+    operator: operator
+  });
+}
+```

docs/resources/samples/samples-overview.md

@@ -30,6 +30,7 @@ This section contains [Office Scripts](../../overview/excel.md) based solutions
 | [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. |
 | [Row and column visibility samples](row-and-column-visibility.md) | A collection of samples that demonstrate how to show, hide, and freeze rows and columns. |
+| [Set conditional formatting for cross-column comparisons](conditional-formatting-parameters.md) | This sample applies formatting based on values in adjacent columns. It also gets user input through script parameters. |
 
 ## Beyond the basics
 
@@ -42,12 +43,12 @@ Check out the following end-to-end project that automates sample scenarios along
 | [Cross-reference workbooks](excel-cross-reference.md) | This sample uses Office Scripts and Power Automate to cross-reference and validate information in different workbooks. |
 | [Count blank rows in a specific sheet or in all sheets](count-blank-rows.md) | This sample detects if there are any blank rows in sheets where you anticipate data to be present and then report the blank row count for usage in a Power Automate flow. |
 | [Email chart and table images](email-images-chart-table.md) | This sample uses Office Scripts and Power Automate actions to create a chart and send that chart as an image by email. |
-| [External fetch calls](external-fetch-calls.md) | This sample uses `fetch` to get information from GitHub for the script. |
 | [Manage calculation mode in Excel](excel-calculation.md) | This sample shows how to use the calculation mode and calculate methods in Excel using Office Scripts. |
 | [Move rows across tables](move-rows-across-tables.md) | This sample shows how to move rows across tables by saving filters, then processing and reapplying the filters. |
 | [Output Excel data as JSON](get-table-data.md) | This solution shows how to output Excel table data as JSON to use in Power Automate. |
 | [Remove hyperlinks from each cell in an Excel worksheet](remove-hyperlinks-from-cells.md) | This sample clears all of the hyperlinks from the current worksheet. |
 | [Run a script on all Excel files in a folder](automate-tasks-on-all-excel-files-in-folder.md) | This project performs a set of automation tasks on all files situated in a folder on OneDrive for Business (can also be used for a SharePoint folder). It performs calculations on the Excel files, adds formatting, and inserts a comment that @mentions a colleague. |
+| [Use external fetch calls](external-fetch-calls.md) | This sample uses `fetch` to get information from GitHub for the script. |
 | [Write a large dataset](write-large-dataset.md) | This sample shows how to send a large range as smaller subranges. |
 
 ## Scenarios

docs/testing/platform-limits.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: 04/20/2023
+ms.date: 09/08/2023
 ms.localizationpriority: medium
 ---
 
@@ -76,6 +76,15 @@ Your browser needs third-party cookies enabled to show the **Automate** tab in E
 - [Firefox](https://support.mozilla.org/kb/disable-third-party-cookies)
 - [Safari](https://support.apple.com/guide/safari/manage-cookies-and-website-data-sfri11471/mac)
 
+## 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.
+
+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.)
+
 ## 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/testing/power-automate-troubleshooting.md

@@ -2,13 +2,13 @@
 title: Troubleshoot Office Scripts running in Power Automate
 description: Tips, platform information, and known issues with the integration between Office Scripts and Power Automate.
 ms.topic: troubleshooting-general
-ms.date: 04/20/2023
+ms.date: 09/08/2023
 ms.localizationpriority: medium
 ---
 
 # Troubleshoot Office Scripts running in Power Automate
 
-Power Automate lets you take your Office Script automation to the next level. However, because Power Automate runs scripts on your behalf in independent Excel sessions, there are a few important things to note.
+Power Automate runs scripts on your behalf in independent Excel sessions. This causes some behavioral changes that may create issues with certain scripts or scenarios. There are also limitations and behaviors from the Power Automate platform script writers should know. Be sure to read the articles [Troubleshoot Office Scripts](troubleshooting.md) and [Platform limits and requirements with Office Scripts](platform-limits.md), as much of that information also applies to scripts in flows.
 
 > [!TIP]
 > If you're just starting to use Office Scripts with Power Automate, please start with [Run Office Scripts with Power Automate](../develop/power-automate-integration.md) to learn about the platforms.

docs/testing/troubleshooting.md

@@ -2,7 +2,7 @@
 title: Troubleshoot Office Scripts
 description: Debugging tips and techniques for Office Scripts, as well as help resources.
 ms.topic: troubleshooting-general
-ms.date: 02/24/2023
+ms.date: 09/08/2023
 ms.localizationpriority: medium
 ---
 
@@ -13,7 +13,11 @@ As you develop Office Scripts, you may make mistakes. It's okay. You have the to
 > [!NOTE]
 > For troubleshooting advice specific to Office Scripts with Power Automate, see [Troubleshoot Office Scripts running in Power Automate](power-automate-troubleshooting.md).
 
-## Types of errors
+## Platform limits and requirements
+
+For a detailed list of limitations on the Office Scripts platform due to Excel, Power Automate, or other technologies, see [Platform limits and requirements with Office Scripts](platform-limits.md).
+
+## Script errors
 
 Office Scripts errors fall into one of two categories:
 
@@ -82,10 +86,6 @@ The following steps should help troubleshoot any problems related to the **Autom
 > [!NOTE]
 > There is a known issue that prevents scripts stored in SharePoint from always appearing in the recently used list. This occurs when your admin turns off Exchange Web Services (EWS). Your SharePoint-based scripts are still accessible and usable through the file dialog.
 
-## Platform limits
-
-For a detailed list of limitations on the Office Scripts platform due to Excel, Power Automate, or other tools, see [Platform limits and requirements with Office Scripts](./platform-limits.md).
-
 ## Help resources
 
 [Stack Overflow](https://stackoverflow.com/questions/tagged/office-scripts) is a community of developers willing to help with coding problems. Often, you'll be able to find the solution to your problem through a quick Stack Overflow search. If not, ask your question and tag it with the "office-scripts" tag. Be sure to mention you're creating an Office *Script*, not an Office *Add-in*.

docs/toc.yml

@@ -90,6 +90,8 @@ items:
         href: resources/samples/report-day-to-day-changes.md
       - name: Row and column visibility
         href: resources/samples/row-and-column-visibility.md
+      - name: Set conditional formatting for cross-column comparisons
+        href: resources/samples/conditional-formatting-parameters.md
     - name: Beyond the basics
       items:
       - name: Combine worksheets into a single workbook