By popular demand: "Make It Mine" notebooks, sections, and pages! (in Preview)
Hello! This is Diane on behalf of the OneNote team in Vancouver, Canada. We're excited to announce Preview support for copying OneNote notebooks, sections, and pages on OneDrive for Business! You can copy any notebook, section, or page that you have access to, as long as the source and destination are in the same tenant.
Now, everyone can get their own copies to use however they want. This feature is a great fit for classrooms, conferences, and eLearning! For example:
You may already know about the OneNote Class Notebook and the OneNote Staff Notebook. With the new copy functionality, these notebooks can more easily grow with the curriculum.
Say you're leading a workshop. You can share a OneNote notebook that contains the agenda, content, and resources. Attendees can copy the notebook to their own OneDrive for Business on any device (including iPad, iPhone, Android, Mac, and Windows) and then take notes in their own copy.
Note: Copy functionality is currently supported on OneDrive for Business for Office 365 and SharePoint sites, not on consumer OneDrive.
Using the API
For Copy operations, you follow an asynchronous calling pattern: First call the Copy action, and then poll the operation endpoint for the result.
So first, you send a POST request to the Copy action on the item you want to copy. We added four Copy actions to the OneNote API:
CopyNotebook. Copies a whole notebook to the Notebooks folder in the destination Documents library. The folder is created if it doesn't exist.
CopyToNotebook. Copies a section to a specific notebook.
CopyToSectionGroup. Copies a section to a specific section group.
CopyToSection. Copies a page to a specific section.
In the request body, send a JSON object that contains the parameters that your operation needs. It's okay to send an empty body if none are needed.
id. The ID of the destination notebook or section group (for sections); or the ID of the destination section (for pages).
siteCollectionId and siteId. The SharePoint site to copy the item to. Use only when copying to a site.
groupId. The ID of the group to copy the item to. Use only when copying to a Unified group.
renameAs. The name of the copy (for notebooks or sections only). Defaults to the name of the existing item.
Here's an example that copies one of my notebooks to a SharePoint team site. I want to use the same name, so I didn't include the renameAs parameter.
Authorization: Bearer {token}
Content-Type: application/json
{
"siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
"siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}
If the call is successful, the OneNote API returns a 202 status and an Operation-Location header in the response. This is an excerpt of the response:
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/beta/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
…
Then, you can poll the Operation-Location endpoint to get the status of the copy operation:
Authorization: Bearer {token}
Accept: application/json
The status is included in the returned OperationModel object:
{
"@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
"id":"copy-8a211d7c-220b-413d-8022-9a946499fcfb",
"status":"completed",
"createdTime":"2015-09-16T17:32:07.048Z",
"lastActionTime":"2015-09-16T17:32:17.7777639Z",
"resourceLocation":"https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
"error":null
}
You can poll the Operation-Location endpoint until the status property returns completed or failed. If the status is completed, the resourceLocation property contains the resource endpoint for the new copy. If the status is running, the percentComplete property shows the approximate percentage completed. If the status is failed, the error and @api.diagnostics properties provide error information.
FAQs and more info
Which notebooks can I copy?
You can copy any notebook that's in your own OneDrive for Business or any notebook that's been shared with you from someone's personal site or other SharePoint site. The source and the destination must be in the same tenant.
The CopyNotebook action is most useful for:
-
Copying notebooks that are shared with you but aren't in your own OneDrive for Business.
Copying your own notebooks and shared notebooks to SharePoint sites.
Do permissions persist?
The OneNote Copy operations honor the source notebook's permissions--that is, the authenticated user must be able to access the source notebook in order to copy it. However, copied notebooks don't retain the permissions of the source. The copy has permissions as though the user just created it.
How do I get the ID of a notebook, section, or page?
You can query for IDs and other properties in your OneDrive for Business or on SharePoint sites, including personal sites. To refine your searches, use filter, select, and other query string options, as shown in these examples:
To get the IDs you need to build requests that include SharePoint personal, team, and other sites, use the FromUrl function. FromUrl takes an absolute URL to a SharePoint site …
… and returns a JSON response with the siteCollectionId and siteId for the site:
{
"@odata.context":"https://www.onenote.com/api/beta/$metadata#Microsoft.OneNote.Api.SiteMetadata",
"siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
"siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}
Remember, these Copy APIs are in Preview and may change before they're released to production. Let us know what you think here, or via UserVoice or @onenotedev!
Want to learn more about how OneNote fits into the education space? Then check out these resources:
Comments
Anonymous
January 23, 2016
Hi Diane If this functionality likely to be included as a standard feature in a future version of OneNote, for end users?Anonymous
December 05, 2016
Hi Diane,The copyToSection api has been an essential tool in developing my onenote work app. The latest update on android, ios and osx (haven't tried windows) has resulted in it becoming impossible to use. I create template pages and then embed pdfs, images and ink (and text but this works) into the pages and then copy them into notebooks as patients present for visits. This has been working forever on ios and early this year on android, but the latest update now refuses to load the pages on all the platforms (but still works on the online version). I have rolled the android tablets back to the previous version, but it has rendered the ios version pretty much useless for us at work.Prior to copyToSection and CopyToNotebook I would generate the entire page using POST and PATCH to create or update indivdual pages but this put such a load on the server that throttling was unbearable.Is it possible for the onenote-api and onenote teams to fix this issue?CheersSteve