Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Convert Notes to Enhanced Notes


In Winter '16 the new enhanced Notes tool became generally available, and with it introduced a new "Notes" related list separate from the classic "Notes & Attachments" related list.

In Spring '17 Salesforce announced that after Winter '18 the "Notes & Attachments" related list will no longer have an upload or attach button. Customers will be required to migrate to and adopt Salesforce Files. Although this change is specific to Attachments/Files, it is very clear that "Notes & Attachments" related list will eventually be retired in favor of the new Files and Notes related lists.

At the time of this project, Salesforce has not (yet?) provided an official conversion tool from Notes to Enhanced Notes.

This project enables the manual or automatic conversion of classic Notes into Enhanced Notes to take advantage of more sophisticated features, like sharing, revisions, rich text, images, etc.

The package includes visualforce pages that let you:

  • Configure sharing and conversion options
  • Run test conversions
  • Enable near real-time or scheduled conversions

Additional Background:

Related Ideas


  • Summer '17 (API 40.0) or later

  • Enable Create Audit Fields so Note create/update/owner fields can be preserved on the new enhanced notes

screen shot

  • Enable New Notes so ContentNote object exists and the new note-taking tool is available

screen shot

Packaged Release History

Release 1.4 (current)

  • Install package
  • Adds support for "Guest Site" users creating notes when the near real-time trigger option is enabled.
  • Adds option to specify "Max Records to Convert" for customers who have more notes to convert than the daily allowed Content Publication Limit. This allows those admins to better plan multi-day conversions. (Issue 1)
  • Updated all code to API v41.0 (Winter '18)

Release 1.3

  • New with Winter '18, private notes are converted and shared to parent record using new File Privacy on Records field. (Issue 21)
  • Fixes issue where empty classic note body appears as <p></p> in converted enhanced note. (Issue 19)

Release 1.2

Please note, this app always preserved the original CreatedDate of the converted note but the LastModifiedDate was always "today" because of how the new Enhanced Note was being shared to the parent record. In my original design I had opted to give you all more options around how the newly converted Enhanced Note gets shared to internal and community users as well as whether users with access to the parent entity inherited read-only or edit access to the file. But those options came at the cost of never being able to preserve the original LastModifiedDate.

Responding to your all's feedback and use cases, this version of the app now preserves the LastModifiedDate of the original note! However, to make this possible means the app no longer manually shares the new Enhanced Note by explicitly creating ContentDocumentLink records. This has the side effect that two previously available conversion settings have now been removed:

  • Which community of users who have access to the note's parent record get access to the converted notes?
  • How should view or edit access to the converted note be granted to users with access to the note's parent record?

These options now rely on the Salesforce defaults.

Release 1.1

Release 1.0

  • Initial release

Installing the Source Code (Developers)

You may install the unmanaged code from GitHub and make any desired adjustments. You are responsible for ensuring unit tests meet your org's validation rules and other requirements.

Getting Started

  1. Enable setting Create Audit Fields so Note create/update/owner fields can be preserved on the new enhanced notes
  2. Enable setting New Notes so ContentNote object exists and the new note-taking tool is available
  3. Add "Notes" related list to your page layouts (e.g. Accounts, Contacts, Tasks, Events, etc.)
  4. Deploy the package using one of the installation links above
  5. Assign yourself the permission set Convert Notes to Enhanced Notes then switch to the app by the same name
  6. On the Convert Notes to Enhanced Notes tab page, click on Setup Conversion Settings to configure sharing and conversion behavior
  7. Perform a test conversion
  8. Consider automating conversion

screen shot

screen shot


Salesforce System Errors

Salesforce System Error: 208410828-86802 (1615802660)

Salesforce System Error: 623811003-63707 (123133497)

According to Salesforce documentation,

ContentNote currently provides a generic error like "Note could not be saved." whenever an issue is encountered while parsing the Note file itself. This is often an indication of an issue with the contents of the text body (Content) file, such as special character(s) that have not been properly escaped.

Any conversion errors are reported in the Convert Notes to Enhanced Notes Logs object. If the details reported there are not sufficient for you to resolve the conversion issue then if you trust me share with me the note trying to be converted and I'll see if I can pinpoint if it's due to special characters or encoding.

You may need to manually export your Note records and replace any special characters then update them back into Salesforce prior attempting to convert them. Please see comments made by Rachel Park on this thread in Success Community on 8/23/2017:

"Using Data Loader, I actually exported all of the original Notes and did a find/replace on the special characters in Excel and then updated the records in Salesforce. When I ran the conversion process again afterwards, everything completed fine!"

Regex too complicated

You may encounter this error if your original note is very large or contains a lot of HTML formatting.

If you trust me share with me the note trying to be converted and I'll see if I can pinpoint the cause and provide a fix.

Max Documents or Versions Published Governor Limit

When converting classic Notes & Attachments the new data is stored in the ContentVersion object. There is a limit to how many of these records can be created in a 24 hour period. With Summer '17 release the limit is increased from 36,000 to 200,000! If you have a lot of Notes & Attachments to convert plan around this limit and split the work across multiple days.

Field is not writeable: ContentVersion.CreatedById

When you deploy the package you might get error that files are invalid and need recompilation and one of the specific messages might say "Field is not writeable: ContentVersion.CreatedById". The conversion tool tries to copy the notes's original created and last modified date/user to the converted enhanced note. To do so then the "Create Audit Fields" feature must be enabled. Please see this help article for instructions enable this feature.

screen shot

screen shot

Visibility InternalUsers is not permitted for this linked record.

When the conversion tool shares the enhanced note to the note's owner and parent record the ContentDocumentLink.Visibility field controls which community of users, internal or external, may gain access to the enhanced note if they have access to the related record.

When communities are enabled then both picklist values AllUsers and InternalUsers are acceptable. When communities are disabled then only the picklist value AllUsers is acceptable.

This error usually means communities are disabled in your org and you're trying to set the visibility of the converted enhanced notes to InternalUsers.

To fix then either (a) enable communities or (b) change the visibility option to AllUsers.

INSUFFICIENT_ACCESS_OR_READONLY, Invalid sharing type I: [ShareType]

This error means the object the new file is trying to be shared to does not support the conversion setting Users inherit view or edit access to the file based on their view or edit access to the attachment's parent record and instead you must try Users can only view the file but cannot edit it, even if the user can edit the attachment's parent record.

This is known to occur with Solution object and likely other objects.

FIELD_INTEGRITY_EXCEPTION, Owner ID: id value of incorrect type: 035xxxxxxxxxxxxxxx: [OwnerId]

Prior to Spring '12, Salesfore customers could have Self-Service Portals, which pre-date the modern Communities we have today. This error means the Note is owned by a Self-Service User and ContentVersions cannot be owned by them. You may want to consider changing ownership of those notes to actual user records whose IDs start with 005 prefix.

How are private notes converted?

Starting with Release 1.3 of the app, private notes are converted to enhanced notes and related to the parent record as you would expect and the enhanced note's privacy is preserved by using Winter '18 feature **File Privacy on Records".

Prior to Release 1.3, private notes were handled differently:

Classic Notes & Attachments have an IsPrivate checkbox field that when selected makes the record only visible to the owner and administrators, even through the Note or Attachment is related to the parent entity (e.g. Account or Contact). However, ContentNote object follows a different approach. Rather than an explicit 'IsPrivate' checkbox it uses a robust sharing model, one of the reasons to convert to the new enhanced notes to begin with! In this sharing model, to make a record private then it simpy isn't shared with any other users or records. The caveat then is that these unshared (private) enhanced notes do not show up contextually on any Salesforce record. By sharing the new enhanced note with the original parent record then any user who has visibility to that parent record now has access to this previously private note.

Therefore, when converting you have the option to:

(a) ignore private notes and not convert them

(b) convert and share them with the parent entity

(c) convert them but don't share them with the parent entity, they will reside in the note owner's private library

Inactive Owners

ContentNote records cannot be created and be owned by an inactive user. The enhanced notes must be owned by an active user to be created otherwise get error INACTIVE_OWNER_OR_USER, owner or user is inactive.. Prior to running conversion you should either (a) update all old notes with inactive owners to be owned by an active user, or (b) convert them manually first.

If I run the conversion multiple times, do duplicate enhanced notes get created for the same notes?

No, no duplicate enhanced notes should be created once a note has been converted once. When notes are converted into enhanced notes we store the Note.ID in the ContentVersion.Original_Record_ID__c field for tracking purposes. The conversion logic first checks if there exist any enhanced notes that have been stamped with the note id, if yes then we skip converting that note again.

Of course, if you choose the conversion option to delete the notes upon conversion then no such note would exist the second time around. But if you choose to keep the notes post conversion they will not be converted again if you run conversion process multiple times.


This is not an official conversion tool by to migrate Notes to Enhanced Notes. This is a personal project by Doug Ayers to assist customers in migrating to and adopting Enhanced Notes. Although this tool has been successfully tested with several customers since 2015 that have between dozens to tens of thousands of notes, please do your own due diligence and testing in a sandbox before ever attempting this in production.

Always make a backup of your data before attempting any data conversion operations.

You may read the project license here.

Special Thanks


No releases published


No packages published