OneNote JavaScript API programming overview

OneNote introduces a JavaScript API for OneNote Online add-ins. You can create task pane add-ins, content add-ins, and add-in commands that interact with OneNote objects and connect to web services or other web-based resources.

Note: When you build your add-in, if you plan to publish your add-in to the Office Store, make sure that you conform to the Office Store validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Components of an Office Add-in

Add-ins consist of two basic components:

  • A web application consisting of a webpage and any required JavaScript, CSS, or other files. These files are hosted on a web server or web hosting service, such as Microsoft Azure. In OneNote Online, the web application displays in a browser control or iframe.

  • An XML manifest that specifies the URL of the add-in's webpage and any access requirements, settings, and capabilities for the add-in. This file is stored on the client. OneNote add-ins use the same manifest format as other Office Add-ins.

Office Add-in = Manifest + Webpage

An Office add-in consists of a manifest and webpage

Using the JavaScript API

Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • A rich API for OneNote-specific operations, accessed through the Application object.
  • A common API that's shared across Office applications, accessed through the Document object.

Accessing the rich API through the Application object

Use the Application object to access OneNote objects such as Notebook, Section, and Page. With rich APIs, you run batch operations on proxy objects. The basic flow goes something like this:

  1. Get the application instance from the context.

  2. Create a proxy that represents the OneNote object you want to work with. You interact synchronously with proxy objects by reading and writing their properties and calling their methods.

  3. Call load on the proxy to fill it with the property values specified in the parameter. This call is added to the queue of commands.

    Note: Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. Call context.sync to run all queued commands in the order that they were queued. This synchronizes the state between your running script and the real objects, and by retrieving properties of loaded OneNote objects for use in your script. You can use the returned promise object for chaining additional actions.

For example:

    function getPagesInSection() {
        OneNote.run(function (context) {
            
            // Get the pages in the current section.
            var pages = context.application.getActiveSection().pages;
            
            // Queue a command to load the id and title for each page.            
            pages.load('id,title');
            
            // Run the queued commands, and return a promise to indicate task completion.
            return context.sync()
                .then(function () {
                    
                    // Read the id and title of each page. 
                    $.each(pages.items, function(index, page) {
                        var pageId = page.id;
                        var pageTitle = page.title;
                        console.log(pageTitle + ': ' + pageId); 
                    });
                })
                .catch(function (error) {
                    app.showNotification("Error: " + error);
                    console.log("Error: " + error);
                    if (error instanceof OfficeExtension.Error) {
                        console.log("Debug info: " + JSON.stringify(error.debugInfo));
                    }
                });
        });
    }

You can find supported OneNote objects and operations in the API reference.

Accessing the common API through the Document object

Use the Document object to access the common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

For example:

function getSelectionFromPage() {
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text,
        { valueFormat: "unformatted" },
        function (asyncResult) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(error.message);
            }
            else $('#input').val(asyncResult.value);
        });
}

OneNote add-ins support only the following common APIs:

API Notes
Office.context.document.getSelectedDataAsync Office.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsync Office.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
var mySetting = Office.context.document.settings.get(name); Settings are supported by content add-ins only
Office.context.document.settings.set(name, value); Settings are supported by content add-ins only
Office.EventType.DocumentSelectionChanged

In general, you only use the common API to do something that isn't supported in the rich API. To learn more about using the common API, see the Office Add-ins documentation and reference.

OneNote object model diagram

The following diagram represents what's currently available in the OneNote JavaScript API.

OneNote object model diagram

Additional Resources