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. 

POST https://www.onenote.com/api/beta/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copynotebook

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

Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb

 

Then, you can poll the Operation-Location endpoint to get the status of the copy operation: 

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb

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: 

GET https://www.onenote.com/api/beta/me/notes/notebooks/{id}/sections?select=id\&filter=name%20eq%20'Homework'

GET https://www.onenote.com/api/beta/myorganization/sitecollections/{id}/sites/{id}/notes/notebooks?select=self

 

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 … 

GET https://www.onenote.com/api/beta/myorganization/sitecollections/FromUrl(url='https://domain.sharepoint.com/site-a')

 

… 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: