officedev / office-scripts-docs

Office Scripts Documentation

Office Scripts documentation

Welcome to the Office Scripts documentation repository. In this repo, you can find the documentation source files for Office Scripts tutorials and how-to guides. For the best experience, we recommend you view this content on Microsoft Learn.

NOTE: You can find the reference documentation source files for the Office Scripts API in the office-scripts-docs-reference repository. These APIs contain all the potential operations for your scripts.

Give us your feedback

The goal of the repo is to provide developer education about Office Scripts. As such, issues should pertain to that educational content. Please submit an issue for the following scenarios:

• Information needed to succeed in developing Office Scripts is missing or incomplete.
• Information is inaccurate or obsolete.
• You find typos, grammatical mistakes, or other problems with the articles.
• Articles are organized in a confusing or unintuitive manner.

If you are seeing product behavior that differs from the documentation, please provide as much of the following information as is possible and relevant:

• The version and build number of the client you are using.
• Steps to reproduce the issue.
• Console output and error messages.

We also encourage you to fork, make the fix, and do a pull request of your proposed changes. For details, see Contribute to this documentation.

If your issue is not related to the Office Scripts documentation, please post it to one of the following channels instead:

• To ask a question about designing Office Scripts or the Office.js API that runs Office Scripts, post your question to Stack Overflow and tag it with the "office-scripts" tag.
• To report an issue with the Office.js API, create the issue in the OfficeDev/office-js repository, which members of the product team monitor for customer-reported issues.

Copyright

Copyright (c) 2019 Microsoft Corporation. All rights reserved.

Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

office-scripts-docs's Issues

Add link to official blog post announcement

In the page, https://review.docs.microsoft.com/en-us/office/dev/scripts/?branch=master it will be useful to link to the official blog post announcement.

Only TypeScript is supported in the Script Editor.

The Docs currently offer a choice of TypeScript or JavaScript however only TypeScript is supported in the Script Editor.

https://review.docs.microsoft.com/en-us/office/dev/scripts/overview/overview?branch=master#scripting-language-typescript-or-javascript

Code gives an error because of Argument Type

[20, 42] Argument of type 'string | number | boolean' is not assignable to parameter of type 'number'.
Type 'string' is not assignable to type 'number'.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: db20932c-4680-4ee6-1299-4995d5151e5f
• Version Independent ID: 3ff9e767-2543-6a73-579e-c0ea53c15a0c
• Content: Read workbook data with Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/tutorials/excel-read-tutorial.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Add section about undoing script runs

From @peronald:

I think we should show a user how to undo a script by going into the version history of the document. If a user runs a script and sees that they cannot undo it, they may have concerns. To alleviate their stress, we should probably include a section on how to 'undo' a script.

Mention req sets?

Reconsider how the API requirement sets are discussed on the overview page:
https://review.docs.microsoft.com/en-us/office/dev/scripts/overview/overview?branch=master#office-javascript-api

Tutorial autofit columns does weird formatting

https://review.docs.microsoft.com/en-us/office/dev/scripts/tutorials/excel-office-scripts-tutorial?branch=master#read-a-cell

1. Copy and past the table
2. copy and pasting the script
3. run the script

observe the strange autofit formatting

Is this dependent on screen size or other settings?

How will users report these errors (Makers?)

Where are Scripts saved/stored?

In the next documentation:
https://docs.microsoft.com/en-us/office/dev/scripts/overview/excel

It explains that the scripts can be saved, where are the scripts stored? is it the same Git Hub options as ScriptLab?, I need to know If I don't necessarily need a Git Hub account before asking my It Admin to enable the Automate Ribbon option

"Overview" needs more pictures

Title—suggest at least one photo (or better yet, gif) per major UI component

https://github.com/OfficeDev/office-scripts-docs/blob/master/docs/overview/overview.md

Define read and write operations?

Any workbook change is recorded as one or more write operations in the script. Scripts can also read data from a workbook.

What are read or write operations?

Tutorials page contains link to internal word doc

Under the prerequisites section "Opt-in to the Excel Scripting preview" this should include a walk through of how the IT admin can enable preview. It may also be worth including "Admin must opt-in to the Office Scripts preview" to match the necessary action.

