Create and Configure Recipients with the CSV_Parser.ps1 script in Live@edu

 

Applies to: Live@edu

Topic Last Modified: 2013-01-10

 

Download and use the CSV_Parser.ps1 Windows PowerShell script to add new users, update existing users, or delete existing users. 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 Exchange Control Panel. For more information, see Import New Exchange Online Users with a CSV File.

Use the script for the following user types:

  • Mailbox users   Mailbox users are users in your cloud-based domain that have a mailbox and a corresponding Microsoft ID.

  • Mail contacts   Mail contacts, also known as external contacts, don't have a Microsoft ID or a mailbox in your domain. For the cloud-based service, 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 the cloud-based service, mail users are users inside your organization, and they can have a Microsoft 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:

Before you begin

To learn how to install and configure Windows PowerShell and connect to the service, see Use Windows PowerShell in Exchange Online.

You don't have to connect Windows PowerShell to the cloud-based service before you run the script. The script connects for you.

Download the script

Download the CSV_Parser.ps1 Windows PowerShell script here.

After you download the script file, perform the following steps:

  1. Right-click the script file, and select Properties.

  2. 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.

  3. 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".

noteNote:
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 Microsoft ID and the cloud-based 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
Important attributes for the CSV file

This table lists the important attributes used in the CSV file. Many of these attributes are always required.

 

Attribute name Required/Optional Description

Action

Always required

Action refers to the type of procedure being performed. Valid options are:

  • Add   This value creates new users in your domain. If you attempt an Add action, and the Name attribute and the Type attribute that you specify matches the Name attribute and Type attribute of an existing user, the CSV_parser.ps1 script automatically converts the Add action to an Update action on the existing user. If the Name attributes match, but the Type attributes are different, the Add action fails.

    If you attempt an Add action to create mailbox users or mail users, you may accidentally specify an unmanaged Microsoft ID, and the Add action will fail. An unmanaged ID, also called an e-mail as sign-in ID (EASI ID) is a Microsoft ID created by a user before you enrolled your domain in the cloud-based service. You can use the ImportLiveID or EvictLiveID attributes to create the user. For more information about unmanaged Microsoft IDs, see Import or Evict Existing Microsoft IDs in Live@edu.

  • Update   This value updates existing users in your domain.

    Caution   If you define an attribute in the header row, but specify a null value for the attribute for the user in an Update action, the existing value of the attribute is removed from the user.

  • Delete   This value deletes existing users from your domain. By default, the mailbox and the associated Microsoft ID are removed from use. This removes the user's access to all data associated with the Microsoft ID, such as Xbox Live points and Zune points, and data on Windows Live Spaces, Windows Live Groups, and Windows Live SkyDrive. You can keep the Microsoft ID using the KeepWindowsLiveID attribute.

  • PasswordReset   This value resets the password for an existing user. When you use this action, the only attributes that you specify are Name and Password. All other attributes are ignored.

Important   Avoid combining Add actions and Update actions in the same CSV file. And remember: if you define an attribute in the header row but specify a null value for the attribute for the user in an Update action, the existing value of the attribute is removed from the user.

Type

Always required

Type specifies the user type. Valid entries are:

  • Mailbox   This value specifies mailbox users in your domain that have a mailbox and a corresponding Microsoft ID.

  • MailContact   This value specifies a mail contact, a user outside your domain that doesn't have a Microsoft ID or a mailbox in your domain, but can receive e-mail messages at an external e-mail address. The e-mail address can't be in an accepted domain of the cloud-based organization. Mail contacts are also known as external contacts.

  • MailUser   This value specifies a mail user, a user that doesn't have a mailbox in your domain. The e-mail address must exist in an accepted domain of the cloud-based organization. Use MailUser for members of your organization who don't have a cloud-based mailbox. For example, use MailUser for the faculty and staff of a university where only the students and alumni have cloud-based mailboxes.

    The CSV_Parser.ps1 script creates mail users with a Microsoft ID. You can create a mail user without a Microsoft ID by using the New-MailUser cmdlet. For more information, see Create Mail Users.

Name

Always required

Name specifies an identifier for the user. When you create new mailbox users or mail users, the value of Name is used as the name of the Microsoft ID. The value of Name must be unique in your domain. The Name attribute is important for Windows  PowerShell operations on cloud-based 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 shared address book.

Note   Make sure the value that you use for Name is unique in your cloud-based organization. If you create two accounts with the same value of Name but different Microsoft IDs, there may be problems properly associating the Microsoft ID with the correct mailbox.

DisplayName

  • Optional for Add and Update actions

  • Not used with Delete actions

DisplayName specifies how the user name is displayed in the address book and in the Exchange Control Panel. 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.

FirstName

  • Optional for Add and Update actions

  • Not used with Delete actions

