Integrating OneNote 2007 with a Document Management System
Alex Simmons, Microsoft Corporation
Applies to: Microsoft Office OneNote 2007
Summary: Learn how to create a Microsoft Office OneNote 2007 add-in to integrate OneNote with a document management system. Read a brief summary of OneNote and design options based on the OneNote API. (10 printed pages)
In the Microsoft Office OneNote 2007 file hierarchy, a Section equates to a single OneNote file and has a .one file name extension. In the OneNote user interface (UI), however, the largest unit of organization is the notebook. In each notebook, there can be numerous sections according to user preference.
Fundamentally, there are five different types of organizational structure in the OneNote UI:
Sections (.one files)
There are hierarchical rules about which type of structure can exist within other pieces of structure:
Notebooks can have:
Section groups can have:
Sections can have:
A user can have more than one notebook. By default, OneNote provides three notebooks. Each notebook contains the following default sections and pages as introductory material:
OneNote Best Practices
In the file system, here is how each piece of UI structure is represented:
Notebooks are always folders.
Section groups are always folders.
Sections are always .one files, and are always children of a notebook (folder) or a section group (folder).
In OneNote 2007 Beta 2, if there are file attachments stored on any of the pages in the section, a thicket folder is created as a sibling of the .one file. This thicket folder contains copies of the files stored on the pages for that section, and must be moved if that section is moved. If the thicket folder is not moved so that it is always a sibling of the section file, the attachments in the OneNote UI are no longer functional if you try to open them in the OneNote UI.
A change with the release version of OneNote 2007 is that attachments are stored with the .one file. Thicket folders no longer exist, unless the section is stored in a Microsoft Office SharePoint Server 2007 library, in which case, thicket folders to store attachments are automatically created by OneNote.
You cannot close the OneNote application, nor can you close sections, section groups, pages, or subpages. However, you can close notebooks.
In general, users do not choose to close notebooks. They usually leave them open indefinitely, so that every time they close and reopen OneNote, the files shown in the UI are unchanged. Usually, users close notebooks only to remove them from the UI, when they are finished with a project or if they rarely look in that notebook and want to see fewer notebooks.
Unlike other Microsoft Office file types, users cannot open, edit, and then close OneNote files. You should assume that they leave them open.
Files Are Saved Automatically
Any changes made to the files are saved automatically. This happens on an interval, which differs based on where the file is actually stored:
Local drive: 5 seconds
UNC share: 30 seconds
SharePoint library: 10 minutes
HTTP share: 10 minutes
By default, notebooks are stored in the user's My Documents folder.
Working with the OneNote Cache
When OneNote saves a change to a file, it first saves the change to the OneNote cache, and then later replicates and merges it with the actual .one file. The .one files may be stored on the local drive, on a share, or in a SharePoint library. The cache enables users to have continuous access to their notes, regardless of where the files are actually stored or if the user is online or offline. Users can make edits to files while they are offline and OneNote automatically merges the changes back to the file when the file is available again. This also prevents OneNote from writing the entire file from the cache each time replication happens. Instead, only changes are replicated and merged with the actual file.
If your document management system supports SMB/CIFS or WebDAV, it may be possible to open the files stored in the document management system directly. However, if your version-history model is to create a copy for each version of a file, this does not work well, because OneNote continuously updates the open (and checked out) files as they are edited.
By default, the cache file is stored at C:\Documents and Settings\user name\Local Settings\Application Data\Microsoft\OneNote\12.0.
Cache file name: OneNoteOfflineCache.onecache
Cache thicket folder name: OneNoteOfflineCache_Files
The two following implementations do not require use or knowledge of the cache. This information is provided for clarity.
File Attachments and .one Files
There is a single .one file for every section shown in the OneNote UI. If there are attachments (inserted files, or audio/video recording files) that are inserted into the section, they are also stored in the .one file. When users open, edit, save, and close an attachment, such as a Microsoft Office Word .doc file, OneNote updates the copy of the attachment stored in the .one file.
For the Beta 2 version of OneNote 2007, publishing to a .one file does not include any file attachments. They are saved into a thicket folder. The release version of OneNote 2007 saves them as part of the .one file.
Adding Buttons to an Existing OneNote Toolbar
A custom add-in can add multiple buttons to OneNote toolbars, with these limitations:
Buttons must be added to an existing toolbar. OneNote does not support the ability to create your own toolbar programmatically.
Buttons appear at the end of the specified toolbar.
The following solutions are optimized for two different scenarios:
Scenario One: Checked-Out Files Visible. If your customers typically work with only a few files from the document management system at one time and that set does not change frequently, consider having only the checked-out files show in OneNote.
Scenario Two: All Files Visible. If your customers collaborate frequently and many contributors update the same set of files, you may want to make all OneNote files that are stored in the document management system visible from OneNote, for a specified project. This option enables contributors to see the changes and new files that others make in OneNote.
Scenario One: Checked-Out Files Visible
This approach is modeled after how checking a file in or out from a document management system works for standard document file types, such as a .doc file. When users check out files from the document management system to edit in OneNote, OneNote makes copies in a notebook called Checked Out Notes. While the files are checked out, the users can change the files as needed, including editing them offline from the OneNote cache. They can even move files into a shared notebook so that others who have access to this shared notebook can collaborate, using OneNote multi-user editing features. When the users finish editing and check the files back in, OneNote removes the files from the UI and saves a copy of the changed files back to the document management system. This model shows only checked-out files from the document management system in the UI.
OneNote 2007 Beta 2 does not save file attachments (such as embedded .doc files or audio or video recordings) as part of the .one file. For OneNote 2007 Beta 2, you can test using the .one format, but understand that the file attachments will not be part of the .one file.
Scenario Two: All Files Visible
While more labor-intensive, this approach provides the best solution for integrating OneNote with a document management system.
This option assumes that your document management system includes the equivalent of a "project" in its UI. The mapping from document management system to OneNote is Project name in the document management system to Notebook name in OneNote.
This approach shows all of the OneNote files stored in the document management system for a particular project within a single OneNote notebook. By default, the user has a read-only view of the OneNote files stored in the document management system. Periodically, as files are updated on the document management system, the add-in queries the document management system and updates the view of the notes in OneNote.
From OneNote, users can check out OneNote files, make updates to the files, and then check the files back in, which updates the files stored on the document management system. As in Scenario One, users can also create additional files in the document management system from existing content in their OneNote notes by saving notes to the document management system. In this model, the add-in must do the following:
Query the document management system for changes and update the files on the user's computer.
Set the read-only status on the .one files on the user's computer for files that are not checked out.
Adhere to the same check-out, check-in, and save procedures as Scenario One.
The following section describes, in general, how to implement this scenario. Although it does not provide step-by-step instructions, the intention is to describe possibilities and inspire you to create even better experiences for your document management system and OneNote customers.
Implementing Scenario One: Checked-Out Files Visible
To implement this scenario, you need to add three buttons to the OneNote UI:
Save Notes to DMS
The following sections describe the required button behaviors.
Button Behavior: Save Notes to DMS
Case 1: Current Page Is Part of a Checked-Out File
The add-in finds a property on the file that says the file is checked out.
The add-in publishes the local file and replaces the file stored in the document management system and does not check in the file.
Depending on how your document management system tracks version history, you may not want to replace the file that is stored in the document management system. You may want to leave that version intact and save a new version of the .one file to the document management system.
Case 2: Current Page Is Not in a Checked-Out File
The add-in does not find a property on the file that says the file is checked out.
Option One (Recommended). A dialog box offering scoping options is presented to the user. The user can save the current selection, page, page group, or section as a new file to the document management system. After choosing the scope, the user can browse the hierarchy of the document management system to choose where to save the file and what to name it. A new file that matches the specified scoping is saved to the document management system.
After saving the file, another dialog box should ask if the user wants to check out the file to continue editing the version stored in the document management system.
If the user checks out the file, OneNote opens the file in a specified folder (for example, the Checked Out Notes folder), exactly the same as if the user had checked out the file using the Check Out button.
If the user does not check out the file, the user stays on the current page and cannot edit the file that is stored in the document management system.
Option Two (Alternative). Assume the scope according to context and do not give the user an option to control it. In this case, setting the default option to section (the file equivalent in OneNote) is a logical choice.
You can save OneNote files to the document management system by using the Publish method:
OneNote 2007 Beta 2 publishes the .one file to the document management system. Attachments and audio files are put in a thicket folder next to the .one file.
The release version of OneNote 2007 publishes the .one file to the document management system. Attachments and audio files are included in the .one file.
Button Behavior: Check Out
Pressing Check Out should open a dialog box where users can browse their document management system to check out a file. The add-in then copies the specified file to a specified folder notebook, for example, a Checked Out Notes folder.
If the notebook does not already exist:
Option One (Recommended). Pressing Check Out prompts the user for a location to create this notebook, then creates the notebook in the specified location and copies the checked-out file there.
Option Two (Alternative). Pressing Check Out creates the new notebook in the user's My Documents folder, in the \OneNote Notebooks directory, and copies the checked-out file there.
If the notebook already exists, Pressing Check Out copies the file there.
A property should be stored on the file so that the add-in can quickly and dependably tell if the file is checked out.
OneNote 2007 Beta 2 copies the .one file to the specified notebook. You must also copy the folder containing attachments and audio files to the folder next to the .one file for them to work properly.
The release version of OneNote 2007 saves the .one file to the specified notebook.
The add-in opens the copied .one file and opens to the last modified page in that section.
Button Behavior: Check In
Clicking the Check In button should save the file back to the document management system in the same way as clicking the Save Notes to DMS button.
It should also delete the file from the specified Check Out notebook (and corresponding thicket folder, if you created one).
If the current section (the section the user is currently viewing) is not a checked-out file, disable this button.
The user can move the checked-out file from the default notebook to any other notebook that is open. You should still be able to check a file in from that location and delete it from that notebook after check-in.
You should also create implicit check in of files.
Most document management systems that integrate with Microsoft Office today automatically check in open files when the files are closed.
Option One (Recommended). If the user closes OneNote and there are still files checked out, present the user with a dialog box that gives them the following options:
Check In. The file is checked in.
Save only. File is saved to the document management system but the file is still checked out.
Keep Checked Out. The file is still checked out; it is not saved or checked in. Do not do anything. The file remains stored in the specified notebook and is available to the user the next time OneNote is opened.
You also may want to include a check box with the option to never prompt for this again, and a way to set the default action.
Option Two (Alternative). Check in the file.
How to Implement
When OneNote closes, it calls all active add-ins to release. When an add-in gets that release call, it should not release immediately. It should do the following:
Bring up a dialog box that prompts the user to indicate what to do with the open files.
If the user chooses to keep the file checked out, go to Step 8.
Display a progress meter or dialog box that says "Checking in the file to the document management system" or "Saving the file to the document management system."
Publish the file to the document management system.
If the user chose to save but not check in, go to Step 8.
If the user chose to check in, check the file back into the document management system.
Delete the file stored locally from the OneNote hierarchy.
Close the progress dialog box.
Complete the release of the add-in so OneNote can finish closing.
Even though OneNote users can have multiple OneNote windows open, all of which can show the add-in buttons, when a window is closed the add-in does not receive a release call unless it is the last window open, meaning the OneNote process is being shut down. Therefore, the add-in does not receive more than one release call per OneNote session.
Viewing .one Files Stored in a Document Management System
All .one files stored in the document management system should be marked read-only. This is so that, if a user opens the file to view it, the user cannot edit it in OneNote and potentially be confused about whether they can check in the changes they made to the file. Such files are opened automatically by OneNote into the Recently Viewed Notes folder.
If the user already has a file checked out, any file opened directly from the document management system still opens into the Recently Viewed Notes folder.
Optionally, the add-in can check to see if the file is currently checked out by that user and, if it is, navigate the user to that checked-out file rather than opening to the Recently Viewed Notes folder.
Checking Files In or Out from the Document Management System
Optionally, users should have the same access from within the document management system UI to .one files that are stored in the document management system as to any other file types. They should be able to check .one files in and out directly from the document management system. To do this, the document management system must use the add-in to check out the file in the document management system and open it in OneNote, in the same way as is used if the checkout occurs in the add-in UI in OneNote.
Implementing Scenario Two: All Files Visible
You can reuse many of the same strategies described in the previous scenario. This section outlines details specific to implementing Scenario Two: All Files Visible.
Add a DMS Project Button
To implement this scenario, you need to add an additional button, the Open DMS Project button. If the user clicks the button, the user can browse the document management system and choose a project. In this example, the term project is used to describe a form of organization in the document management system. It is useful to have some form of parent hierarchy so that new files that are added to the same project in the document management system appear in the same project notebook in OneNote. Add-in authors should decide the best way to scope this based on the organization of the document management system. You want to:
Ensure the add-in copies all of the .one files to a new notebook in OneNote.
Have the user provide a name for the notebook and specify a location to save it. Alternatively, you could choose to use the project name for the notebook name and save it to the default location for OneNote files.
Ensure that files copied into the notebook are read-only until they are explicitly checked out. You can set read-only attributes using APIs from the file system.
If there is an organizational structure within the project in the document management system, such as nested folders with different OneNote files, you can duplicate this structure in OneNote by creating the same folder structure in the notebook folder. In the OneNote UI, these folders would map to section groups. Section groups can contain additional section groups or sections, enabling you to duplicate organization structures that you may encounter within a document management system.
Synchronizing OneNote and the Document Management System
Because OneNote opens files in the document management system as read-only by default, you can only save changes to files in the document management system when a user checks in a new version.
The add-in should query the document management system at a specified interval to check for new or updated files. If possible, you may also want the document management system to notify the add-in directly rather than having the add-in query the document management system.
If the add-in finds new or updated files, it should copy the new file into the OneNote notebook, replacing the old file, if it exists. The updated file should remain read-only in OneNote.
Checking Out a File from OneNote
If users click Check Out while they are looking at a read-only file, the add-in should query the document management system for file updates before checking the file out:
If the user has the most recent version, the add-in should remove the read-only attribute on the file in OneNote. You can set read-only attributes using APIs from the file system.
If the version from the document management system is more recent, the add-in should download the most recent copy of the file and then remove the read-only attribute on the file.
If the file in the document management system is checked out by another user, the add-in should prompt the user with this information.
Upon check out, the add-in should mark the file in the document management system as checked out.
You should be aware that, while it is not common, it is possible that by using the file system a user could give write access to a read-only OneNote file that the user does not have checked out. Because this could cause a version mismatch between the version in the document management system and the version in OneNote, the add-in should check this attribute periodically and warn the user if they made a file that was not checked out writable, their changes may be lost when trying to check the file in or out.
Showing Check-Out Status in OneNote
OneNote does not have a status bar, or a traditional File Properties dialog box.
The best way to show checked-out status of a file from the OneNote UI is to add the string (checked out) to the name of the file. The OneNote API supports changing the name of files inserted by the add-in.
You should decide whether to update the name stored in the document management system or whether to only update the names of the files in OneNote. The add-in could only rename the files that are open in OneNote if the document management system is reporting the file as checked out, rather than renaming the actual file in the document management system.
The add-in could also add the user name of the person who has the file checked out to the file name as additional information, for example, (checked out by user name).
Checking In a File from OneNote
If a user clicks Check In, the add-in should publish the file to the document management system, as described in Scenario One: Checked Out Files Visible.
Instead of deleting the OneNote copy of this file, as in Scenario One, the add-in should mark the file as read-only.
Tracking Document Management System Files in OneNote
In addition to attaching a property to the files that are checked out, you should attach a special property to all of the files opened from the document management system so that, when the add-in queries the document management system, it can easily find the files in OneNote in case the user moves them to a different notebook.
This second property can be specific to the document management system project, or it can be a generic document management system association.
Viewing or Accessing Other Application Files from OneNote
OneNote is not a file explorer. The OneNote UI can list only notebooks, sections, and section groups.
If there are other file types stored in the document management system project, but not stored in a OneNote thicket folder, OneNote cannot display these.
The add-in could create its own read-only section or page in an existing section, to show the other project files, and it could hyperlink them directly to the files in the document management system. This would be another item that the add-in would need to check and update when it queries. Because the add-in can add or remove content directly from OneNote pages, it could keep the list of hyperlinks synchronized with the files in the document management system.
However, you should not create links in this way to files stored in OneNote thicket folders. Those files are represented as attachments on the OneNote page, so it would be confusing for the user if these files were included in the list of hyperlinks.