Request for new article: Restoring Deleted Office Scripts

Could a new article be written on the topic of how to restore deleted scripts (from OneDrive)? This will be a good reference for support when customers accidentally delete or troubleshoot when they don't see a Script they expect in the available scripts.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: ea78ca2e-5171-be4b-1a76-16245c3cf186
• Version Independent ID: 4e25e34f-fa75-fbf5-ada5-12503a859cd1
• Content: Troubleshooting Office Scripts - Office Scripts
• Content Source: docs/testing/troubleshooting.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

request features

"Request features" at https://aka.ms/oscripts

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: f67f2ac9-6bd4-a5fc-20b0-e0b055dbe61c
• Version Independent ID: a0f30a07-4ebf-ac33-6797-43ae7306bede
• Content: Office Scripts documentation
• Content Source: docs/index.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Issue with manually entering file path for .xlsx

Great tutorial! Got it working ok, struggled with adding my file path though - I could only add through using the pop-up file-selection GUI, instead of entering my filepath maunally (i.e. same path for example "/TestFolder/task-reminder.xlsx" but it failed on testing).

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 5d5d64ce-91a7-5caa-89f4-d16acac667bd
• Version Independent ID: 07baec70-00d6-e47b-f73a-f52bb10fd92e
• Content: Office Scripts sample scenario: Automated task reminders - Office Scripts
• Content Source: docs/resources/scenarios/task-reminders.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Automate tab not visible in excel for web

We have officescripts enabled for users in our organization still no user can see automate ribbon in excel for web.

Article URL

https://docs.microsoft.com/en-us/office/dev/scripts/testing/platform-limits#third-party-cookies

Issue

We have office scripts enabled for users in our organization still no user can see automate ribbon in excel for web.

We checked with various browsers with all cookies enabled and in private session as well. All users in organization faces issue.
Is the feature available for yet to deliver. If feature is available then why automate ribbon is not available for our users.

Difficult to Find Automate Tab if hidden in the ribbon.

Could not find the automate tab since Excel hides it behind a drop down arrow.

https://review.docs.microsoft.com/en-us/office/dev/scripts/tutorials/excel-office-scripts-tutorial?branch=master

Open the Automate tab and press Record Actions.

Security of Office Scripts

Could you please offer more details concerning Office Scripts and Security? The statement "no JavaScript auth tokens can be shared with (office?) scripts" is a bit vague.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 67a88dd6-c546-a6a7-9745-50bc60de2a9f
• Version Independent ID: 2274fc03-b644-8aa5-dd51-067ae86c9746
• Content: Differences between Office Scripts and VBA macros - Office Scripts
• Content Source: docs/resources/vba-differences.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Sharing Office Scripts in Excel for the web

see suggested correction in Issue section below

Article URL

https://support.microsoft.com/en-us/office/sharing-office-scripts-in-excel-for-the-web-226eddbc-3a44-4540-acfe-fccda3d1122b

Issue

Please be more precise for what access permissions this is true, "Important: Anyone with access to a workbook can view and run its attached scripts." Perhaps instead should read, "Anyone with Edit access to a workbook..." Users with Read access should be able to view the workbook but not be able to run scripts.

Consistently use `let` instead of `const`

Issue

From @gergzk:

One maybe minor thing that popped to my eye: the examples use a mix of let and const, and thinking about the feedback from MAKER, people might already find these confusing so having two of them could be worse?
The recorder intentionally creates lines of code with 'let' because it's not opinionated that these should be const and if someone wants to play with the code it's one less hurdle, but that's a pretty philosophical and unproven reason. Is there a consistency thing here we should be paying more attention to?

"Overview" "Script environment" section is unhelpful if unfamiliar with TypeScript

Becomes more obvious if you read it from the persona of "I only know Excel, I've never programmed before (or I've used VBA a few times)."

Suggest emphasizing TypeScript less and giving a brief overview of what it is with a link to the TypeScript site.

https://github.com/OfficeDev/office-scripts-docs/blob/master/docs/overview/overview.md

Add (preview) to overview H1

