Update migration-api-overview.md

resubmitting updates from previous PR March 29th that didn't go live.  Adding section Entering user identifiers in UseGroup.xml

Author: JoanneHendrickson

docs/apis/migration-api-overview.md

@@ -492,6 +492,54 @@ The import pipeline is using Azure Blob Storage security model as is. This means
 ### Events and event handlers
 
 The import pipeline allows event handlers to be referenced on list items but doesn’t allow defining event handlers at the list level at this time. The import pipeline does not fire events as items are imported, so existing event handlers will not fire due to the import event.
+### Entering user identifiers in UserGroup.XML
+
+Follow these guidelines when generating the **UserGroup.XML** in the submitted package:
+
+- A person can be identified only once in a single package
+- The 'login' attribute of the user identifier requires a UPN. **Do not** enter a non-UPN email address.
+
+
+>[!Important]
+> As of March 2, 2022, the Migration API now validates and enforces a maximum of one identifier per user in a single package. 
+>
+>While using a non-UPN email won't result in a failed job, it may bring unexpected results in SharePoint Online.
+
+**Examples**
+
+The following examples show the correct and incorrect ways of entering the user identifier in UserGroup.XML.
+
+In this case, the user has the following identifiers:
+
+- **UPN**: [email protected]
+- **Email**: [email protected]. 
+
+
+**Correct**
+
+- In this example, the user is entered only once, using a UPN email address.
+
+```xml
+<User Id="1" Login="i:0#.f|membership|[email protected]" …/>
+
+```
+
+**Incorrect**
+
+- **Example 1:** This example uses a non-UPN email address and incorrectly includes more than identifier for a single user.
+
+```xml
+
+<User Id="1" Login="i:0#.f|membership|[email protected]" …/>
+<User Id="2" Login="i:0#.f|membership|[email protected]" …/>
+
+```
+
+- **Example 2:** This example incorrectly uses a non-UPN email address.
+
+```xml
+
+<User Id="2" Login="i:0#.f|membership|[email protected]" …/>
 
 ### Resolving Users