New Extensibility in OneNote 12

Whew, sorry for that extended disappearing act. It turns out things get a little busy around beta 1, especially when combined with holidays and (in my case) my girlfriend Heidi relocating to Seattle.

Anyway today's topic is extensibility. We've taken a pretty measured approach to extensibility in OneNote up to this point, as those of you familiar with our SP1 Import API know. OneNote 12 is a little less measured, in that we now support a full import/export API (meaning that anything you can create in OneNote manually, you can now import and export as XML), a few automation APIs, and the ability to add buttons to OneNote to call into your external solution code. Our main extensibility goals for this release were to make OneNote data accessible programmatically, and to enable simple connectors between OneNote and related business applications (for example, for sales folks can push their OneNote notes directly into a CRM system). The ability to create a variety of new kinds of PowerToys comes along for free :).

The detailed documentation isn't available publicly yet (we're in the process of getting is published on MSDN), but here's a quick rundown of the methods. (If you're a Beta 1 participant, you can download the detailed doc, which contains the full method descriptions as well as some example code, from https://beta.microsoft.com under "Downloads" - just search for "OneNote" on that page.) Note that the mechanism for registering add-ins is still getting finalized, so it isn't listed here.

  • GetHierarchy, UpdateHierarchy and DeleteHierarchy. Retrieve, add, and delete pieces of the OneNote hierarchy (notebooks, folders, sections, and pages) as XML.
  • OpenHierarchy and CloseNotebook. Open sections and or open or close notebooks, as though you had used File>Open, Open Notebook, Close Notebook. 
  • CreateNewPage. Add a new page to the end of the current section. You can also accomplish this via UpdateHierarchy (which allows you to add pages at other locations than the end of the section); this method is just provided for convenience, since this is a common operation.
  • GetPageContent, UpdatePageContent, DeletePageContent and GetBinaryPageContent. Retrieve, update, or delete page content as XML. This handles all kinds of OneNote content, including text, ink, pictures, audio/video, and attached files. A parameter specifies whether to serialize the binary files inline, or return IDs that can be used to retrieve the files individually using GetBinaryPageContent.
  • SavePageAsMHTML. Returns the contents of a page in MHTML format, exactly as if you clicked File>Save As, and then selected "Current Page" as the scope and "MHTML" as the format. This is a convenience method for getting a reasonably hi-fidelity rendering of the page in a standard format, in case your intent is to display the content or use it in a non-OneNote context.
  • NavigateTo. Navigates to the object you specify (a section, a page, a paragraph, etc). You specify using the same IDs that are returned by GetHierarchy and GetPageContent. This allows you your add-in to ensure that the user is directed to the appropriate portion of their notes in response to events in the add-in.
  • GetHyperlinkToObject. Returns a onenote:// hyperlink to the object with the specified ID. Useful for embedding links in other applications or documents that, when clicked, will return the user to this exact object within OneNote.
  • FindPages. Returns the user's OneNote hierarchy as XML (like GetHierarchy), but only includes pages that match the specified search string. (Search string has same format and options as what you would type into the Find box in OneNote.) An option specifies whether to show the UI of the search running as well. This can be useful for locating a particular note previously created via an add-in.

As you'd expect, OneNote has an expanded XML schema relative to the SimpleImporter API from SP1. Without going into all the details here, sufficed to say there are elements corresponding to all the types of objects in OneNote (notebooks, folders, sections, pages, paragraphs, pictures, ink, attachments, and audio/video recordings). Also note that for now, we just have the COM API. We're be adding a managed wrapper and probably some helper functions for building/parsing OneNote XML as soon as we can, but it may be a little while yet.

As mentioned above, a primary goal is to make OneNote data accessible to external applications and business systems. CRM and Document Management systems are scenarios we've heard about from multiple customers. We hope to enable simple CRM connectors in this release, and potentially simple DM connectors as well, although this one gets a little trickier due to the combination of OneNote's saving strategy (save all changes all the time) and Document Management systems' approach (require checkout, keep version histories). What would be useful for you? What systems would you like to connect OneNote to in your own work?

Personally, I'm also looking forward to a greatly expanded realm of PowerToy possibilities, since it will be possible to add buttons to OneNote, and extract as well as import data. Auto-publish to your blog or web site of choice cannot be far behind. As always, I'd love to hear your thoughts - what do you want to build? What do you think of what we've described so far? What's missing?