[excel] (Power Automate) Show how to handle large datasets in Power Automate (#583)

* Partial work

* Add scripts

* Add flow steps

* Fix quotation marks

* Typo fixes

* Add cross-links for discoverability

* Apply suggestions from code review

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

* Typo fix

* Fix alt-text

* Standardize condition inut for PA walkthroughs

---------

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

Author: AlexJerabek

docs/images/write-large-dataset-1.png

@@ -1,17 +1,19 @@
 ---
 title: Write a large dataset
 description: Learn how to split a large dataset into smaller write operations in Office Scripts.
-ms.date: 05/13/2021
+ms.date: 02/24/2023
 ms.localizationpriority: medium
 ---
 
 # Write a large dataset
 
 The `Range.setValues()` API puts data in a range. This API has limitations depending on various factors, such as data size and network settings. This means that if you attempt to write a massive amount of information to a workbook as a single operation, you'll need to write the data in smaller batches in order to reliably update a [large range](../../testing/platform-limits.md).
 
+The first part of the sample shows how to write a large dataset in Excel. The second part expands the example to be part of a Power Automate flow. This is necessary if your script takes longer to run than the [Power Automate action timeout](../../testing/platform-limits.md#power-automate).
+
 For performance basics in Office Scripts, please read [Improve the performance of your Office Scripts](../../develop/web-client-performance.md).
 
-## Sample code: Write a large dataset
+## Sample 1: Write a large dataset in batches
 
 This script writes rows of a range in smaller parts. It selects 1000 cells to write at a time. Run the script on a blank worksheet to see the update batches in action. The console output gives further insight into what's happening.
 
@@ -141,6 +143,119 @@ function getRandomString(length: number): string {
 }
 ```
 
-## Training video: Write a large dataset
+### Training video: Write a large dataset
 
 [Watch Sudhi Ramamurthy walk through this sample on YouTube](https://youtu.be/BP9Kp0Ltj7U).
+
+## Sample 2: Write data in batches from a Power Automate flow
+
+For this sample, you'll need to complete the following steps.
+
+1. Create a workbook in OneDrive named **SampleData.xlsx**.
+1. Create a second workbook in OneDrive named **TargetWorkbook.xlsx**.
+1. Open  **SampleData.xlsx**.
+1. Add sample data. You can use the script from the [Write a large dataset in batches](#sample-1-write-a-large-dataset-in-batches) section to generate this data.
+1. Create and save both of the following scripts.
+1. Follow the steps under [Power Automate flow: Read and write data in a loop](#power-automate-flow-read-and-write-data-in-a-loop) to create the flow.
+
+### Sample code: Read part of a workbook
+
+```TypeScript
+function main(workbook: ExcelScript.Workbook, startRow: number, batchSize: number) : string[][] {
+    // This sample only reads the first worksheet in the workbook.
+    const sheet = workbook.getWorksheets()[0];
+
+    // Get the boundaries of the range.
+    // Note that we're assuming usedRange is too big to read or write as a single range.
+    const usedRange = sheet.getUsedRange();
+    const lastColumnIndex = usedRange.getLastColumn().getColumnIndex();
+    const lastRowindex = usedRange.getLastRow().getRowIndex();
+
+    // If we're starting past the last row, exit the script.
+    if (startRow > lastRowindex) {
+        return [[]];
+    }
+
+    // Get the next batch or the rest of the rows, whichever is smaller.
+    const rowCountToRead = Math.min(batchSize, (lastRowindex - startRow + 1));
+    const rangeToRead = sheet.getRangeByIndexes(startRow, 0, rowCountToRead, lastColumnIndex + 1);
+    return rangeToRead.getValues() as string[][];
+}
+
+```
+
+### Sample code: Write part of a workbook
+
+```TypeScript
+function main(workbook: ExcelScript.Workbook, data: string[][], currentRow: number, batchSize: number): boolean {
+  // Get the first worksheet.
+  const sheet = workbook.getWorksheets()[0];
+
+  // Set the given data.
+  if (data && data.length > 0) {
+    sheet.getRangeByIndexes(currentRow, 0, data.length, data[0].length).setValues(data);
+  }
+
+  // If we wrote less data than the batch size, signal the end of the flow.
+  return batchSize > data.length;
+}
+```
+
+### Power Automate flow: Read and write data in a loop
+
+1. Sign into [Power Automate](https://flow.microsoft.com) and create a new **Instant cloud flow**.
+1. Choose **Manually trigger a flow** and select **Create**.
+1. Add a **New step** to track the current row being read and written. Make a new **Initialize variable** action with the following values.
+    * **Name**: currentRow
+    * **Type**: Integer
+    * **Value**: 0
+
+    :::image type="content" source="../../images/write-large-dataset-1.png" alt-text="The completed 'Initialize variable' step for the 'currentRow'.":::
+1. Add a **New step** to set the number of rows to be read in a single batch. Depending on the number of columns, this may need to be smaller to avoid the data transfer limits. Make a new **Initialize variable** action with the following values.
+    * **Name**: batchSize
+    * **Type**: Integer
+    * **Value**: 10000
+
+    :::image type="content" source="../../images/write-large-dataset-2.png" alt-text="The completed 'Initialize variable' step for the 'batchSize'.":::
+1. Add a **Do until** control. The flow will read chunks of the data until it has all been copied. You'll use the value of **-1** to indicate the end of the data has been reached. Give the control the following values.
+    * **Choose a value**: *currentRow* (dynamic content)
+    * **is equal to** (from the dropdown list)
+    * **Choose a value**: -1
+
+    :::image type="content" source="../../images/write-large-dataset-3.png" alt-text="The completed 'Do until' control.":::
+1. The remaining steps are added inside the **Do until** control. Next, call the script to read the data. Add an **Excel Online (Business)** connector with the **Run script** action. Use the following values for the action.
+    * **Location**: OneDrive for Business
+    * **Document Library**: OneDrive
+    * **File**: "SampleData.xlsx" (as selected by the file picker)
+    * **Script**: Read selected rows
+    * **startRow**: *currentRow* (dynamic content)
+    * **batchSize**: *batchSize* (dynamic content)
+
+    :::image type="content" source="../../images/write-large-dataset-4.png" alt-text="The completed 'Run script' action for the script that reads the data.":::
+1. Call the script to write the data. Add a second **Excel Online (Business)** connector with the **Run script** action. Use the following values for the action.
+    * **Location**: OneDrive for Business
+    * **Document Library**: OneDrive
+    * **File**: "TargetWorkbook.xlsx" (as selected by the file picker)
+    * **Script**: Write data at row location
+    * **startRow**: *currentRow* (dynamic content)
+    * **batchSize**: *batchSize* (dynamic content)
+
+    :::image type="content" source="../../images/write-large-dataset-5.png" alt-text="The completed 'Run script' action for the script that writes the data.":::
+1. Update the current row to reflect that a batch of data has been read and written. Add an **Increment variable** action with the following values.
+    * **Name**: currentRow
+    * **Value**: *batchSize* (dynamic content)
+
+    :::image type="content" source="../../images/write-large-dataset-6.png" alt-text="The completed 'Increment variable' step for the 'currentRow'.":::
+1. Add a **Condition** control to check if the scripts have read everything. The "Write data at row location" script returns true when it has written fewer rows than the batch size allows. This means it's at the end of the data set. Create the **Condition** control with the following values.
+    * **Choose a value**: *result* (dynamic content from **Run script**)
+    * **is equal to** (from the dropdown list)
+    * **Choose a value**: *true* (expression)
+
+    :::image type="content" source="../../images/write-large-dataset-7.png" alt-text="The completed 'Condition' control.":::
+1. Under the **If yes** section of the **Condition** control, set the **currentRow** variable to be **-1**. Create a **Set variable** action with the following values.
+    * **Name**: currentRow
+    * **Value**: -1
+
+    :::image type="content" source="../../images/write-large-dataset-8.png" alt-text="The 'If yes' path with the completed 'Set variable' control.":::
+1. Save the flow. Use the **Test** button on the flow editor page or run the flow through your **My flows** tab. Be sure to allow access when prompted.
+1. The "TargetWorkbook.xlsx" file should now have the data from "SampleData.xlsx".

docs/images/write-large-dataset-2.png

@@ -1,7 +1,7 @@
 ---
 title: Platform limits and requirements with Office Scripts
 description: Resource limits and browser support for Office Scripts when used with Excel.
-ms.date: 02/07/2023
+ms.date: 02/24/2023
 ms.localizationpriority: medium
 ---
 
@@ -33,7 +33,7 @@ Excel limits that aren't specific to Office Scripts can be found in the article
 The following limitations with the Power Automate platform are the ones you'll most likely encounter.
 
 - Each user is limited to **1,600 calls** to the Run script action per day. This limit resets at 12:00 AM UTC.
-- There's a **120-second timeout** for [synchronous Power Automate operations](/power-automate/limits-and-config#timeout). For long-running scripts, you must either [optimize your script](../develop/web-client-performance.md) or split your Excel automation into multiple scripts.
+- There's a **120-second timeout** for [synchronous Power Automate operations](/power-automate/limits-and-config#timeout). For long-running scripts, you must either [optimize your script](../develop/web-client-performance.md) or [split your Excel automation into multiple script calls](../resources/samples/write-large-dataset.md#sample-2-write-data-in-batches-from-a-power-automate-flow).
 - The maximum size of parameters passed to the Run script action is **30,000,000 bytes (28.6MB)**.
 
 Additional Power Automate platform usage limitations can be found in the following articles.