FirstName specifies the first name that is listed for the user in the address book. When you create new mailbox users or mail users, the value of FirstName is also used as the first name of the Microsoft ID.

LastName

  • Optional for Add and Update actions

  • Not used with Delete actions

LastName specifies the last name that is listed for the user in the address book. When you create new mailbox users or mail users, the value of LastName as also used as the last name of the Microsoft ID.

EmailAddress or WindowsLiveID

  • Required for Add and Update actions

  • Not used with Delete actions

EmailAddress and WindowsLiveID are interchangeable. Don't use EmailAddress and WindowsLiveID in the same CSV file.

EmailAddress specifies the e-mail address of a new user. When you create new mailbox users or mail users, the EmailAddress attribute is used as the primary e-mail address and is used to create the corresponding Microsoft ID. The value of EmailAddress must be unique in the cloud-based organization.

For mailbox users and mail users, the value of EmailAddress must be in an accepted domain of the cloud-based organization. For mail contacts, the value of EmailAddress can't be in an accepted domain of the cloud-based organization.

You can't use the CSV_Parser.ps1 script to update the primary e-mail address or Microsoft ID for an existing user.

FederatedIdentity

  • Required for Add actions on mailbox users and mail users in federated domains

  • Not used with Update or Delete actions

FederatedIdentity is used in federated domains to associate an on-premises account with a cloud-based mailbox or mail user.

EmailAddressN where N is an integer from 2 through 5.

  • Optional for Update actions

  • Not used with Add or Delete actions

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 cloud-based organization. For mail contacts, the proxy address can't be in an accepted domain of the cloud-based organization.

Password

  • Required for Add actions on mailbox users and mail users

  • Optional for Update actions on mailbox users

  • Not used with Delete actions

Password is the Microsoft ID password for a mailbox user or mail user. The Password attribute is required when you create new mailbox users or mail users, and can be used optionally to reset an existing mailbox user's password.

To force a user to change their password after they log on, use the ForceChangePassword attribute.

For more information about passwords, see Password Guidelines.

ForceChangePassword or ResetPasswordOnNextLogon

  • Optional for Add and Update actions on mailbox users

  • Not used with Delete actions

ForceChangePassword and ResetPasswordOnNextLogon are interchangeable. Don't use ForceChangePassword and ResetPasswordOnNextLogon in the same CSV file.

ForceChangePassword is available only in the CSV_parser.ps1 script when you are creating or updating mailbox users. When ForceChangePassword is set to 1, or if the ForceChangePassword attribute isn't defined in the header row, new users must change their password after they log on for the first time. When ForceChangePassword is set to 0, new users aren't required to change their password after they log on for the first time.

MailboxPlan

  • Optional for Add actions on mailbox users

  • Not used with Update or Delete actions

MailboxPlan is only available in the CSV_parser.ps1 script 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.

EvictLiveID

  • Optional for Add actions on mailboxes and mail users

  • Not used with Update or Delete actions

EvictLiveID is only available when you create mailboxes or mail users. Use this attribute to create the user in the event you encounter an EASI ID that matches the e-mail address of the new user you're trying to create.

When set to Y, the Microsoft ID and all its existing settings, including the password, are preserved. However, the Microsoft ID is removed from your cloud-based domain and placed in a forced rename state. For more information, see Import or Evict Existing Microsoft IDs in Live@edu.

When you evict the Microsoft ID from your domain, you can create a new Microsoft ID with the same name, but the password must be different than the password of the evicted Microsoft ID.

If an EASI ID is encountered during an Add action, and you didn't specify an EvictLiveID or ImportLiveID value of Y, the Add action will fail for that user.

ImportLiveID

  • Optional for Add actions on mailbox users and mail users

  • Not used with Update or Delete actions

ImportLiveID is only available when you create mailboxes or mail users. Use this attribute to create a user in the event you encounter an EASI ID that matches the e-mail address of the new user you're trying to create.

Note   ImportLiveID isn't supported in federated domains.

When set to Y, the Microsoft ID and all of its existing settings, including the password, are preserved, and it's associated with the new mailbox or mail user that you create in your domain. For more information, see Import or Evict Existing Microsoft IDs in Live@edu.

After you import the Microsoft ID into your cloud-based organization, you can't evict the Microsoft ID. Generally, we recommend that you don't import EASI IDs into your cloud-based organization. Also, if you import the Microsoft ID into your cloud-based organization, the value of Password is ignored.

If an EASI ID is encountered during an Add action, and you didn't specify an EvictLiveID or ImportLiveID value of Y, the Add action will fail for that user.

KeepWindowsLiveID

  • Optional for Delete actions on mailbox users and mail users

  • Not used with Add or Update actions

