Attention: This page is scheduled to be removed on June 30, 2014. Please refer to the Message Center in the Office 365 admin portal to stay informed about changes to your Office 365 service, including new features and actions you need to take to keep your service running smoothly.


Important

The scripts in this article are only needed if you are a Live@edu customer and you plan to use the Windows Azure Directory Sync tool after the upgrade to Office 365.

Because the Directory Sync tool maps objects from on-premises Active Directory to the cloud differently than what was possible with Outlook Live and Outlook Live Directory Sync (OLSync), we have created Windows PowerShell scripts that you can use to modify the cloud object types to match the new mapping. If you don't run these scripts prior to synchronizing using the Directory Synch tool, you may experience errors that prevent synchronization.

There are two scripts:

  • The ReadMode.ps1 script identifies objects in one organizational unit (OU) and its child organizational units in Office 365 that need to be aligned. Changes are identified and output to a .csv file. No changes are made to the cloud or on-premises directories.
  • The RemediationMode.ps1 script modifies the objects that are identified and listed in the .csv file that was created by the ReadMode.ps1 script. The script updates the object type in the cloud to match the requirements of the Directory Sync tool, and updates legacy information to the on-premises object in order to preserve mail routing.

To learn when in the upgrade process to use these scripts:

To download the scripts, go to the Cloud Directory Preparation scripts download page. For details about how OLSync synchronizes objects, see How objects are synchronized.

In this article

Objects Changed by the Scripts
System Requirements
Usage
Troubleshooting

Objects Changed by the Scripts

The Cloud Directory Preparation scripts identify and fix three areas where the mapping has changed.

Abbreviation used in .csv file Scenario Action
userToMailContact An object that is a User in on-premises Active Directory and a MailContact in Exchange Online In Exchange Online, the script replaces the MailContact object with a User object with an ExternalEmailAddress.
contactToMailUser An object that is a Contact in on-premises Active Directory and a MailUser in Exchange Online In Exchange Online, the script replaces the User object with a Contact object.
groupToMailUser An object that is a Distribution Group in on-premises Active Directory and a MailUser in Exchange Online

In Exchange Online, the script replaces the User object with a Distribution Group object.

For all members of the distribution group in Active Directory, the script sets the equivalent membership in Exchange Online using the new Distribution Group.

If there is not an equivalent member of the group in Exchange Online, or if group membership can't be set, the script logs a warning.

Note that the RemediationMode.ps1 script does not change the objects that are a Distribution Group in on-premises Active Directory and a Mail Contact in Exchange Online (groupToMailContact). These rarely occur, and if they do, you can delete the cloud object.

In order to preserve mail routing, the LegacyExchangeDN of the original Exchange object is added as an X500 entry to the proxy address of the on-premises object.

System Requirements

Operating Systems:

  • Windows Server 2003/R2 and above
  • Windows Server 2008/R2 and above

Note: These operating systems have been verified to function in English only. Other languages may have differing results and are not recommended.

Domain controller or domain-joined PC

  • Active Directory

Credentials:

  • ReadMode.ps1 must be run from an account that has sufficient permissions to read on-premises Active Directory user account data. By default, all user accounts have this permission.
  • RemediationMode.ps1 must be run from an account that has sufficient permissions to read and modify on-premises Active Directory user account data. By default, this would be an account in the Domain Admins group.

Windows PowerShell

Usage

Read Mode Script:
ReadMode.ps1

Syntax

.\ReadMode.ps1 -OutputFileName <string> -Office365AdminUserName <string> -LDAP <string>

Parameters

Parameter Description
OutputFileName Specifies the file name and path of the output .csv file to be created by the script. If no path is specified, the file is created in the folder from which you run the script.
Office365AdminUserName Specifies the user name of an Office 365 account that has permissions to read user data.
  • When you run the script, you’ll be prompted for the Office 365 account password.
LDAP Specifies the LDAP path of the organizational unit to report on in the format: “LDAP://distinguished_name”.
  • This script must be run once for each organizational unit (OU). All child organizational units under the specified OU are included automatically.
  • This parameter is case-sensitive.
  • For steps to find the LDAP path, see Troubleshooting.

Example

PS C:\DirectoryPreparationScripts> .\ReadMode.ps1 -OutputFileName .\DirectoryPreparation.csv -Office365AdminUserName admin@fineartschool.net -LDAP "LDAP://OU=Students,DC=students,DC=fineartschool,DC=net"

Comments

  • This script identifies objects in one organizational unit (OU) and any child organizational units in Office 365 that need to be aligned. Changes are identified and output to a .csv file. No changes are made to the cloud or on-premises directories.
  • Each time you run the ReadMode.ps1 script, in addition to the .csv file, a log is generated in a Logs folder under the folder in which you ran the script. The log file includes:
    • Number of Active Directory Objects
    • Number of Active Directory mail objects
    • Number of cloud mail objects (This does not include mailboxes)
    • Number of objects to remediate
    • Errors
  • This script takes approximately 10 minutes per 1000 objects to run.

Output

