Merge pull request #669 from OfficeDev/main

AlexJerabek · web-flow · commit 0e03fa7a4d57 · 2023-10-25T08:35:00.000-07:00
[admin] Publish
diff --git a/docs/develop/macros-power-automate.md b/docs/develop/macros-power-automate.md
@@ -1,23 +1,23 @@
 ---
 title: Use macro-enabled files in Power Automate flows
 description: Learn how to use macro-enabled files, or .xlsm files, in Power Automate flows.
-ms.date: 08/09/2023
+ms.date: 10/19/2023
 ms.localizationpriority: medium
 ---
 
 # How to use macro-enabled files in Power Automate flows
 
-You can integrate your .xlsm files with a Power Automate flow. This lets you start to convert your existing automation solutions to web-based formats. Please note that the macros contained in the .xlsm files cannot be run through Power Automate. Only Office Scripts are enabled there.
+[Power Automate](https://make.powerautomate.com/) flows support .xlsm files in the [Excel Online (Business) connector](https://make.powerautomate.com/connectors/shared_excelonlinebusiness/excel-online-business/).
 
-The [Excel Online (Business) connector](https://make.powerautomate.com/connectors/shared_excelonlinebusiness/excel-online-business/) in [Power Automate](https://make.powerautomate.com/) is typically limited to files in the Microsoft Excel Open XML Spreadsheet (.xlsx) format. Its file browser only lets you select .xlsx files. However, macro-enabled files are compatible with the connector's **Run script** action if the file metadata is used.
+> [!IMPORTANT]
+> The macros contained in the .xlsm files cannot be run through Power Automate. Only Office Scripts are enabled there.
 
-In your flow, use the **Get File Metadata** action from either the [OneDrive for Business](https://make.powerautomate.com/connectors/shared_onedriveforbusiness/onedrive-for-business/) or [SharePoint](https://make.powerautomate.com/connectors/shared_sharepointonline/sharepoint/) connectors. The **Run script** action accepts this metadata as a valid file. Use the *ID* dynamic content returned from the **Get file metadata** action as the "File" argument when running the script. The following screenshot shows a flow providing the metadata for a file called "Test Macro File.xlsm" to a **Run script** action.
-
-:::image type="content" source="../images/xlsm-in-power-automate.png" alt-text="A flow with a Get file metadata action passing the metadata of a macro file to a Run script action.":::
+The **Run script** action lets you select .xlsm files. Other connector actions require you use the file ID. Get this ID with the **Get File Metadata** action from either the [OneDrive for Business](https://make.powerautomate.com/connectors/shared_onedriveforbusiness/onedrive-for-business/) or [SharePoint](https://make.powerautomate.com/connectors/shared_sharepointonline/sharepoint/) connectors. Use the *ID* dynamic content returned from the **Get file metadata** action as the "File" argument for Excel connector actions.
 
 > [!WARNING]
 > Some .xlsm files, especially those with ActiveX or Form controls, may not work in the Excel online connector. Be sure to test before deploying your solution.
 
-## Other resources
+## See also
 
-[Watch Sudhi Ramamurthy's YouTube video on how use an .xlsm file in a Run Script action](https://youtu.be/o-H9BbywJQQ).
+- [Excel Online (Business) connector reference](/connectors/excelonlinebusiness/)
+- [Run Office Scripts with Power Automate](power-automate-integration.md)
diff --git a/docs/develop/pivottables.md b/docs/develop/pivottables.md
@@ -1,7 +1,7 @@
 ---
 title: Work with PivotTables in Office Scripts
 description: Learn about the object model for PivotTables in the Office Scripts JavaScript API.
-ms.date: 09/08/2023
+ms.date: 10/19/2023
 ms.localizationpriority: medium
 ---
 
@@ -26,7 +26,10 @@ The [PivotTable](/javascript/api/office-scripts/excelscript/excelscript.pivottab
 - The [PivotLayout](/javascript/api/office-scripts/excelscript/excelscript.pivotlayout) defines how the [PivotFields](/javascript/api/office-scripts/excelscript/excelscript.pivotfield) and [PivotItems](/javascript/api/office-scripts/excelscript/excelscript.pivotitem) are displayed.
 - [PivotFilters](/javascript/api/office-scripts/excelscript/excelscript.pivotfilters) filter data from the [PivotTable](/javascript/api/office-scripts/excelscript/excelscript.pivottable) using different criteria.
 
-Look at how these relationships work in practice. The following data describes fruit sales from various farms. It's the base for all the examples in this article. Use [pivottable-sample.xlsx](pivottable-sample.xlsx) to follow along.
+To look at how these relationships work in practice, start by downloading the sample workbook. That data describes fruit sales from various farms. It's the base for all the examples in this article. Run the sample scripts throughout the article to create and explore PivotTables.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](pivottable-sample.xlsx)
 
 :::image type="content" source="../images/pivottable-raw-data.png" alt-text="A collection of fruit sales of different types from different farms.":::
 
diff --git a/docs/develop/script-buttons.md b/docs/develop/script-buttons.md
@@ -1,12 +1,12 @@
 ---
-title: Run Office Scripts in Excel with buttons
+title: Run Office Scripts in Excel from buttons
 description: Add buttons to workbooks that control Office Scripts in Excel.
 ms.topic: overview
-ms.date: 03/10/2023
+ms.date: 10/24/2023
 ms.localizationpriority: medium
 ---
 
-# Run Office Scripts in Excel with buttons
+# Run Office Scripts in Excel from buttons
 
 Help your colleagues find and run your scripts by adding script buttons to a workbook.
 
diff --git a/docs/develop/scripting-fundamentals.md b/docs/develop/scripting-fundamentals.md
@@ -2,14 +2,16 @@
 title: Fundamentals for Office Scripts in Excel
 description: Object model information and other basics to learn before writing Office Scripts.
 ms.topic: get-started
-ms.date: 10/01/2022
+ms.date: 10/24/2023
 ms.localizationpriority: high
 ---
 
 # Fundamentals for Office Scripts in Excel
 
 This article will introduce you to the technical aspects of Office Scripts. You'll learn the critical parts of the TypeScript-based script code and how the Excel objects and APIs work together.
 
+If you would prefer to get started with an interactive experience, try the tutorial [Record, edit, and create Office Scripts in Excel](../tutorials/excel-tutorial.md) or visit our [samples](../resources/samples/samples-overview.md).
+
 ## TypeScript: The language of Office Scripts
 
 Office Scripts are written in [TypeScript](https://www.typescriptlang.org/docs/home.html), which is a superset of [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript). If you're familiar with JavaScript, your knowledge will carry over because much of the code is the same in both languages. We recommend you have some beginner-level programming knowledge before starting your Office Scripts coding journey. The following resources can help you understand the coding side of Office Scripts.
@@ -41,6 +43,8 @@ To write a script, you need to understand how the Office Scripts APIs fit togeth
 - A **Worksheet** contains collections of those data objects that are present in the individual sheet.
 - **Workbooks** contain collections of some of those data objects (such as **Tables**) for the entire **Workbook**.
 
+The complete list of Office Scripts API objects is detailed in the [ExcelScript package](/javascript/api/office-scripts/excelscript).
+
 ## Workbook
 
 Every script is provided a `workbook` object of type `Workbook` by the `main` function. This represents the top level object through which your script interacts with the Excel workbook.
diff --git a/docs/images/xlsm-in-power-automate.png b/docs/images/xlsm-in-power-automate.png
diff --git a/docs/includes/power-automate-tutorial-prerequisites.md b/docs/includes/power-automate-tutorial-prerequisites.md
@@ -1,5 +1 @@
-Before starting this tutorial, you'll need access to the following:
-
-- [Power Automate](/power-automate/organization-q-and-a).
-- Excel for Windows, for Mac, or on the web.
-- [A Microsoft 365 commercial or EDU plan that includes Office Scripts](/microsoft-365/admin/manage/manage-office-scripts-settings).
+You'll need access to Office Scripts and Power Automate for this tutorial. Please review the [Platform support](/office/dev/scripts/testing/platform-limits#platform-support) if the Automate tab doesn't appear. The [Power Automate sign-up FAQ](/power-automate/organization-q-and-a) has information on getting started with Power Automate.
diff --git a/docs/includes/tutorial-prerequisites.md b/docs/includes/tutorial-prerequisites.md
@@ -1,4 +1 @@
-Before starting this tutorial, you'll need access to Office Scripts, which requires the following:
-
-- Excel for Windows, for Mac, or on the web.
-- [A Microsoft 365 commercial or EDU plan that includes Office Scripts](/microsoft-365/admin/manage/manage-office-scripts-settings).
+You'll need access to Office Scripts for this tutorial. Please review the [Platform support](/office/dev/scripts/testing/platform-limits#platform-support) if the Automate tab doesn't appear.
diff --git a/docs/resources/samples/add-excel-comments.md b/docs/resources/samples/add-excel-comments.md
@@ -1,7 +1,7 @@
 ---
 title: Add comments in Excel
 description: Learn how to use Office Scripts to add comments in a worksheet.
-ms.date: 08/14/2023
+ms.date: 10/20/2023
 ms.localizationpriority: medium
 ---
 
@@ -11,22 +11,25 @@ This sample shows how to add comments to a cell including [@mentioning](https://
 
 ## Example scenario
 
-* The team lead maintains the shift schedule. The team lead assigns an employee ID to the shift record.
-* The team lead wishes to notify the employee. By adding a comment that @mentions the employee, the employee is emailed with a custom message from the worksheet.
-* Subsequently, the employee can view the workbook and respond to the comment at their convenience.
+The team lead maintains the shift schedule. They assign an employee ID to the shift record. If the team lead wishes to notify the employee, they add a comment that @mentions the employee. The employee is emailed with a custom message from the worksheet. Subsequently, the employee can view the workbook and respond to the comment at their convenience.
 
 ## Solution
 
 1. The script extracts employee information from the employee worksheet.
 1. The script then adds a comment (including the relevant employee email) to the appropriate cell in the shift record.
 1. Existing comments in the cell are removed before adding the new comment.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download [add-excel-comments.xlsx](add-excel-comments.xlsx) for a ready-to-use workbook. Add the following script to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](add-excel-comments.xlsx)
 
 ## Sample code: Add comments
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 function main(workbook: ExcelScript.Workbook) {
   // Get the list of employees.
diff --git a/docs/resources/samples/add-image-to-workbook.md b/docs/resources/samples/add-image-to-workbook.md
@@ -17,12 +17,17 @@ The first sample copies an image from one worksheet to another. This could be us
 
 The second sample copies an image from a URL. This could be used to copy photos that a colleague stored in a shared folder to a related workbook. Please note that this sample can't be adapted to work with a local image file, as that isn't supported by Office Scripts.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download [add-images.xlsx](add-images.xlsx) for a ready-to-use workbook. Add the following scripts and try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](add-images.xlsx)
 
 ## Sample code: Copy an image across worksheets
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 /**
  * This script transfers an image from one worksheet to another.
diff --git a/docs/resources/samples/community-seasons-greetings.md b/docs/resources/samples/community-seasons-greetings.md
@@ -13,9 +13,16 @@ Enjoy!
 
 [Watch the Seasons greetings script in action on the "Les's IT Blog" YouTube channel](https://youtu.be/HBiGEkzmkgo).
 
-## Script
+## Setup: Sample Excel file
 
-Download [happy-tree.xlsx](happy-tree.xlsx) for a ready-to-use workbook. Add the following script to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](happy-tree.xlsx)
+
+## Sample code: Happy tree
+
+Add the following script to the sample workbook and try the sample yourself!
 
 ```TypeScript
 /* Original version by Leslie Black.  */
diff --git a/docs/resources/samples/copy-tables-combine.md b/docs/resources/samples/copy-tables-combine.md
@@ -14,12 +14,17 @@ There are two variations of this script:
 1. The [first script](#sample-code-combine-data-from-multiple-excel-tables-into-a-single-table) combines all tables in the Excel file.
 1. The [second script](#sample-code-combine-data-from-multiple-excel-tables-in-select-worksheets-into-a-single-table) selectively gets tables within a set of worksheets.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download [tables-copy.xlsx](tables-copy.xlsx) for a ready-to-use workbook. Add the following scripts to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](tables-copy.xlsx)
 
 ## Sample code: Combine data from multiple Excel tables into a single table
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 function main(workbook: ExcelScript.Workbook) {
   // Delete the "Combined" worksheet, if it's present.
diff --git a/docs/resources/samples/email-images-chart-table.md b/docs/resources/samples/email-images-chart-table.md
@@ -35,12 +35,17 @@ This solution has two parts:
 1. [An Office Script to calculate and extract Excel chart and table](#sample-code-calculate-and-extract-excel-chart-and-table)
 1. A Power Automate flow to invoke the script and email the results. For an example on how to do this, see [Create an automated workflow with Power Automate](../../tutorials/excel-power-automate-returns.md#create-an-automated-workflow-with-power-automate).
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download [email-chart-table.xlsx](email-chart-table.xlsx) for a ready-to-use workbook. Add the following script to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](email-chart-table.xlsx)
 
 ## Sample code: Calculate and extract Excel chart and table
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 function main(workbook: ExcelScript.Workbook): ReportImages {
   // Recalculate the workbook to ensure all tables and charts are updated.
diff --git a/docs/resources/samples/get-table-data.md b/docs/resources/samples/get-table-data.md
@@ -9,9 +9,12 @@ ms.localizationpriority: medium
 
 Excel table data can be represented as an array of objects in the form of [JSON](https://www.w3schools.com/whatis/whatis_json.asp). Each object represents a row in the table. This helps extract the data from Excel in a consistent format that is visible to the user. The data can then be given to other systems through Power Automate flows.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download the file [table-data-with-hyperlinks.xlsx](table-data-with-hyperlinks.xlsx) for a ready-to-use workbook.
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](table-data-with-hyperlinks.xlsx)
 
 :::image type="content" source="../../images/table-input.png" alt-text="A worksheet showing input table data.":::
 
@@ -21,7 +24,7 @@ A variation of this sample also includes the hyperlinks in one of the table colu
 
 ## Sample code: Return table data as JSON
 
-Add the following script to try the sample yourself!
+Add the following script to the sample workbook and try the sample yourself!
 
 > [!NOTE]
 > You can change the `interface TableData` structure to match your table columns. Note that for column names with spaces, be sure to place your key in quotation marks, such as with `"Event ID"` in the sample. For more information about working with JSON, read [Use JSON to pass data to and from Office Scripts](../../develop/use-json.md).
diff --git a/docs/resources/samples/move-rows-across-tables.md b/docs/resources/samples/move-rows-across-tables.md
@@ -13,12 +13,17 @@ This script does the following:
 * Moves all selected rows into the target table in another worksheet.
 * Reapplies the relevant filters to the source table.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download the file [input-table-filters.xlsx](input-table-filters.xlsx) for a ready-to-use workbook. Add the following script to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](input-table-filters.xlsx)
 
 ## Sample code: Move rows using range values
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 function main(workbook: ExcelScript.Workbook) {
 
diff --git a/docs/resources/samples/remove-hyperlinks-from-cells.md b/docs/resources/samples/remove-hyperlinks-from-cells.md
@@ -12,12 +12,17 @@ ms.localizationpriority: medium
 > [!NOTE]
 > This only works if the cell count is < 10k.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download the file [remove-hyperlinks.xlsx](remove-hyperlinks.xlsx) for a ready-to-use workbook. Add the following script to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](remove-hyperlinks.xlsx)
 
 ## Sample code: Remove hyperlinks
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 function main(workbook: ExcelScript.Workbook, sheetName: string = 'Sheet1') {
   // Get the active worksheet. 
diff --git a/docs/resources/samples/report-day-to-day-changes.md b/docs/resources/samples/report-day-to-day-changes.md
@@ -9,12 +9,17 @@ ms.localizationpriority: medium
 
 Power Automate and Office Scripts combine to handle repetitive tasks for you. In this sample, you're tasked with recording a single numerical reading in a workbook every day and reporting the change since yesterday. You'll build a flow to get that reading, log it in the workbook, and report the change through an email.
 
-## Sample Excel file
+## Setup: Sample Excel file
 
-Download [daily-readings.xlsx](daily-readings.xlsx) for a ready-to-use workbook. Add the following script to try the sample yourself!
+This workbook contains the data, objects, and formatting expected by the script.
+
+> [!div class="nextstepaction"]
+> [Download the sample workbook](daily-readings.xlsx)
 
 ## Sample code: Record and report daily readings
 
+Add the following script to the sample workbook and try the sample yourself!
+
 ```TypeScript
 function main(workbook: ExcelScript.Workbook, newData: string): string {
   // Get the table by its name.
diff --git a/docs/resources/samples/samples-overview.md b/docs/resources/samples/samples-overview.md
@@ -62,7 +62,7 @@ Office Scripts can automate parts of your daily routine. These day-to-day tasks
 | [Fetch and graph water-level data from NOAA](../scenarios/noaa-data-fetch.md) | This scenario uses an Office Script to pull data from an external source (the [NOAA Tides and Currents database](https://tidesandcurrents.noaa.gov/)) and graph the resulting information. It highlights the skills of using `fetch` to get data and using charts. |
 | [Grade calculator](../scenarios/grade-calculator.md) | This scenario features a script that validates an instructor's record for their class's grades. It showcases the skills of error checking, cell formatting, and regular expressions. |
 | [Schedule interviews in Teams](../scenarios/schedule-interviews-in-teams.md) | This scenario shows how to use an Excel spreadsheet to manage interview meeting times and make a flow to schedules meetings in Teams. |
-| [Task reminders](../scenarios/task-reminders.md) | This scenario uses an Office Script in a Power Automate flow to send reminders to coworkers to update a project's status. It highlights the skills of Power Automate integration and data transfer to and from scripts. |
+| [Task reminders as Teams cards](../scenarios/task-reminders.md) | This scenario uses an Office Script in a Power Automate flow to send reminders to coworkers to update a project's status. It highlights the skills of Power Automate integration and data transfer to and from scripts. |
 
 ## Community contributions and fun samples
 
diff --git a/docs/resources/samples/table-of-contents.md b/docs/resources/samples/table-of-contents.md
diff --git a/docs/resources/scenarios/analyze-web-downloads.md b/docs/resources/scenarios/analyze-web-downloads.md
diff --git a/docs/resources/scenarios/grade-calculator.md b/docs/resources/scenarios/grade-calculator.md
diff --git a/docs/resources/scenarios/punch-clock.md b/docs/resources/scenarios/punch-clock.md
diff --git a/docs/resources/scenarios/schedule-interviews-in-teams.md b/docs/resources/scenarios/schedule-interviews-in-teams.md
diff --git a/docs/resources/scenarios/task-reminders.md b/docs/resources/scenarios/task-reminders.md
diff --git a/docs/toc.yml b/docs/toc.yml
