Articles in this section

See more

List item IDs

Updated

Details

List item IDs are preserved only when using the ShareGate migration tool's Insane mode for Microsoft 365, as this uses Microsoft's new migration API, which allows these values to be set in a new list.

List item IDs will not be preserved in migrations performed without Insane mode enabled or when migrating with Insane Mode to an On-Premises destination.

These two scenarios use the regular SharePoint API, automatically assigning List Item ID values. Preserving the List Item IDs for any version of SharePoint using this API would require that we manipulate the content database directly, voiding your SharePoint warranty. Due to this, and the unavailable database in Microsoft 365, List Item IDs cannot be supported outside Insane Mode or to an On-Premises destination.

Note: If you delete an item from your Microsoft 365 destination list, another item will not reuse its ID. For example, if you delete a list item with ID 2 at the destination, then migrate new items with Copy content only in Insane mode, a source item with the same ID (2) will not be able to have that same ID at the destination. The workaround in these cases is to use Copy structure and content instead.

Workaround

Disclaimer: The following workaround is provided as-is, without any warranty or support. It has not been tested for all scenarios, so it may not work in all cases. If this workaround fails, we can't provide an alternative solution.

Should you wish to attempt to preserve list item IDs without using the Microsoft 365 migration API, the following workaround is offered as an alternative:

Note: The following procedure will allow you to preserve list item IDs. However, it involves some manual steps and will not preserve permissions, version history, and attachments.

  1. Ensure the ShareGate migration tool's performance options are set to Minimal (this will ensure a single thread so that the IDs are copied sequentially. If another setting is set, it might not work because of multi-threading).
  2. Create a new list in your destination (ensure it never had any items created in it, an empty list that used to have items that were deleted will not work).
  3. Copy items (in any order) into your destination list until you have items with the same ID numbers as at the source (even if the wrong items have the wrong IDs). For example, if you have IDs 1 to 100 in your source list, make sure you have items with IDs 1 to 100 in your destination list.
  4. If there are gaps in IDs at the source (for example, no item with ID 30), you will need to delete the items in the destination to have the same gaps (so, in my example, delete the item with ID 30).
  5. In the ShareGate migration tool, drill down to your source list and click on Bulk edit content.
  6. Select all the items and click Export metadata. 
  7. Save it in your preferred location. 
  8. In the ShareGate migration tool, drill down to your destination list and click on Bulk edit content.
  9. Select Import and Edit. 
This will re-assign all the correct values to items pre-created with the proper IDs, achieving the same result as copying while preserving IDs.
 
If you are using your List Item IDs for a workflow, the following workaround is offered as an alternative:
  1. Create a new column (single line of text) called Old ID (or another preferred name) in the destination list.
  2. Map the ID column from the source to that new Old ID column through the map properties option.
  3. Set the workflow to use that column instead.

Related articles