Bulk Import

Bulk Import creates many user accounts in a single operation using a CSV file. It is intended for large account migrations or situations where creating users individually would be slow or error-prone. During the import process you can assign authentication methods, group membership or partner assignments, folder permissions, and SFTP/SSH public keys while creating each user.

Bulk Import is commonly used when migrating accounts from a legacy system while preserving existing credentials, or when onboarding many users at once. If your organization uses Single Sign-On with automated provisioning, use SCIM or Just-in-Time provisioning instead so that users are created automatically when they authenticate.

Bulk Import is available only in the web interface. Files.com validates the file and shows warnings and errors before it creates any users.

Alternatives to Bulk Import

When onboarding external organizations or partner companies, consider using Partners instead of importing partner users directly. Partner management lets you delegate user lifecycle management safely to partner administrators.

When only a small number of users are required or when each user requires significantly different configuration, creating users individually is usually simpler than preparing a CSV file.

CSV File Format

Bulk Import uses a CSV (Comma-Separated Values) file to describe the users to create. In the web interface, you can download the CSV template from the Bulk Create Users page.

Each CSV file contains a single header row followed by one data row per user. The header row defines which columns appear in the file, and every data row must follow the same column order. Each data row represents a single user account.

The username column must always be present. Columns that are left blank or omitted use default values, and blank rows are ignored during import.

Bulk Import reads only supported column names. Unrecognized columns are ignored and reported during validation.

Comment lines (# comment) are not supported. Do not include them in your CSV.

During import, Files.com analyzes the CSV file before creating any accounts. This validation step checks the file structure and user records before any changes are made to the site.

Password Policy and Imported Hashes

When importing users with the authentication method of password_with_imported_hash, the value in the password column must contain a supported password hash. Imported hashes bypass the site's password policy validation because the plaintext password is not available during migration.

Files.com verifies the hash during the user's first successful login. After verification, the password is converted to Files.com's internal storage format (PBKDF2).

If the user later changes their password, the new password must satisfy the site's password policy.

Plaintext passwords provided during import must always meet the site's password policy.

Supported CSV Columns

The table below lists the supported columns that may appear in a Bulk Import CSV file. The web interface also displays a listing of Supported Columns, including the allowed values.

SSO Providers Authentication Methods

Assign new users to an SSO Provider configured for your site by providing the corresponding authentication_method value. Only SSO Providers already configured for your site are valid values.

Supported SSO Provider Values

Use these values in the authentication_method column. The web interface lists the valid options for the authentication_method, including your active SSO providers, in the Supported Columns listing.

Multiple SSO Providers of the Same Type

Bulk Import matches an SSO provider by the authentication_method value, not by a provider name or display name.

When your site has multiple instances of the same SSO provider enabled with the same authentication_method value, Bulk Import cannot choose a specific provider for a specific user. Bulk Import assigns the user to the first matching provider of the specified type.

To create users assigned to different providers of the same type, create the users without SSO during Bulk Import, then assign each user to the intended SSO provider after the import.

Importing Partner Users

The partner_id column of the CSV allows you to assign the newly created user to a Partner as a partner user. You can enter either the name or the ID of the Partner in the column.

Partner users have unique restrictions, so the partner_id column is not compatible with group_ids, site_admin, or folder_permissions.

Partner users can never be part of a group, so a record that includes values in the group_ids column and in the partner_id column cannot be imported.

Similarly, Partner users can never be Site Administrators. Site Administrators have unrestricted access to your entire site, and Partner users only have the folder permissions granted to their Partner. Attempting to import a user record that includes a partner_id value and sets the site_admin column to Y will fail.

All folder permissions for Partner users are assigned to the Partner rather than the user, so values in the folder_permissions column are ignored when the partner_id column is used. Unlike the group_ids and site_admin conflicts, which prevent the record from being imported at all, this does not cause an error; the user is created successfully as a Partner user and the folder_permissions value is silently ignored.

Assigning Folder Permissions

Automatically assign folder permissions to users with the folder_permissions column of the import file. Supply a list of folders and permissions, separated by pipe symbols, to be assigned to the user (see example). Folders that don't already exist are automatically created when the user is added.

If you omit the folder_permissions column or leave it blank for a user, Bulk Import creates the user without any user-level folder permissions.

That user can authenticate, but cannot access any folders or files unless at least 1 of the following is true:

• site_admin is Y. Site Administrators have access to every path in the site.
• You are creating a Partner user by filling in the partner_id column. Partner users always have the permissions granted to their Partner, and cannot have folder permissions assigned to the user directly.
• You enabled Automatically Create New User Folders Here When Users Are Created. That setting grants access to the created folder.
• You use Group Level Permissions, and you assign the user to groups with folder access via group_ids.

Possible Permission Values

Use the permission values from the table below to limit what actions the user can take for each folder.

Example Folder Permissions

Sales=readonly|Engineering=readwrite,history|Home/Adam=admin

This defines 3 permissions: Sales=readonly, Engineering=readwrite,history and Home/Adam=admin. The user will be given Read-Only permission on the Sales folder, Read/Write and History permissions on the Engineering folder, and Admin permission on the Home/Adam folder. If any of those folders do not exist, they are created automatically.

Advanced Usage Notes

Use a slash for the folder name to specify the Root Folder, for example: /=readonly.

If a folder name contains a vertical bar, for example Sales|North-America, the vertical bar must be escaped with a preceding backslash: Sales\|North-America=readonly.

When site_admin is enabled for the user, then the value of folder_permissions for that user is ignored, because site administrators have admin access to all folders.

Folder permissions are applied recursively to all sub-folders by default. To limit a permission to the specified folder name and not its sub-folders, add an asterisk * after the permission value. For example, supplying Home=admin* creates a non-recursive folder admin permission for the "Home" folder.

Import Validation

Before creating any users, Files.com validates the uploaded CSV file. The validation checks file structure, required fields, and data values, and reports any errors and warnings before the import runs.

Errors prevent user creation. Warnings indicate issues that may lead to unexpected configuration results. Only valid user records are imported.

You can continue the import only when at least 1 valid record can be imported. If no records can be imported, there is nothing for the import process to do.

The best practice is to fix all warnings and errors before processing the file. That way, every row in the CSV corresponds to a created user, which makes it easier to follow up on issues with new user accounts.

Common User CSV Validation Errors

The most common failures reported by the pre-validation step are listed below.

Errors in User CSV Structure

Errors related to file structure, column formatting, and other general CSV issues, are listed with the discussion of CSV Import Files.

• Missing Header Row
• Unrecognized Column Names
• Invalid Record Length
• Empty Row Warnings

Username is Required

The username column must be included in the header row, and it must not be blank in any data row.

When every row of the import file reports the error Username is required., the header row is usually missing or malformed: without it, no column is identified as containing the username, so every record is invalid. Edit the import file to add or fix the header row.

When only some user records display the Username is required error, look for missing commas or quotes in those rows. Edit the CSV and start the import process again.

Duplicate Usernames

Each username may appear only once in the CSV file. Duplicate usernames cause the affected rows to fail validation.

When a username appears on more than one data row, the validation step lists each row that contains the username along with the message Username (USERNAME) occurs more than once. None of the rows with that username are imported.

To fix the error, edit the CSV to remove duplicate rows before processing it.