When the ShareGate migration tool copies list items, there is no implicit way to know if the item that is being copied already exists in the destination of your migration, so it uses key properties to avoid overwriting items.
Note: Key properties can only be changed on a list. Library migrations rely on the file name which is always unique to each document.
You can set the ShareGate migration tool to handle already existing content in different ways. For instance, you can copy and replace existing items at the destination, and you can copy only newer items (incremental copy).
These actions require the application to determine what items are matching between the source and the destination.
To do so, the ShareGate migration tool relies on the properties Title and Created since they are default properties and usually offer a unique value on every list item.
Note: Calendar items have key properties as well, but they are different than those of list items. These properties are Created, Recurrence, Start time, and Title.
When should you change key properties?
You will have to select new key properties if you're dealing with one of the examples below:
- Multiple list items have the same values in the Created and Title fields. For example, some lists will not use Title, and something like a workflow operation can leave multiple items with the same Created value.
- The key properties were set on other properties that don't have a unique value for each list item.
Note: your list item IDs cannot be used as a key property because they are not always preserved in the destination list.
How-to change your key properties
Properties included in the unique key are indicated by a solid key under Mappings of the Copy content only migration screen.
- Select Copy from the menu.
- Select Copy content only and connect to a source and a destination.
- Click Mappings on the top-right.
- Select the Properties tab.
- Select the empty key next to the properties that you want to use as a Key property. Select the solid key next to the properties that you do not want to use as a Key property.
- Click Save.