Topic Last Modified: 2009-10-01
Download and use the CSV_Parser.ps1 Windows PowerShell script to add new users, update existing users, or delete existing users in Outlook Live. The script, which uses a comma separated value (CSV) file to specify users, is a great way to create and configure many users at one time.
Note You can also create many new users with a CSV file in the Web management interface. For more information, see Import New Users with a CSV File.
Use the script for the following user types:
- Mailbox users Mailbox users are users in your Outlook Live domain that have a mailbox and a corresponding Windows Live ID.
- Mail contacts Mail contacts, also known as external contacts, don't have a Windows Live ID or a mailbox in your domain. For Outlook Live, mail contacts are users outside your organization. However, their contact information includes an e-mail address that can be displayed in your address book.
- Mail users Mail users also don't have a mailbox in your domain. However, for Outlook Live, mail users are users inside your organization, and they can have a Windows Live ID. For example, they can be users in your organization who have on-premises e-mail accounts.
For a more detailed explanation, see the following sections in this topic:
- Options for the CSV file
- Options for the CSV_Parser.ps1 script
- How do you use the CSV_Parser.ps1 script?
- Troubleshoot errors from the CSV_Parser.ps1 script
Before you begin
To learn how to install and configure Windows PowerShell and connect to Outlook Live, see Use Windows PowerShell.
You don't have to connect Windows PowerShell to Outlook Live before you run the script. The script connects to Outlook Live for you.
Download the script
Download the CSV_Parser.ps1 Windows PowerShell script here.
After you download the script file, perform the following steps:
-
Right-click the script file, and select Properties.
-
On the General tab, in the Security section that has the text "This file came from another computer and might be blocked to help protect this computer," click Unblock. If there is no Security section, don't worry about it.
-
Click OK.
Options for the CSV file
You can use any text editor, or an application like Microsoft Office Excel, to create the CSV file. Format the file as described in the "CSV file format" section of this topic and save the file with the extension ".csv".
Note: |
|---|
|
If the CSV file contains non-ASCII characters, make sure to save the CSV file with UTF-8 encoding. Depending on the application, saving the CSV file with UTF-8 encoding may be easier when the system locale of the computer matches the language used in the CSV file. Also, if you use Excel to create or modify the CSV file, don't include double quotation marks in the cell values. Excel automatically adds double quotation marks to all cell values that contain spaces when the file is saved as a CSV file. You can examine the CSV file in Notepad or another text editor to confirm that the values don't contain extra double quotation marks. |
The first row, or header row, of the CSV file lists the names of the attributes, or fields, specified on the rows that follow. Each attribute name is separated by a comma.
Each row under the header row represents an individual user and supplies the information required for the Windows Live ID and the Outlook Live mailbox and address book listing. The attributes in each individual user row must be in the same order as the attribute names in the header row. Each attribute value is separated by a comma. If the attribute value for a particular record is null, don't type anything for that attribute. However, make sure that you include the comma to separate the null value from the next attribute.
CSV file format
Here's an example of the correct format for a CSV file. In this example, two mailbox users are being provisioned: one for Tamara Johnston and one for Ayla Kol.
Action,Type,Name,EmailAddress,Password,FirstName,LastName,DisplayName Add,Mailbox,Tamara Johnston,TamaraJ@students.contoso.edu,P@ssw0rd,Tamara,Johnston,Tamara Johnston Add,Mailbox,Ayla Kol,Aylak@students.contoso.edu,P@ssw0rd,Ayla,Kol,Ayla Kol
This table lists all the supported attributes.
| Attribute name | Required/Optional | Description |
|---|---|---|
Action | Always required | Action refers to the type of procedure being performed. Valid options are:
|
Type | Always required | Type specifies the user type. Valid entries are:
|
Name | Always required | Name specifies an identifier for the user. When you create new mailbox users, the value of Name is used as the name of the Windows Live ID. The value of Name must be unique in your domain. You can't modify the value of the Name attribute on an existing user. The Name attribute is important for Windows PowerShell operations on Outlook Live users, but the value of the Name attribute isn't visible outside Windows PowerShell. The DisplayName attribute is modifiable for existing users and is visible in the Outlook Live address book. Note Make sure the value that you use for Name is unique in your Outlook Live organization. If you create two accounts with the same value of Name but different Windows Live IDs, Outlook Live will have problems properly associating the Windows Live ID with the correct mailbox. |
DisplayName |
| DisplayName specifies how the user name is displayed in the address book and in the Web management interface. If you don't specify a value for DisplayName when you create new users, the value of EmailAddress is used for DisplayName. To create the display name "Last, First", enclose the value in double quotation marks. If you use Excel to create or modify the CSV file, don't include the double quotation marks in the cell values. |
EmailAddress |
| EmailAddress specifies the e-mail address of a new user. When you create new mailbox users, the EmailAddress attribute is used as the e-mail address for the mailbox and is used to create the corresponding Windows Live ID. The value of EmailAddress must be unique in the Outlook Live organization. For mailbox users and mail users, the value of EmailAddress must be in an accepted domain of the Outlook Live organization. For mail contacts, the value of EmailAddress can't be in an accepted domain of the Outlook Live organization. You can't update the e-mail address for an existing user. For more information about accepted domains, see Accepted Domains. |
FirstName |
| FirstName specifies the first name that is listed for the user in the address book. When you create new mailbox users, the value of FirstName is also used as the first name of the Windows Live ID. |
KeepWindowsLiveID |
| KeepWindowsLiveID is only available when you delete mailboxes. When set to |
LastName |
| LastName specifies the last name that is listed for the user in the address book. When you create new mailbox users, the value of LastName as also used as the last name of the Windows Live ID. |
MailboxPlan |
| MailboxPlan is only available when you are creating new mailbox users. If you don't specify a value for MailboxPlan, the default mailbox plan for your organization is used. Typical values are DefaultMailboxPlan and GalDisabledMailboxPlan. For more information about mailbox plans, see Mailbox Plans for Outlook Live. |
Password |
| Password is the Windows Live ID password for a mailbox user. The Password attribute is required when you create new mailbox users and can be used optionally to reset an existing mailbox user's password. The Password attribute doesn't apply to mail contacts or mail users. To force a mailbox user to change their password after they log on, use the ForceChangePassword attribute. For more information about passwords, see Password Guidelines for Outlook Live. |
City |
| City specifies the city that is listed for the user in the address book. If you don’t supply this information, the City field is left blank. |
Company |
| Company specifies the company name that is listed for the user in the address book. If you don’t supply this information, the Company field is left blank. |
CountryorRegion |
| CountryorRegion specifies the ISO 3166 two-letter country code or the name of the country or region that is listed for the user in the address book. You can find the valid values for the CountryorRegion attribute in the Country / Region field in the Contact Information section of the account properties in the Web management interface for Outlook Live. |
CustomAttributeN where N is an integer from 1 through 15. |
| This parameter specifies the Custom Attribute N property where N is an integer from 1 through 15. The Custom Attribute N properties aren't visible in the Web management interface or the address book. However, you can use the Custom Attribute N values as filters in Windows PowerShell operations, such as creating dynamic distribution groups. For more information, see Dynamic Distribution Groups. |
Department |
| Department specifies the department that is listed for the user in the address book. If you don’t supply this information, the Department field is left blank. |
EmailAddressN where N is an integer from 2 through 5. |
| EmailAddressN specifies up to 4 additional e-mail addresses, known as proxy addresses for the user. For mailbox users and mail users, the proxy address must be in an accepted domain of the Outlook Live organization. For mail contacts, the proxy address can't be in an accepted domain of the Outlook Live organization. For more information about accepted domains, see Accepted Domains. |
Fax |
| Fax specifies the fax number that is listed for the user in the address book. If you don’t supply this information, the Fax field is left blank. |
ForceChangePassword |
| ForceChangePassword is available only when you are creating new mailbox users. When ForceChangePassword is set to |
HomePhone |
| HomePhone specifies the home phone number that is listed for the user in the address book. If you don’t supply this information, the Home phone field is left blank. |
Initials |
| Initials specifies the middle initial that is listed for the user in the address book. If you don’t supply this information, the Initial field is left blank. |
MobilePhone |
| MobilePhone specifies the mobile phone number that is listed for the user in the address book. If you don’t supply this information, the Mobile phone field is left blank. |
Notes |
| The Notes field specifies additional information that is listed for the user in the address book. If you don't provide any information, the Notes field is left blank. |
Office |
| Office specifies the office location that is listed for the user in the address book. If you don’t supply this information, the Office field is left blank. |
Phone |
| Phone specifies the work phone number that is listed for the user in the address book. If you don’t supply this information, the Work phone field is left blank. |
PostalCode |
| PostalCode specifies the postal code that is listed for the user in the address book. If you don’t supply this information, the Zip / Postal code field is left blank. |
StateorProvince |
| StateorProvince specifies the state or province that is listed for the user in the address book. If you don’t supply this information, the State / Province field is left blank. |
StreetAddress |
| StreetAddress specifies the street address that is listed for the user in the address book. If you don’t supply this information, the Street field is left blank. |
Title |
| Title specifies the title that is listed for the user in address book. If you don’t supply this information, the Title field is left blank. |
WebPage |
| WebPage specifies the Web page address that is listed for the user in the address book. If you don’t supply this information, the Web page field is left blank. |
Options for the CSV_Parser.ps1 script
| Parameter | Required | Description |
|---|---|---|
LiveCredential | Required | The LiveCredential parameter specifies the Windows Live ID and password of an Outlook Live administrator account in your Outlook Live domain. To specify a value for the LiveCredential parameter, store the Windows Live ID credentials in a variable before you run the |
UsersFile | Required | The UsersFile parameter specifies the name and location of the |
EndRow | Optional | The EndRow parameter specifies the last data row of the CSV file to act upon. The default value is 1000000. If you don't specify a value, the script will act on all data rows in the CSV file until the end is reached. The header row that contains the column definitions isn't included in the count of data rows in the CSV file. |
LogDirectory | Optional | The LogDirectory parameter specifies the location of the log files that are generated by the script. The name of a log file is CSV_Parser_<monthdateyear_time>.txt This file contains useful troubleshooting information. If you don't specify a value for LogDirectory, the log file is stored in the directory that is specified by the %TEMP% environment variable in your Windows profile. By default, the temporary directory is located at C:\Users\<username>\AppData\Local\Temp. If you specify a different log directory, make sure the specified directory exists, and make sure you have sufficient permissions to read and create files in that directory. |
LogVerbose | Optional | The LogVerbose parameter enables detailed debug logging for advanced troubleshooting purposes. If you specify the LogVerbose parameter, detailed debug logging is enabled. |
RemoteURL | Optional | The RemoteURL parameter specifies the URL that connects your local Windows PowerShell console to the remote Outlook Live service. You don't have to use this parameter. The script will automatically connect to the correct datacenter. The only acceptable value for this parameter is |
StartRow | Optional | The StartRow parameter specifies the beginning data row of the CSV file to act upon. The default value is 1. If you don't specify a value, the script will start on the first data row in the CSV. The header row that contains the column definitions isn’t included in the count of data rows in the CSV file. |
ValidateAction | Optional | The ValidateAction parameter enables or disables validation. The default value is |
$WarningPreference | Not applicable | $WarningPreference controls the error handling for the script. You set the value for $WarningPreference by modifying the value in the
The default value is |
How do you use the CSV_Parser.ps1 script?
Here's an example that shows how to use the CSV_Parser.ps1 script with the following details:
- Path to CSV_Parser.ps1 script C:\Tools\CSV_Parser.ps1
- CSV file name and path C:\Data\Bulk Import.csv
To use the CSV_Parser.ps1 script to import users that are defined in the "C:\Data\Bulk Import.csv" file
-
Click Start > All Programs > Accessories> Windows PowerShell > Windows PowerShell.
-
Run the following command:
-
In the Windows PowerShell Credential Request window that opens, type the Windows Live ID and password of an Outlook Live administrator account. When you're finished, click OK.
-
Run the following command:
-
Depending on the number of users and attributes that are defined in the CSV file, the script may take some time to run. Various messages and errors may be displayed. When the script is finished, you can view these messages in the log file named CSV_Parser_<monthdateyear_time>.txt. By default the log file is located at C:\Users\<user name>\AppData\Local\Temp\, but you can specify the log file location with the LogDirectory parameter.
Troubleshoot the CSV_Parser.ps1 script
If you have difficulty running the script, or the script doesn't produce the results that you expected, try the following troubleshooting steps:
-
Verify that the structure and content of your CSV file is correct. To do this, refer to the
test.csvfile that is included with theCSV_Parser.ps1script.-
The following attributes are always required: Action, Type, Name.
-
The EmailAddress attribute is required for Add and Update actions.
-
The Password attribute is required for Add actions on mailbox users.
-
The following attributes are always required: Action, Type, Name.
-
Make sure you are running the latest version of the script. The script has an automatic version check that runs every time you run the script. If you are using an outdated version of the script, you'll receive an error message similar to the following:
Error = This script version <version> is no longer supported. Please update to the latest version. -
If the
CSV_Parser.ps1script has problems connecting to Outlook Live, try connecting to Outlook Live manually without using the script. For more information about how to connect Windows PowerShell to Outlook Live with Windows Remote Management (WinRM), see Connect Windows PowerShell to Outlook Live. -
Check the log file. By default, the log files are located at C:\Users\<user name>\AppData\Local\Temp, but you can change the location with the LogDirectory parameter. The log files are named CSV_Parser_<monthdateyear_time>.txt.
Note: