Announcing changes to Office Add-ins’ ExecuteFunction commands

Office Add-ins team

Office Add-ins have long supported custom ribbon buttons and menus, called add-in commands. For Word, Excel, PowerPoint, and Outlook, these come in two flavors: those that open a task pane and those that call a JavaScript function. For the latter ExecuteFunction type of command, you create a function in a JavaScript file and then identify the function by name in the manifest. The JavaScript file is loaded by a UI-less HTML file, usually called functionfile.html or commands.html.

To improve security in Office Add-ins, we are changing how you create ExecuteFunction add-in commands. This change does not require re-submission of your Office Add-in.

In addition to defining the JavaScript function, you also need to register the function with Office by adding a call of Office.actions.associate("name-of-function", function).

Office.actions.associate("name-of-function", function)

Office Add-ins ExecuteFunction code sample

function writeText(event) {
    // Implement your custom code here. The following code is a simple example.   
    Office.context.document.setSelectedDataAsync("ExecuteFunction works. Button ID=" + event.source.id,
        function(asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                // Show error message. 
            } else {
                // Show success message. 
            }
        });
    // Calling event.completed is required. event.completed lets the platform know that processing has completed. 
    event.completed();
}
// Register the function with the associate API 
Office.actions.associate("writeText", writeText);

IMPORTANT


You must make these changes before October 30, 2022. On that date, functions in the ExecuteFunction type add-in commands that are not registered in this way will no longer run. So, lease update your Office Add-in as soon as possible to avoid impacting your add-ins functionality.

To test that you’ve correctly registered your functions, you can simulate how Office will behave on October 30, 2022. Add an attribute to the <script> tag that loads the Office JavaScript library in the HTML file. The following is an example:

[html]
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" data-use-associated-actions-only="1" type="text/javascript"></script>
[html]

When you load the Office JavaScript library with the data-use-associated-actions-only attribute, registered add-in commands will run. Add-in commands that you do not register with the associated API, will not.

 

Additional resources

Happy coding!

0 comments

Discussion is closed.

Feedback usabilla icon