Announcing changes to Office Add-ins’ ExecuteFunction commands

Microsoft Office 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)

The following is an example:


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


These changes must be made 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. Please 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 the Office JavaScript library is loaded with the data-use-associated-actions-only attribute, only add-in commands that are registered with the associate API will run. Any add-in commands that are not registered with the associate API will fail to run. 

You can find complete add-in samples in our GitHub repo. To learn more about add-in commands, see our documentation.

For questions, we invite you to join our monthly Office Add-ins community call. Lastly, if you run across any issues, please report them in the Github repo.

Additional resources

Office Developer Center

0 comments

Leave a comment