[all hosts] (Event-based activation) Consolidate Outlook and WXP autorun information #5269
+503
−471
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Learn Build status updates of commit c1fa8d5:
|
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ice-js-docs-pr into AlexJ-AutorunCombo
|
Learn Build status updates of commit 7364bd1:
|
|
Learn Build status updates of commit 5e77870:
|
|
Learn Build status updates of commit 51f560e: ✅ Validation status: passed
This comment lists only the first 25 files in the pull request. |
| @@ -7,7 +7,7 @@ ms.localizationpriority: medium | |||
|
|
|||
| # AppSource listing options for your event-based Outlook add-in | |||
There was a problem hiding this comment.
Does this content also apply to event-based activation in WXP? If so, should we update the supported platforms in the article?
| @@ -8,7 +8,7 @@ ms.localizationpriority: medium | |||
|
|
|||
| # Debug your event-based or spam-reporting Outlook add-in | |||
|
|
|||
| This article discusses the key debugging stages to enable and set breakpoints in your code as you implement [event-based activation](autolaunch.md) or [integrated spam reporting](spam-reporting.md) in your add-in. Before you proceed, we recommend reviewing the [troubleshooting guide](troubleshoot-event-based-and-spam-reporting-add-ins.md) for additional steps on how to resolve development errors. | |||
| This article discusses the key debugging stages to enable and set breakpoints in your code as you implement [event-based activation](../develop/event-based-activation.md) or [integrated spam reporting](spam-reporting.md) in your add-in. Before you proceed, we recommend reviewing the [troubleshooting guide](../testing/troubleshoot-event-based-and-spam-reporting-add-ins.md) for additional steps on how to resolve development errors. | |||
|
|
|||
| To begin debugging, select the tab for your applicable client. | |||
|
|
|||
There was a problem hiding this comment.
For Line 17, change "Outlook on the web" to "Office on the web".
Comment on lines
47
to
49
| | Event canonical name</br>and add-in only manifest name | Description | Supported clients and channels | | ||
| | ----- | ----- | ----- | | ||
| | `OnDocumentOpened` | Occurs when a user opens a document or creates a new document, spreadsheet, or presentation. | <ul><li>Windows (build >= 16.0.18324.20032)</li><li>Office on the web</li><li>Office on Mac will be available later </li></ul>| |
There was a problem hiding this comment.
Consider adding the "Unified manifest for Microsoft 365 name" column (even if it isn't supported yet) for consistency.
| 1. Manually sideload your add-in in Word on the web by following the guidance at [Sideload Office Add-ins to Office on the web](../testing/sideload-office-add-ins-for-testing.md#manually-sideload-an-add-in-to-office-on-the-web). Use the **manifest.xml** in the root of the project. | ||
| 1. Try opening both new and existing Word documents in Word on the web. Headers should automatically be added when they open. | ||
|
|
||
| ## Next steps |
There was a problem hiding this comment.
Are we adding more content here?
There was a problem hiding this comment.
I'll replace this with a See Also.
Co-authored-by: Sam Ramon <15154970+samantharamon@users.noreply.github.com>
|
Learn Build status updates of commit d0743cc: ✅ Validation status: passed
This comment lists only the first 25 files in the pull request. |
|
Learn Build status updates of commit aae7d13:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/develop/addressing-same-origin-policy-limitations.md | View | Details | |
| docs/develop/event-based-activation.md | View | Details | |
| docs/develop/use-sso-in-event-based-activation.md | View | Details | |
| docs/outlook/authenticate-a-user-with-an-sso-token.md | View | Details | |
| docs/outlook/onmessagesend-onappointmentsend-events.md | View | Details | |
| docs/outlook/spam-reporting.md | View | Details | |
| docs/testing/debug-autolaunch.md | View | Details | |
| docs/toc.yml | View | Details | |
| docs/outlook/debug-autolaunch.md | 💡Suggestion | n/a (file deleted or renamed) | Details |
| docs/outlook/use-sso-in-event-based-activation.md | 💡Suggestion | n/a (file deleted or renamed) | Details |
| .openpublishing.redirection.json | ✅Succeeded | View | |
| docs/concepts/browsers-used-by-office-web-add-ins.md | ✅Succeeded | View | |
| docs/concepts/duplicate-legacy-metaos-add-ins.md | ✅Succeeded | View | |
| docs/includes/deploy-updates-that-require-admin-consent.md | ✅Succeeded | View | |
| docs/outlook/append-on-send.md | ✅Succeeded | View | |
| docs/outlook/autolaunch-store-options.md | ✅Succeeded | View | |
| docs/outlook/autolaunch.md | ✅Succeeded | n/a (file deleted or renamed) | |
| docs/outlook/debug-ui-less.md | ✅Succeeded | View | |
| docs/outlook/index.yml | ✅Succeeded | View | |
| docs/outlook/item-multi-select.md | ✅Succeeded | View | |
| docs/outlook/mobile-event-based.md | ✅Succeeded | View | |
| docs/outlook/notifications.md | ✅Succeeded | View | |
| docs/outlook/on-new-compose-events-walkthrough.md | ✅Succeeded | View | |
| docs/outlook/one-outlook.md | ✅Succeeded | View | |
| docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md | ✅Succeeded | View |
This comment lists only the first 25 files in the pull request.
docs/develop/addressing-same-origin-policy-limitations.md
- Line 45, Column 142: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'.
docs/develop/event-based-activation.md
- Line 141, Column 296: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'. - Line 154, Column 149: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'. - Line 168, Column 174: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'.
docs/develop/use-sso-in-event-based-activation.md
- Line 13, Column 477: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'. - Line 42, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'authenticate-a-user-with-an-sso-token.md'. - Line 44, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'.
docs/outlook/authenticate-a-user-with-an-sso-token.md
- Line 57, Column 145: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'. - Line 65, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'.
docs/outlook/onmessagesend-onappointmentsend-events.md
- Line 419, Column 249: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#deploy-to-users' in 'develop/event-based-activation.md'.
docs/outlook/spam-reporting.md
- Line 359, Column 230: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'.
docs/testing/debug-autolaunch.md
- Line 11, Column 175: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'. - Line 27, Column 62: [Warning: file-not-found - See documentation]
Invalid file link: 'one-outlook.md'. - Line 31, Column 157: [Warning: file-not-found - See documentation]
Invalid file link: 'on-new-compose-events-walkthrough.md'. - Line 186, Column 23: [Warning: file-not-found - See documentation]
Invalid file link: 'sideload-outlook-add-ins-for-testing.md'. - Line 195, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'.
docs/toc.yml
- Line 900, Column 15: [Warning: file-not-found - See documentation]
Invalid file link: 'outlook/use-sso-in-event-based-activation.md'.
docs/outlook/debug-autolaunch.md
- [Suggestion: file-not-redirected - See documentation]
File docs/outlook/debug-autolaunch.md with URL /office/dev/add-ins/outlook/debug-autolaunch was deleted without redirection. To avoid broken links, add a redirection.
docs/outlook/use-sso-in-event-based-activation.md
- [Suggestion: file-not-redirected - See documentation]
File docs/outlook/use-sso-in-event-based-activation.md with URL /office/dev/add-ins/outlook/use-sso-in-event-based-activation was deleted without redirection. To avoid broken links, add a redirection.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
There was a problem hiding this comment.
Pull Request Overview
This PR consolidates event-based activation guidance by merging Outlook and Office host (Word, Excel, PowerPoint) autorun articles into a single central “Activate add-ins with events” article, and updates all related links and TOC entries.
- Adds a new Word walkthrough: Add headers when a document opens
- Renames and refactors the Excel/PowerPoint/Word activation guide to Activate add-ins with events
- Updates TOC/navigation and all troubleshooting/testing docs to point at the consolidated article
Reviewed Changes
Copilot reviewed 31 out of 31 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/word/add-headers-on-document-open.md | New Word event-based activation walkthrough |
| docs/toc.yml | Updated table of contents: added walkthrough and fixed links |
| docs/develop/event-based-activation.md | Renamed/refactored central event-based activation concept |
Comments suppressed due to low confidence (1)
docs/toc.yml:104
- There's a typo in the navigation label:
requirmentshould berequirement.
href: develop/specify-office-hosts-and-api-requirements.md
| 1. Try opening both new and existing Word documents in Word on the web. Headers should automatically be added when they open. | ||
| - Event-based add-ins require an internet connection to be able to launch when a specific event occurs. Add-in event handlers are expected to be short-running, lightweight, and as noninvasive as possible. After activation, your add-in will time out within approximately 300 seconds, the maximum length of time allowed for running event-based add-ins. To signal that your add-in has completed processing a launch event, your associated event handler must call the [event.completed](/javascript/api/outlook/office.mailboxevent#outlook-office-mailboxevent-completed-member(1)) method. (Note that code included after the `event.completed` statement isn't guaranteed to run.) Each time an event that your add-in handles is triggered, the add-in is reactivated and runs the associated event handler, and the timeout window is reset. The add-in ends after it times out, or the user closes the compose window or sends the item. | ||
|
|
||
| T- he behavior of multiple add-ins that subscribe to the same event isn't deterministic. Outlook launches the add-ins in no particular order. For Excel, PowerPoint, and Word, only one random add-in will be activated. For example, if multiple Word add-ins that handle `OnDocumentOpened`, only one of those handlers will run. |
There was a problem hiding this comment.
Fix the typo at the start of the sentence: change T- he to The.
Suggested change
| T- he behavior of multiple add-ins that subscribe to the same event isn't deterministic. Outlook launches the add-ins in no particular order. For Excel, PowerPoint, and Word, only one random add-in will be activated. For example, if multiple Word add-ins that handle `OnDocumentOpened`, only one of those handlers will run. | |
| The behavior of multiple add-ins that subscribe to the same event isn't deterministic. Outlook launches the add-ins in no particular order. For Excel, PowerPoint, and Word, only one random add-in will be activated. For example, if multiple Word add-ins that handle `OnDocumentOpened`, only one of those handlers will run. |
Copilot uses AI. Check for mistakes.
| } | ||
|
|
||
| async function registerOnParagraphChanged(event) { | ||
| Word.run(async (context) => { |
There was a problem hiding this comment.
The function calls Word.run(...) without awaiting it, then immediately calls event.completed(). Consider awaiting the run promise so registration finishes before signaling completion.
Suggested change
| Word.run(async (context) => { | |
| await Word.run(async (context) => { |
Copilot uses AI. Check for mistakes.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
AlexJerabek
commented
Jul 9, 2025
|
Learn Build status updates of commit ccb6d62:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/develop/addressing-same-origin-policy-limitations.md | View | Details | |
| docs/develop/event-based-activation.md | View | Details | |
| docs/develop/use-sso-in-event-based-activation.md | View | Details | |
| docs/outlook/authenticate-a-user-with-an-sso-token.md | View | Details | |
| docs/outlook/onmessagesend-onappointmentsend-events.md | View | Details | |
| docs/outlook/spam-reporting.md | View | Details | |
| docs/testing/debug-autolaunch.md | View | Details | |
| docs/toc.yml | View | Details | |
| docs/outlook/debug-autolaunch.md | 💡Suggestion | n/a (file deleted or renamed) | Details |
| docs/outlook/use-sso-in-event-based-activation.md | 💡Suggestion | n/a (file deleted or renamed) | Details |
| .openpublishing.redirection.json | ✅Succeeded | View | |
| docs/concepts/browsers-used-by-office-web-add-ins.md | ✅Succeeded | View | |
| docs/concepts/duplicate-legacy-metaos-add-ins.md | ✅Succeeded | View | |
| docs/includes/deploy-updates-that-require-admin-consent.md | ✅Succeeded | View | |
| docs/outlook/append-on-send.md | ✅Succeeded | View | |
| docs/outlook/autolaunch-store-options.md | ✅Succeeded | View | |
| docs/outlook/autolaunch.md | ✅Succeeded | n/a (file deleted or renamed) | |
| docs/outlook/debug-ui-less.md | ✅Succeeded | View | |
| docs/outlook/index.yml | ✅Succeeded | View | |
| docs/outlook/item-multi-select.md | ✅Succeeded | View | |
| docs/outlook/mobile-event-based.md | ✅Succeeded | View | |
| docs/outlook/notifications.md | ✅Succeeded | View | |
| docs/outlook/on-new-compose-events-walkthrough.md | ✅Succeeded | View | |
| docs/outlook/one-outlook.md | ✅Succeeded | View | |
| docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md | ✅Succeeded | View |
This comment lists only the first 25 files in the pull request.
docs/develop/addressing-same-origin-policy-limitations.md
- Line 45, Column 142: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'.
docs/develop/event-based-activation.md
- Line 141, Column 296: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'. - Line 154, Column 149: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'. - Line 168, Column 174: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'.
docs/develop/use-sso-in-event-based-activation.md
- Line 13, Column 477: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'. - Line 42, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'authenticate-a-user-with-an-sso-token.md'. - Line 44, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'.
docs/outlook/authenticate-a-user-with-an-sso-token.md
- Line 57, Column 145: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'. - Line 65, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'.
docs/outlook/onmessagesend-onappointmentsend-events.md
- Line 419, Column 249: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#deploy-to-users' in 'develop/event-based-activation.md'.
docs/outlook/spam-reporting.md
- Line 359, Column 230: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'.
docs/testing/debug-autolaunch.md
- Line 11, Column 175: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'. - Line 27, Column 62: [Warning: file-not-found - See documentation]
Invalid file link: 'one-outlook.md'. - Line 31, Column 157: [Warning: file-not-found - See documentation]
Invalid file link: 'on-new-compose-events-walkthrough.md'. - Line 186, Column 23: [Warning: file-not-found - See documentation]
Invalid file link: 'sideload-outlook-add-ins-for-testing.md'. - Line 195, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'.
docs/toc.yml
- Line 900, Column 15: [Warning: file-not-found - See documentation]
Invalid file link: 'outlook/use-sso-in-event-based-activation.md'.
docs/outlook/debug-autolaunch.md
- [Suggestion: file-not-redirected - See documentation]
File docs/outlook/debug-autolaunch.md with URL /office/dev/add-ins/outlook/debug-autolaunch was deleted without redirection. To avoid broken links, add a redirection.
docs/outlook/use-sso-in-event-based-activation.md
- [Suggestion: file-not-redirected - See documentation]
File docs/outlook/use-sso-in-event-based-activation.md with URL /office/dev/add-ins/outlook/use-sso-in-event-based-activation was deleted without redirection. To avoid broken links, add a redirection.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
|
Learn Build status updates of commit 4bc9ce4:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/develop/addressing-same-origin-policy-limitations.md | View | Details | |
| docs/develop/event-based-activation.md | View | Details | |
| docs/develop/use-sso-in-event-based-activation.md | View | Details | |
| docs/outlook/authenticate-a-user-with-an-sso-token.md | View | Details | |
| docs/outlook/onmessagesend-onappointmentsend-events.md | View | Details | |
| docs/outlook/spam-reporting.md | View | Details | |
| docs/testing/debug-autolaunch.md | View | Details | |
| docs/toc.yml | View | Details | |
| docs/outlook/debug-autolaunch.md | 💡Suggestion | n/a (file deleted or renamed) | Details |
| docs/outlook/use-sso-in-event-based-activation.md | 💡Suggestion | n/a (file deleted or renamed) | Details |
| .openpublishing.redirection.json | ✅Succeeded | View | |
| docs/concepts/browsers-used-by-office-web-add-ins.md | ✅Succeeded | View | |
| docs/concepts/duplicate-legacy-metaos-add-ins.md | ✅Succeeded | View | |
| docs/includes/deploy-updates-that-require-admin-consent.md | ✅Succeeded | View | |
| docs/outlook/append-on-send.md | ✅Succeeded | View | |
| docs/outlook/autolaunch-store-options.md | ✅Succeeded | View | |
| docs/outlook/autolaunch.md | ✅Succeeded | n/a (file deleted or renamed) | |
| docs/outlook/debug-ui-less.md | ✅Succeeded | View | |
| docs/outlook/index.yml | ✅Succeeded | View | |
| docs/outlook/item-multi-select.md | ✅Succeeded | View | |
| docs/outlook/mobile-event-based.md | ✅Succeeded | View | |
| docs/outlook/notifications.md | ✅Succeeded | View | |
| docs/outlook/on-new-compose-events-walkthrough.md | ✅Succeeded | View | |
| docs/outlook/one-outlook.md | ✅Succeeded | View | |
| docs/outlook/onmessagefromchanged-onappointmentfromchanged-events.md | ✅Succeeded | View |
This comment lists only the first 25 files in the pull request.
docs/develop/addressing-same-origin-policy-limitations.md
- Line 45, Column 142: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'.
docs/develop/event-based-activation.md
- Line 141, Column 296: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'. - Line 154, Column 149: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'. - Line 168, Column 174: [Warning: file-not-found - See documentation]
Invalid file link: '../outlook/use-sso-in-event-based-activation.md'.
docs/develop/use-sso-in-event-based-activation.md
- Line 13, Column 477: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'. - Line 42, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'authenticate-a-user-with-an-sso-token.md'. - Line 44, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'.
docs/outlook/authenticate-a-user-with-an-sso-token.md
- Line 57, Column 145: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'. - Line 65, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'.
docs/outlook/onmessagesend-onappointmentsend-events.md
- Line 419, Column 249: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#deploy-to-users' in 'develop/event-based-activation.md'.
docs/outlook/spam-reporting.md
- Line 359, Column 230: [Warning: file-not-found - See documentation]
Invalid file link: 'use-sso-in-event-based-activation.md'.
docs/testing/debug-autolaunch.md
- Line 11, Column 175: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'. - Line 27, Column 62: [Warning: file-not-found - See documentation]
Invalid file link: 'one-outlook.md'. - Line 31, Column 157: [Warning: file-not-found - See documentation]
Invalid file link: 'on-new-compose-events-walkthrough.md'. - Line 186, Column 23: [Warning: file-not-found - See documentation]
Invalid file link: 'sideload-outlook-add-ins-for-testing.md'. - Line 195, Column 3: [Warning: file-not-found - See documentation]
Invalid file link: 'spam-reporting.md'.
docs/toc.yml
- Line 900, Column 15: [Warning: file-not-found - See documentation]
Invalid file link: 'outlook/use-sso-in-event-based-activation.md'.
docs/outlook/debug-autolaunch.md
- [Suggestion: file-not-redirected - See documentation]
File docs/outlook/debug-autolaunch.md with URL /office/dev/add-ins/outlook/debug-autolaunch was deleted without redirection. To avoid broken links, add a redirection.
docs/outlook/use-sso-in-event-based-activation.md
- [Suggestion: file-not-redirected - See documentation]
File docs/outlook/use-sso-in-event-based-activation.md with URL /office/dev/add-ins/outlook/use-sso-in-event-based-activation was deleted without redirection. To avoid broken links, add a redirection.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This article merges the Outlook and WXP autorun articles. Everything related to general event-based activation will be in the main article, while the walkthroughs go to other articles.
I have several open questions to the feature crew about behavior that is uncovered, so this is a draft until I get some clarity.
There is also a corresponding reference PR in the pipeline. Once this moves past the draft phase, I'll submit that one.