Views: 1058 (Data available since 06.02.2017)
Last Modified: 15.06.2015
Important! If the system uses the UTF-8 encoding, a CSV file must be created in this encoding as well.

Preparing a CSV File

A valid CSV file must exist before you import users from it. The file must have the following format:

header
data
data
data

Each line in the file represents a table row. A header can include any records in a single line. The header describes the data that follows it. The values in each line (the header and the data) are separated by a delimiter.

Example of user data header

LAST_NAME;PERSONAL_PHOTO;NAME;SECOND_NAME;WORK_POSITION;EMAIL;PERSONAL_BIRTHDAY;PERSONAL_GENDER;WORK_PHONE;UF_1C_PHONE_INNER;PERSONAL_MOBILE;PERSONAL_ICQ;LOGIN;IBLOCK_SECTION_NAME_1;IBLOCK_SECTION_NAME_2;IBLOCK_SECTION_NAME_3;IBLOCK_SECTION_NAME_4

The data in fields must match the format prescribed by the header. The field must exist no matter whether it is empty or not; essentially it means that, if there is no data for a field, the separator must exist (e.g. “;;”).

For example: if the file header has the following format:

LAST_NAME;PERSONAL_PHOTO;NAME;SECOND_NAME;WORK_POSITION;

and there is no data for some fields, say 2, 4 and 5, the data row must still be like the following:

Brown;;Andrew;;

Consider the following aspects when formatting a CSV file:

  • Any delimiter character is allowed: comma (,), semicolon (;), space or tab. No spaces can exist between the values. If a delimiter is a space, make sure no double spaces have been added between the values.
  • If a comma is the part of a value (for example, if the object properties are comma-separated), enclose the value in quotes ("yellow,red,green").
  • If double quotes are the part of a value, enclose the value in double quotes. For example: "John" in a CSV file must look as ""John"".
  • Empty rows in a CSV file are not allowed.
  • The headers, string values, and logins are case insensitive.
  • Passwords are case sensitive.
  • Boolean values can be presented as: Y ­- true; N - false.
  • Any excessive data existing after the last identified field are ignored. For example, if a file header specifies 10 values while the row contains 12 values, the last two values will be ignored.
  • Empty data fields are processed as empty strings.
  • The time and date format must be set in the format of the site language. For example: MM/DD/YYYY HH:MI:SS for English.

Exporting Users from Bitrix Framework

To export users, do the following.

  • Open Settings > Manage users > User list.
  • Click Excel to download data.
  • After downloading, edit the file to conform the CSV format requirements:
    • delete the export summary information at the end of the file;
    • if required, change the field names in the file header with the correct ones (see the Data types table below);
    • check if the fields are filled correctly (see the Data types table below).

Data Types

The table contains all the data types that may encounter in a CSV file.

Value Type Required Comments
ACTIVE boolean No. Default is True. Active.
LOGIN string No. Auto generated by default. Specifies a user login, min. 3 characters.
PASSWORD string No. Auto generated by default. Specifies a user password, min. 6 characters.
NAMEstring Yes User’s first name.
LAST_NAME string Yes User’s last name.
SECOND_NAME string No User’s second name.
EMAIL string No. Default value is the administrator’s e-mail. The E-mail address.
DATE_REGISTER dateNo. Default is the current date. The date a user was registered.
LID string No The ID of a default site for notifications.
ADMIN_NOTES string No Administrator’s notes.
EXTERNAL_AUTH_IDstring No The external authorization source ID.
XML_ID string No The user ID for external connection (e.g. ID in an external database).
Personal data Type Required Comments
PERSONAL_GENDER string No Gender: M – male; F – female.
PERSONAL_BIRTHDAY date No Date of birth.
PERSONAL_CITY string NoAddress: city.
PERSONAL_STATE string NoAddress: region, state etc.
PERSONAL_ZIP string NoAddress: ZIP code.
PERSONAL_WWW string NoPersonal web site URL.
PERSONAL_PROFESSIONstring NoProfession.
PERSONAL_NOTES string NoArbitrary notes.
PERSONAL_ICQ string NoICQ account number.
PERSONAL_PHONE string NoHome phone.
PERSONAL_PHOTO string NoThe path to a photo relative to a folder specified in the import parameters.
PERSONAL_FAX string NoFax number.
PERSONAL_MOBILE string NoMobile phone number.
PERSONAL_PAGER string NoPager.
PERSONAL_STREET string NoAddress: street.
PERSONAL_MAILBOX string NoAddress: P/O box.
Work data Type Required Comments
WORK_COMPANY string NoCompany name.
WORK_DEPARTMENT string NoDepartment.
WORK_POSITION string NoPosition.
WORK_WWWstring NoCompany web site URL.
WORK_PHONEstring NoWork phone.
WORK_FAXstring NoWork fax number.
WORK_PAGERstring NoPager.
WORK_STREETstring NoCompany address: street.
WORK_MAILBOXstring NoCompany address: P/O box.
WORK_CITY string NoCompany address: city.
WORK_STATE string NoCompany address: region, state etc.
WORK_ZIP string NoCompany address: ZIP code.
WORK_PROFILE string NoCompany profile.
WORK_LOGO string NoThe path to a company logo image relative to a folder specified in the import parameters.
WORK_NOTESstring NoArbitrary notes.
UF_*string NoUser field.
IBLOCK_SECTION_NAME_* string NoInformation block binding.