Switch to public Stack Overflow links before public preview

Safari supported..or not?

[Enter feedback here]
In conversation with Petra, my understanding is Safari is not supported due to disallowing 3rd party cookies by default. However Safari's inclusion here doesn't make that point clear, so if it is accurate that Safari is still not supported at present, then this should be stated and explained.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 4085c6ff-856c-4704-8d72-5ef0ca1f64c1
• Version Independent ID: 92eda514-0e20-3add-4b61-62d82d210549
• Content: Platform limits and requirements with Office Scripts - Office Scripts
• Content Source: docs/testing/platform-limits.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Open the Automate tab and press Record Actions should be in two steps

https://review.docs.microsoft.com/en-us/office/dev/scripts/tutorials/excel-office-scripts-tutorial?branch=master

Open the Automate tab and press Record Actions.

1. Open the Automate Tab
2. Press Record Actions

This makes it easier to follow verses missing a step, especially as on a laptop people will be switching focus between tabs from reading the tutorial to playing with excel.

Notes in "Overview" are overwhelming

Notes in overview are a bit overwhelming as a first-time reader; I'm expecting to see a very simple, rapid on-ramp towards (1) knowing "enough" and (2) trying the product out. I recommend significantly condensing or even omitting most of the Note content that is shown currently.

Article URL

https://github.com/OfficeDev/office-scripts-docs/blob/master/docs/overview/overview.md

Image

Hi,

How to insert an image from one sheet to another by script?
or
How to insert an image from the folder to the excel sheet by script?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: c0de752a-5e17-5c20-acd7-67f9726bc767
• Version Independent ID: 4304ad93-6811-7101-4077-7f3366ace997
• Content: Basic scripts for Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/resources/excel-samples.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Steps 7-9 no longer up to date

[We now automatically save a script after a user stops recording. The script details pane contains options to rename a script (hover over script name or look in the ... menu) and update its description]

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 64fba0bb-7700-99a1-4f48-93a320e6d1f1
• Version Independent ID: a765c9d0-1250-372d-b3ac-9e0911e2193e
• Content: Record, edit, and create Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/tutorials/excel-tutorial.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Making a copy of an Office Script

Explain the concept of when and how to use “Make a Copy”.

Article URL

Either create a new, separate article or add to “Learn the basics of Office Scripts”
https://docs.microsoft.com/en-us/office/dev/scripts/tutorials/excel-tutorial

Issue

If you want to create a "template" script and later create independent copies of that template script, you must “Make a Copy” of the script. This is important to understand in the use scenario where you want to make a workbook “template” with multiple copies and customize each copy’s script.

Clarify language

https://review.docs.microsoft.com/en-us/office/dev/scripts/tutorials/excel-office-scripts-tutorial?branch=master

I think we should specify that admins needs to do their part to opt-in. Current language sounds like user should do it.

...
Prerequisites
Before starting this tutorial, you'll need access to Office Scripts, which requires the following:

Excel on the web.
Opt-in to the Office Scripts preview (admin-enabled). This adds the Automate tab to the ribbon.

Utilize Office Scripts specific API reference repo (not office-js-docs-reference)

Issue

Once the office-scripts-docs-reference repo is live, we'll need to adjust all the reference API links. We'll also need to setup a fusion TOC between the two repos.

How to transfer ownership for Office Scripts

A common scenario is how Office Script ownership transfer should be handled when the Office script creator is no longer with the organization or for any reason an ownership transfer of the Office Script is desired.

Article URL

Issue

Please describe in detail how ownership transfer can be performed by Office Script owners and tenant administrators. Include in the description what permissions are required, and whether it is possible to administratively transfer ownership from one user account to another. And is Modern M365 group ownership supported for Office Scripts? (If yes, please describe any transfer process relating to Group owned Scripts.)

Also describe default retention policy for Office Scripts after a user has left the organization and is deactivated in Azure Active Directory. Reference: https://docs.microsoft.com/en-us/onedrive/retention-and-deletion

Rework opening lines of the index

Improve the sync/load image

Article URL

Scripting Fundamentals

Issue

Rework the sync/load image to be more on-brand.

