[excel] (Power Automate) Reorganize Power Automate limits about external calls (#612)

* Reorganize Power Automate limits about external calls

* Adjust Workbook.refreshAllDataConnections in the PA method list

* Apply suggestions from code review

Co-authored-by: Alison McKay <[email protected]>

---------

Co-authored-by: Alison McKay <[email protected]>

Author: AlexJerabek

docs/develop/external-calls.md

@@ -1,7 +1,7 @@
 ---
 title: External API call support in Office Scripts
 description: Support and guidance for making external API calls in an Office Script.
-ms.date: 03/15/2023
+ms.date: 04/20/2023
 ms.localizationpriority: medium
 ---
 
@@ -79,12 +79,7 @@ You can [apply IRM settings](/microsoft-365/compliance/apply-irm-to-a-list-or-li
 
 ## External calls from Power Automate
 
-Any external API call fails when a script is run with Power Automate. This is a behavioral difference between running a script through the Excel application and through Power Automate. Be sure to check your scripts for such references before building them into a flow.
-
-You'll have to use [HTTP with Azure AD](/connectors/webcontents/) or other equivalent actions to pull data from or push it to an external service.
-
-> [!WARNING]
-> External calls made through the Power Automate [Excel Online connector](/connectors/excelonlinebusiness) fail in order to help uphold existing data loss prevention policies. However, scripts that are run through Power Automate are done so outside of your organization, and outside of your organization's firewalls. For additional protection from malicious users in this external environment, your admin can control the use of Office Scripts. Your admin can either disable the Excel Online connector in Power Automate or turn off Office Scripts for Excel through the [Office Scripts administrator controls](/microsoft-365/admin/manage/manage-office-scripts-settings).
+[!INCLUDE [External calls in Power Automate](../includes/external-calls-power-automate.md)]
 
 ## See also
 

docs/includes/external-calls-power-automate.md

@@ -0,0 +1,6 @@
+External API calls fail when a script is run through Power Automate. A `fetch` call will give the error message "Runtime error: Line X: fetch is not defined". Be sure to check your scripts for such references before building them into a flow.
+
+You'll have to use [HTTP with Azure AD](/connectors/webcontents/) or other equivalent actions to pull data from or push it to an external service.
+
+> [!WARNING]
+> External calls made through the Power Automate [Excel Online connector](/connectors/excelonlinebusiness) fail in order to help uphold existing data loss prevention policies. However, scripts that are run through Power Automate are done so outside of your organization, and outside of your organization's firewalls. For additional protection from malicious users in this external environment, your admin can control the use of Office Scripts. Your admin can either disable the Excel Online connector in Power Automate or turn off Office Scripts for Excel through the [Office Scripts administrator controls](/microsoft-365/admin/manage/manage-office-scripts-settings).

docs/includes/platform-requirements.md

@@ -1,7 +1,7 @@
 To use Office Scripts, you'll need the following.
 
 1. Excel for Windows (version 2210 or higher), Excel for Mac, or Excel on the web.
-    *The [Action Recorder](../overview/excel.md#action-recorder) is not yet available in the [Semi-Annual Enterprise Channel](/deployoffice/updates/overview-update-channels#semi-annual-enterprise-channel-overview).*
+    - *The [Action Recorder](../overview/excel.md#action-recorder) is not yet available in the [Semi-Annual Enterprise Channel](/deployoffice/updates/overview-update-channels#semi-annual-enterprise-channel-overview).*
 1. OneDrive for Business.
 1. Any commercial or educational Microsoft 365 license with access to the Microsoft 365 Office desktop apps, such as:
     - Office 365 Business

docs/resources/samples/add-image-to-workbook.md

@@ -1,7 +1,7 @@
 ---
 title: Add images to a workbook
 description: Learn how to use Office Scripts to add an image to a workbook and copy it across sheets.
-ms.date: 07/12/2021
+ms.date: 04/20/2023
 ms.localizationpriority: medium
 ---
 
@@ -49,6 +49,9 @@ function main(workbook: ExcelScript.Workbook)
 
 ## Sample code: Add an image from a URL to a workbook
 
+> [IMPORTANT]
+> This sample won't work in Power Automate because of the [`fetch` call](../../develop/external-calls.md#external-calls-from-power-automate).
+
 ```TypeScript
 async function main(workbook: ExcelScript.Workbook) {
   // Fetch the image from a URL.

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/11/2023
+ms.date: 04/20/2023
 ms.localizationpriority: medium
 ---
 
@@ -42,6 +42,22 @@ Additional Power Automate platform usage limitations can be found in the followi
 - [Limits and configuration in Power Automate](/power-automate/limits-and-config)
 - [Known issues and limitations for the Excel Online (Business) connector](/connectors/excelonlinebusiness/#known-issues-and-limitations)
 
+## Power Automate specific restrictions
+
+There are a few important differences between running a script in the Excel application and running a script as part of a Power Automate flow.
+
+### No external calls from a script
+
+[!INCLUDE [External calls in Power Automate](../includes/external-calls-power-automate.md)]
+
+### API behavior differences
+
+Some APIs behave differently when run with Power Automate. Others fail due to their reliance on the Excel UI. The full lists are found in [Troubleshoot Office Scripts running in Power Automate](power-automate-troubleshooting.md).
+
+### ISO strict Open XML workbooks aren't supported
+
+The **Excel Business (Online)** connector's **Run script** action doesn't support workbooks with the [ISO strict version of the Excel Workbook file format](https://www.loc.gov/preservation/digital/formats/fdd/fdd000401.shtml). Flows with this type of workbook return a "BadGateway" error when trying to run a script. This is due to coauthoring restrictions. Please save workbooks as the standard Excel Workbook format for use with Power Automate.
+
 ## Teams support
 
 [!INCLUDE [Teams support note](../includes/teams-support-note.md)]

docs/testing/power-automate-troubleshooting.md

@@ -2,7 +2,7 @@
 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: 03/27/2023
+ms.date: 04/20/2023
 ms.localizationpriority: medium
 ---
 
@@ -32,6 +32,7 @@ The following methods throw an error and fail when called from a script in a Pow
 | [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `getActiveSlicer` |
 | [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `getSelectedRange` |
 | [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `getSelectedRanges` |
+| [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `refreshAllDataConnections` |
 
 ### Script methods with a default behavior in Power Automate flows
 
@@ -42,9 +43,9 @@ The following methods use a default behavior, in lieu of any user's current stat
 | [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `getActiveWorksheet` | Returns either the first worksheet in the workbook or the worksheet currently activated by the `Worksheet.activate` method. |
 | [Worksheet](/javascript/api/office-scripts/excelscript/excelscript.worksheet) | `activate` | Marks the worksheet as the active worksheet for purposes of `Workbook.getActiveWorksheet`. |
 
-## Data refresh not supported in Power Automate
+## PivotTable refresh not supported in Power Automate
 
-Office Scripts can't refresh data when run in Power Automate. Methods such as `PivotTable.refresh` do nothing when called in a flow. Additionally, Power Automate doesn't trigger a data refresh for formulas that use workbook links.
+Office Scripts can't refresh data when run in Power Automate. PivotTable methods such as `PivotTable.refresh` do nothing when called in a flow. `Workbook.refreshAllDataConnections` throws an error. Additionally, Power Automate doesn't trigger a data refresh for formulas that use workbook links.
 
 ### Script methods that do nothing when run in Power Automate flows
 
@@ -53,7 +54,6 @@ The following methods do nothing in a script when called through Power Automate.
 | Class | Method |
 |--|--|
 | [PivotTable](/javascript/api/office-scripts/excelscript/excelscript.pivottable) | `refresh` |
-| [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `refreshAllDataConnections` |
 | [Workbook](/javascript/api/office-scripts/excelscript/excelscript.workbook) | `refreshAllPivotTables` |
 | [Worksheet](/javascript/api/office-scripts/excelscript/excelscript.worksheet) | `refreshAllPivotTables` |
 
@@ -86,10 +86,6 @@ There are two reasons that the parameters or returned data of a script are not a
 
 The signature of a script is stored with the **Excel Business (Online)** connector when it is created. Remove the old connector and create a new one to get the latest parameters and return values for the **Run script** action.
 
-## ISO strict Open XML workbooks aren't supported
-
-The **Excel Business (Online)** connector's **Run script** action doesn't support workbooks with the [ISO strict version of the Excel Workbook file format](https://www.loc.gov/preservation/digital/formats/fdd/fdd000401.shtml). Flows with this type of workbook return a "BadGateway" error when trying to run a script. This is due to coauthoring restrictions. Please save workbooks as the standard Excel Workbook format for use with Power Automate.
-
 ## See also
 
 - [Troubleshoot Office Scripts](troubleshooting.md)