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 http://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?


Comments (17)

  1. dave t says:

    Welcome back…*Oi Sergeant Major! Cancel the search party and recall that helicopter please!* *SAH!* (stamps to attention)

    Thank goodness you’re back – my poor wee finger got so sore clicking your blog link every day to see if your sensible take on all things OneNote was back yet….we now expect at least ten posts a day until Christmas to make up for it 😎

  2. Hermann Klinke says:

    Sounds good for the start. It would be great if you could also

    -create and apply flags to nodes and be able to query for these flags programmatically.

    -access to the task bar: adding and removing items

    -be able to subscribe to events such as when a notebook, section or page is added, modified or deleted or a flag is applied. You could build a notification system that would show you all the new sections or all the new pages that contain a certain flag. Very useful in a team environment to find out what has been changed or added since I have seen that shared notebook.

  3. This is great. You are taking it in the right direction. I am a recent OneNote convert and I am starting to really love it. Hey, how about adding a blog editor/poster? Why should I have to jump out to a buggy shareware app like Ecto or BlogJet?

    Does Scoble have any thoughts on this?

  4. owenb says:

    dave_t – that’s very kind, and thanks for not giving up. Don’t know if I can manage ten posts a day, but we’ll see :).

    Hermann – great suggestions. FYI, there are some discussions about events going on right now within our team. We’re extremely limited in what we can add at this point, but we might yet get something here. We all keep burning the torch for Note Flag extensibility, but it just didn’t fit in this release. For "task bar", are you referring to the note flag summary? If so, you can in fact add to this using the import API (by applying flags programmatically). You can even apply to existing content by exporting, identifying the paragraph you want to flag, and re-importing.

    S.M. – glad this sounds good. Re: blogs, Scoble asks us about it every time we see him :). We definitely think it’s a good fit, and since a direct "publish to blog" feature didn’t make it into the product for this release, this is one of the scenarios we hoped to enable via extensibility. The APIs are sufficient for it – we just haven’t had a chance yet to build the powertoy. I expect we’ll see more than one of them in the relatively near future :).

  5. Jack Shainsky says:

    Thanks for the great news!

    The feature that I’m most missing in OneNote 2003 is the ability to synchronize the Note Flag summary with Palm or Web. I’m using OneNote for implementing the GTD system and ability to view and add my Next Actions in my phone or over the web via PowerToys will make OneNote12 The Tool for GTD.

  6. Hermann Klinke says:

    Owen Braun: For "task bar", are you referring to the note flag summary?

    Yes, I meant the flag summary pane. You call it "Task Pane" in OneNote under the View menu. Your import/export suggestion is a little hackish, I would actually like to create my own list since the task pane can contain different content (e.g. page list).

    I have a list of more than 30 suggestions and bugs to send to you, but they do not have anything to do with extensibility. But I have noted several API Usage examples. I’ll send it all to you when I’ll get around to do it. I do not have much time right now.

  7. Owen Braun says:

    Jack – that’s a great scenario. Keep an eye on Will Kennedy’s Outlook blog, and future posts on mine here – part of the reason we haven’t gone after that scenario as much for OneNote alone is because of some increased integration between OneNote and Outlook tasks (along with some changes on the Outlook side).

    Hermann – definitely send along the list when you get a chance. Or even pieces of it. Thanks for posting!

  8. EMRhelp.org says:

    ""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).""

    Having OneNote be a part of my Document Management solution would be a huge leap forward for OneNote. Allowing the Handwriting Recognition results would make it an indispensable tool for Tablets and people like me who write and type on documents with a graphics tablet.

    Owen – I’d love for you to try OneNote with a Wacom Graphire4 6×8 graphics tablet. You should feel how nice it works and plus you’d see that you need a few things to get it to FLY … like a way to toggle between INK and Type/Selection Tool (with a keyboard shortcut).

  9. Tim says:

    Please please please let us know if the team is reconsidering only syncing content in the "mobile" folder to a ppc or palm device. That limitation would cripple its capabilities. When you search for something, you count on google desktop (or a similar app) to index _the whole drive) to find what you’re looking for — if it had to be in a specific folder, you wouldn’t find what you’re looking for most of the time. I know images, audio and video get huge, but please give us a workaround! Like, since OneNote will OCR pdfs, make the pdf _content_ searchable, and don’t sync the actual pdf. Something. Please let us know if your team thinks of alternatives… Thanks!

  10. Lawrence says:

    There’s a great OneNote PowerToy that automatically creates a new Journal entry page based on the current date. However, a crippling limitation with the current API is that the new page created does not pick up the default stationery for the current section. Any chance of this being fixed in OneNote 12?

  11. ErikR says:

    Comment:  When I describe OneNote, I explain it is like a hybrid app…  It has word-processing like Word, object positioning like Publisher, organization like Access (searching notes), searching prowress of a web search engine, and even audio and video capabilities to boot!  OneNote is really a revolutionary application that has really changed the way I use my computer, and made my TabletPC an indespensible work tool.

    Now, since OneNote has the functionality of so many other applications, is there anyway you can take on email?!  OneNote is great, but Outlook fizzles in comparison, when a TabletPC user has to use Outlook.  There are so many places that Outlook could do better if it could do things that OneNote could do…even in just the simple areas of Notes or Journals.  Yeah, I’ve got the Tablet Enhancements for Outlook TEO, but its an add-in and not "fully" integrated as much as I’d like.  

    If the functionality of Outlook and OneNote could somehow be brought together…now that would be an incredibly usefull business tool!!!

  12. Beta 1 of "OneNote 12" (and "Office12") is now available for download for those people who are signed…

  13. Geoff says:

    When you say a little while yet for a managed wrapper, do you have a time frame in mind?  Are you planning to have this available in Beta 2?   I’d really like to see OneNote fully integrated to .Net and also included in the next release of VSTO.

  14. David Joyce says:

    You chaps have done a fantastic job – and the granularity of your audit trail is fantastic. One essential thing in the post SOX FDA regulated world I live in is audit of what is deleted by who and when.

    Change control is possible via the API but I cant see how I would attribute the delete events to a user.

    The best I could do would be to say XYZ item was deleted during this period..

    Is there a way around this for us regulated folk?

    Perhaps an event which flags a user change is all we need – or a deleted tag in the schema?

    All the best,

    DJ

  15. Beta 1 of "OneNote 12" (and "Office12") is now available for download for those people who are signed

  16. Memmorium says:

         Good idea!

    P.S. A U realy girl?