KeepWindowsLiveID is only available when you delete mailboxes or mail users. When set to Y, the Microsoft ID that is associated with the deleted user is preserved. The user can still access all data that's associated with their Microsoft ID, such as Xbox Live points and Zune points, and data on Windows Live Spaces, Windows Live Groups, and Windows Live SkyDrive.

If the value of KeepWindowsLiveID isn't Y, the Microsoft ID of the removed mailbox is removed from use. The user loses access to all data associated with their Microsoft ID. However, you can typically recover a deleted mailbox and the associated Microsoft ID within 30 days. For more information, see Recover a Deleted Mailbox in Live@edu.

Note   In federated domains, the Microsoft ID is always preserved, so you don't need to use the KeepWindowsLiveID attribute.

Top of page

Optional attributes for the CSV file

This table lists optional attributes you can use in the CSV file. If you don’t supply values for these attributes, they are left blank. None of these attributes are used with Delete actions.

 

Attribute name Description

City

City specifies the city that is listed for the user in the address book.

Company

Company specifies the company name that is listed for the user in the address book.

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 Exchange Control Panel.

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 Exchange Control Panel 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.

Fax

Fax specifies the fax number that is listed for the user in the address book.

HomePhone

HomePhone specifies the home phone number that is listed for the user in the address book.

Initials

Initials specifies the middle initial that is listed for the user in the address book.

MobilePhone

MobilePhone specifies the mobile phone number that is listed for the user in the address book.

Notes

The Notes field specifies additional information that is listed for the user in the address book.

Office

Office specifies the office location that is listed for the user in the address book.

Phone

Phone specifies the work phone number that is listed for the user in the address book.

PostalCode

PostalCode specifies the postal code that is listed for the user in the address book.

StateorProvince

StateorProvince specifies the state or province that is listed for the user in the address book.

StreetAddress

StreetAddress specifies the street address that is listed for the user in the address book.

Title

Title specifies the title that is listed for the user in address book.

WebPage

WebPage specifies the Web page address that is listed for the user in the address book.

Top of page

Options for the CSV_Parser.ps1 script

 

Parameter Required Description

LiveCredential

Required

The LiveCredential parameter specifies the Microsoft ID and password of an Exchange Online administrator account in your cloud-based domain. To specify a value for the LiveCredential parameter, store the Microsoft ID credentials in a variable before you run the CSV_Parser.ps1 script, for example, $LiveCred = Get-Credential.

UsersFile

Required

The UsersFile parameter specifies the name and location of the CSV_Parser.ps1 script. If you use a value that contains spaces, make sure that you enclose the whole value in double quotation marks.

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 cloud-based 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 https://ps.outlook.com/powershell/.

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 $true, which means all actions performed by the CSV_Parser.ps1 script are validated. Validation requires several seconds per object. If you are certain the actions you are performing with the CSV_Parser.ps1 script don't require validation, you can disable validation by setting the value to $false.

$WarningPreference

Not applicable

$WarningPreference controls the error handling for the script. You set the value for $WarningPreference by modifying the value in the CSV_Parser.ps1 script. The possible values are SlientlyContinue, Continue, Inquire, Suspend, or Stop.

  • SilentlyContinue   If an error is encountered, the script continues without displaying the error.

  • Continue   If an error is encountered, the error is displayed and the script continues.

  • Inquire   If an error is encountered, the script pauses and you are forced to choose whether to continue, halt, or suspend the script.

  • Stop   If an error is encountered, the script stops.

The default value is SilentlyContinue.

Top of page

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

  1. Navigate to Start > All Programs > Accessories> Windows PowerShell > Windows PowerShell.

  2. Run the following command:

    $LiveCred = Get-Credential
    
  3. In the Windows PowerShell Credential Request window that opens, type the Microsoft ID and password of an Exchange Online administrator account. When you're finished, click OK.

  4. Run the following command:

    C:\Tools\CSV_Parser.ps1 -LiveCredential $LiveCred -UsersFile "C:\Data\Bulk Import.csv"
    
  5. 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.

Top of page

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.csv file that is included with the CSV_Parser.ps1 script.

    • The following attributes are always required: Action, Type, and Name.

    • The EmailAddress attribute is required for Add and Update actions.

    • The Password attribute is required for Add actions on mailbox users and mail users.

  • 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.ps1 script has problems connecting to the cloud-based service, try connecting manually without using the script. For more information about how to connect Windows PowerShell to the cloud-based service, see Connect Windows PowerShell to the Service.

  • 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.

Top of page

Unsupported attributes

The following attributes aren’t supported by the CSV_Parser.ps1 script:

  • ExtensionCustomAttribute1 – ExtensionCustomAttribute5

Top of page

 
Related help topics
Loading...
No resources were found.