Remove TableStyle from tutorial

The TableStyle isn't consistent across platforms.

Columns references

I can't find a solution for my macro:
function main(workbook: ExcelScript.Workbook) { let foglioVittorio = workbook.getWorksheet("Vittorio Zigiotto") let tabella = foglioVittorio.getTable("VittorioZigiotto") // Auto fill range tabella.addColumn() tabella.addColumn() tabella.addColumn() tabella.addColumn() tabella.addColumn() tabella.getRange(SOMETHING) .autoFill(SOMETHING, ExcelScript.AutoFillType.fillDefault);

I need to compile "SOMETHING" with the reference to the 5 columns before the 5 columns I added and to autofill the last 5 from that. Without table references it was:
function main(workbook: ExcelScript.Workbook) { let selectedSheet = workbook.getActiveWorksheet(); // Auto fill range selectedSheet.getRange("IC1:IG301") .autoFill("IC1:IL301", ExcelScript.AutoFillType.fillDefault); }

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: c0de752a-5e17-5c20-acd7-67f9726bc767
• Version Independent ID: 4304ad93-6811-7101-4077-7f3366ace997
• Content: Sample scripts for Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/resources/excel-samples.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Explanation for Ranges

In the section for Ranges (https://docs.microsoft.com/en-us/office/dev/scripts/develop/scripting-fundamentals#ranges)
It is explained that A1 notation refers to row A and column 1.
Shouldn't it be the contrary? The letter refers to column header and the number refers to row header.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 91eab22e-1a2a-a9e7-2331-f87462d64fcc
• Version Independent ID: bf0955e2-2a06-ea7d-3d78-c8c52294d23a
• Content: Scripting fundamentals for Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/develop/scripting-fundamentals.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Enabling the service does not enable the service

Article URL

Tutorial
Office Scripts settings in M365

Issue

The first article indicates the service is enabled per user, but the steps to enable Office Scripts in the 2nd link are tenant-wide. Also, enabling the service has no effect in the Excel Web UI, hoping for either an updated timeline for availability.

Code Editor and Record Actions

We finally enabled and got the automate ribbon in excel for web enabled however both Record Actions and Code Editor sub windows are not loading/are blank. Is the some additional setting than we need to install/enable?

Additional info: The help sub window does populate correctly, so not sure.

Missing The?

Original:

When the function is executed, Excel application invokes this main function by providing the workbook as its first parameter.

Proposed:

When the function is executed, the Excel application invokes this main function and provides the workbook as its first parameter.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 91eab22e-1a2a-a9e7-2331-f87462d64fcc
• Version Independent ID: bf0955e2-2a06-ea7d-3d78-c8c52294d23a
• Content: Scripting fundamentals for Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/develop/scripting-fundamentals.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Make Description field a separate optional step?

The Description field can be used to provide context as to what the script does. You can leave the Description blank for the tutorial.

(Optional) Fill in the Description field so you can remember what the script does later.

Getting Data from Other Workbooks

I am not finding any documentation on how to get data from other Excel workbooks. I know this is possible with Google App Script, but it does not look I am finding anything about this with Office Script

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 91eab22e-1a2a-a9e7-2331-f87462d64fcc
• Version Independent ID: bf0955e2-2a06-ea7d-3d78-c8c52294d23a
• Content: Scripting fundamentals for Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/develop/scripting-fundamentals.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

[LOC]Back-Translation "パワー自動化"→"Power Automate" (ja-jp)

ja-jp:"https://docs.microsoft.com/ja-jp/office/dev/scripts/develop/power-automate-integration"

en-us:"https://docs.microsoft.com/en-us/office/dev/scripts/develop/power-automate-integration"

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 0230f03f-497b-4a75-39f3-e56ee35994f0
• Version Independent ID: d10d4fe1-8786-c767-a038-075bd9c9d04a
• Content: Run Office Scripts with Power Automate - Office Scripts
• Content Source: docs/develop/power-automate-integration.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Use of getCount() => ??

Hello,

I failed to get the number of tables using getCount().
The workaround to get the number of items in the tableCollection is to use myTables.items.length

---

vAllSheetTables.load('items/length');
await context.sync();

console.log(vThisTable.name);
console.log(vAllSheetTables.items.length);

---

The only property available for the getCount() method is 'value' and I can't load it.
What's the syntax to use getCount() in order to read the number of items in the collection?

Thanks
Regards

David

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: ca3e75cf-4c8d-1b69-2d35-e0da82e1097e
• Version Independent ID: 0033598d-2083-cf91-3af1-a69ca85fe94b
• Content: Excel.TableCollection class - Office Scripts
• Content Source: docs/docs-ref-autogen/excel/excel/excel.tablecollection.yml
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Scripting Fundamentals lead-in too wordy

Article URL

https://review.docs.microsoft.com/en-us/office/dev/scripts/develop/scripting-fundamentals?branch=master

Issue

From Shreedhar:
"This article describes the areas of Office Scripts in Excel on the web that require you to have a better understanding of how the script code works with Excel."
Too wordy and I don’t understand what we are conveying here.

[LOC]Fixed inappropriate japanese "Power Automate Office"→"PowerAutomate を使用して Office" (ja-jp)

[LOC]Fixed inappropriate japanese "Power Automate Office スクリプトを実行する"→"PowerAutomate を使用して Office スクリプトを実行する" (ja-jp)

related:#257
ja-jp:"https://docs.microsoft.com/ja-jp/office/dev/scripts/develop/power-automate-integration"

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 0230f03f-497b-4a75-39f3-e56ee35994f0
• Version Independent ID: d10d4fe1-8786-c767-a038-075bd9c9d04a
• Content: Run Office Scripts with Power Automate - Office Scripts
• Content Source: docs/develop/power-automate-integration.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

Office Scripts in Excel on the web

Recommended add to existing article: Scripts are stored in the OneDrive /Documents/Office Scripts location of the Script owner. They are saved as .osts extension.

Article URL

https://docs.microsoft.com/en-us/office/dev/scripts/overview/excel

Issue

Notifying Office Script creators of the default location of Office script files will provide better visibility in locating and/or identifying the Office Script files in their OneDrive. There may also be administrative or security related reasons to be able to identify what .osts files are and where they are located by default.

Would be great if this page had a link to Sudhi's code samples on Github as well as other samples written by the community

[Enter feedback here]

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: c0de752a-5e17-5c20-acd7-67f9726bc767
• Version Independent ID: 4304ad93-6811-7101-4077-7f3366ace997
• Content: Sample scripts for Office Scripts in Excel on the web - Office Scripts
• Content Source: docs/resources/excel-samples.md
• Product: excel
• Technology: scripts
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

"Overview" missing top-level "what is this thing" section

When viewing the "Overview" page, I'm expecting to see a broad "what is this thing" section, followed by in-depth sections on what I need to know. Currently, I think the article does a good job with the in-depth sections, but omits a broader first section that is more detailed than the index, but less than the current sections.

E.g.

Overview

What can Office Scripts be used for?

Examples, gifs, motivate why this is awesome

Why is this useful?

Maybe case examples? Defer to Power Automate marketing approaches/docs framing

Who is Office Scripts meant for?

Brief overview of baseline skill sets required for certain things

How does Office Scripts work?

Outline the components and their general functions—current sections would probably be subsections here.

Article URL

https://github.com/OfficeDev/office-scripts-docs/blob/master/docs/overview/overview.md

Broken Link

Article URL

Issue

Intimidating to have to learn a lot about programming before proceeding.

It might be reasonable to word the following to indicate that things can be learned as they go along so we don't scare people off.

https://review.docs.microsoft.com/en-us/office/dev/scripts/overview/overview?branch=master#scripting-language-typescript-or-javascript

"Excel for the web" or "Excel on the web"?

Excel product name is inconsistent with other documentation; see:

• https://docs.microsoft.com/en-us/office365/servicedescriptions/office-online-service-description/excel-online
• https://products.office.com/en-us/free-office-online-for-the-web
• https://support.office.com/en-us/article/create-a-workbook-in-excel-for-the-web-63b50461-38c4-4c93-a17e-36998be0e3d0

(Google search suggests correct name is "Excel for the web")