Review the output of the .csv file to learn what changes will be made when you run RemediationMode.ps1.

  • If the script does not encounter errors, you'll see the following four columns in the .csv file:
    Column Description
    PrimarySMTPAddress The address of the object. For example, Student1@students.contoso.edu.
    Scenario One of contactToMailUser, userToMailContact, groupToMailUser or groupToMailContact as described above in Objects changed by the scripts.
    ADObjectGUID GUID for the object in Active Directory.
    CloudObjectGUID GUID for the object in Office 365 Exchange Online.
  • If the .csv file contains those four columns, but no data, you do not need to run the RemediationMode.ps1 script.
  • If objects with duplicate names are found in the cloud directory, the .csv file will contain a list of duplicates, rather than content that can be used in remediation mode. The list will be composed of pairs, with the first row of each pair showing the original name without the CNF suffix (the new object), and the second row showing the original name with the CNF suffix (the older object).

    In this case, you’ll see two columns in the .csv:

    Column Description
    CollisionObjectGUID GUID.
    CollisionObjectDistinguishedName Active Directory distinguished name.

    You’ll need to resolve these replication conflicts and rerun the script in order to generate a .csv file that is usable with RemediationMode.ps1. For more information, see Troubleshooting.

 

Remediation Mode Script:
RemediationMode.ps1

Syntax

.\RemediationMode.ps1 -InputFileName <string> -Office365AdminUserName <string>

Parameters

Parameter Description
InputFileName Specifies the file name of the .csv file that was created as the output of ReadMode.ps1.
Office365AdminUserName Specifies the user name of an Office 365 account that has permissions to modify user data.           
  • When you run the script, you’ll be prompted for the Office 365 account password.

Example

PS C:\DirectoryPreparationScripts> .\RemediationMode.ps1 -InputFileName “.\DirectoryPreparation.csv” -Office365AdminUserName admin@fineartschool.net

Comments

  • This script modifies the objects that are identified and listed in the .csv file that was created by the ReadMode.ps1 script. The script updates the object type in the cloud to match the requirements of the Directory Synch tool, and updates legacy information to the on-premises object in order to preserve mail routing.
  • Only run this script after the current synchronization tool (OLMA or OlSync) has been disabled.
  • This script should be run twice, as the first time it generates new objects. Wait 20 minutes before running it the second time to give Active Directory time to identify any replication collisions.
  • Each time you run the Remediation.ps1 script, a log is generated in a Logs folder under the folder in which you ran the script. If errors occur, details can be found in the log file.
  • The length of time this script takes to run is based on the number of objects in the .csv file and the types of remediation required.

Troubleshooting

Determine the LDAP path for an organizational unit

To determine the LDAP path for a specific organizational unit (OU) for use with the ReadMode.ps1 script, complete the following steps.

  1. Open Active Directory Users and Computers.
  2. On the View menu, click Advanced Features.
  3. Right-click the OU, and then select Properties.
  4. Click Attribute Editor.
  5. Select DistinguishedName.
  6. Copy the value. Substitute this value for distinguished_name in “LDAP://distinguished_name” to use with the ReadMode.ps1 script.
  7. Click Cancel to close the Attribute Editor.

Resolve replication conflicts

If replication conflicts are found in the cloud directory when you run ReadMode.ps1, the .csv file will contain a list of collisions, rather than output that is ready to use with the remediation script. There will be one entry with the original name without the CNF suffix (the new object), and another one with the original name with the CNF suffix (the older object).

To fix it, you determine which of the collision objects should be deleted from the cloud directory:

  • If the object to be deleted is the one with the CNF suffix, rename that object to a temporary name, and then delete it.
  • If the object to be deleted is the one without the CNF suffix, delete that object, and rename the remaining object to remove the CNF suffix.

To delete or rename an object, use Exchange Online cmdlets with Windows Powershell. Use the correct cmdlet for the type of object.

For example, the following table shows an example of a collision between two mail users in the cloud:

CollisionObjectGUID DistinguishedName
d85d6ea1-6b29-491e-9d74-4bcbcfa6b762 CN=AnatKerry\0ACNF:d85d6ea1-6b29-491e-9d74-4bcbcfa6b762,OU=www.contoso.edu,OU=Faculty,DC=dc01,DC=dc02,DC=contoso,DC=edu
63b90c18-304a-4ee6-847a-0a7962556f10 CN=AnatKerry,OU=www.contoso.edu,OU=Faculty,DC=dc01,DC=02,DC=contosos,DC=edu

If you decided to delete the second object, and rename the first object to remove the CNF suffix, you would run the following Windows PowerShell commands:

PS C:\> Remove-MailUser -Identity "63b90c18-304a-4ee6-847a-0a7962556f10"
PS C:\> Set-MailUser -Identity "d85d6ea1-6b29-491e-9d74-4bcbcfa6b762" -Name “AnatKerry”

Work around single account issues

When you run RemediationMode.ps1, you may see an error caused by a single account. To work around this single-account issue, use the following steps which will let you finish running the Remediation Mode script and address the single-account issue later.

  1. Review the most recent log file output from the RemediationMode.ps1 script in the <ScriptRunningDirectory>\Logs folder to identify the account that caused the error.  
  2. Use Notepad or Excel to open the .csv file generated by the ReadMode.ps1 script, and remove the row for the account identified in step 1.
  3. Save the .csv file as a copy of the original.
  4. Run the RemediationMode.ps1 script with the newly created .csv file from step 3.

After the script completes, and you run the Directory Sync tool, you may experience errors related to the account you deleted from the .csv file. For help troubleshooting, see Troubleshoot Directory Synchronization.

Additional troubleshooting information

For more information, see Use Windows Powershell in Exchange Online and Reference to Available Powershell Cmdlets in Exchange Online.

For questions or problems, contact Live@edu support.