Notes:

The UF_* values are user properties created by the administrator. The properties must be created before importing users.

The IBLOCK_SECTION_NAME_* values indicate the information block binding. 5 nesting levels are possible.

Important! The name (NAME) and the last name (LAST_NAME) are the only required fields to import users from a CSV file.

Example of a CSV file:

LAST_NAME,NAME,LOGIN,PASSWORD,EMAIL
Silver,John,jsilver,Password1,jsilver@company.com
Smith,Andrew,asmith,Password2,asmith@company.com
Siskin,Peter,psiskin,Password3,psiskin@company.com
Oldfield,Ben,boldfield,Password4,boldfield@company.com
Baddeley,Jane,jbaddeley,Password5,jbaddeley@company.com
Bloodsworth,Helen,hbloodsworth,81QE1RO98M,hbloodsworth@company.com
Coleman,Kate,kcoleman,D0O4IAYOX0,kcoleman@company.com
Gabbard,Michael,mgabbard,CDUEND3SMX,mgabbard@company.com
Laycock,Harry,hlaycock,GCH425XAM6,hlaycock@company.com
Stockdale,Hamilton,hstockdale,ZD3PZHP2E7,hstockdale@company.com

To make sure you will not encounter any errors during import, check that the file data meet the specification described at the beginning of this chapter. You can check this by opening a CSV file in MS Excel:

  • Check the headers.
  • Ensure the length of all passwords is at least 6 symbols.
  • Ensure the length of all logins is at least 3 symbols.
Note! The system will always successfully import CSV files created in MS Excel. If you created a CSV file in some other application, open and check it in MS Excel.

After you have verified the CSV file, you can import it.

The Import Procedure

In the Import users form, select CSV file as a data source and click Next.

Fill in the fields in the next tab (Import Settings):

Click on image to enlarge

  • Data File – specify the pathname of the CSV file.
  • Field Separator – specify the separator character used in the file.
  • Add Users to Groups – select the group (or groups using Ctrl key) to which to add the user profiles.
  • Path to Images Relative to Site Root – the path to an image file folder relative to which the values of PERSONAL_PHOTO and WORK_LOGO are expected in the file.
  • Bind Users to Information Block Sections – select an information block to which users having the IBLOCK_SECTION_NAME_* property will be added.

    Note: only one information block can be specified. If a user is to be added to many information blocks, you will have to do it manually after import.
  • Allow LDAP authorization – specify the LDAP authorization server name. You can create a server now by clicking Create if required.

Click Next. The next step imports users. Upon completion, a message indicating the number of imported users will be shown.

Viewing Imported Data

To view the imported data, open Settings > Manage users > User list showing all the users registered in the system.

If the import procedure failed for some reason, delete all the records that have succeeded to import, correct the CSV file and perform the above actions again.



Courses developed by «Bitrix», Inc.