User Import User Guide Last update: 2023-03-03 16:46:04

The User Import Manager Interface consist of a single page and provides all options to rapidly import a batch of users into the MODX user database. There is no limit for the count of users to import.

User Interface Description

All interface fields should be pretty self-explanatory but for the sake of completeness here is a description of all fields:

The User Tab

(Screenshot: User Import Management Interface - Import Screen)

• CSV File
  Select a CSV file which holds the user-data in the required format from a local path. The selected file will be uploaded to the server and processed there.
• First row holds field names
  This option needs to be checked if the first line of your CSV file holds the name of the column headers (fields).
• Batch Size
  The number of records to import from the CSV file beginning at line 1. If set to 0, all records will be imported.
• Field Delimiter Character
  Enter the specific delimiter character which is used in your CSV file to seperate the values in each row. Most commonly used delimiters are ; (semi-colon) and , (colon)
• Field Enclosure Character
  Specifies the character which is used to enclose strings in your CSV file. Any field may be quoted. Fields containing a line-break, double-quote, and/or commas must be quoted otherwise the CSV file will likely be impossible to process correctly. Most commonly used enclosure character is the " (double quote)
• Import Options / Set Email Address as Username
  If this option is checked, the username field of your CSV file is ignored and the value from the email address field is used instead. The username field can also be empty ("") in this case.
• Import Options / Create import-markers
  If this option is checked, the date/time of the import and a unique Import-Key is written to the extended fields of each imported user. This can be used to later identify the last imported batch of users. (This will be used later within a new release to enable rollbacks of imports!)
• Import Options / Notify users
  If this option is checked, all imported users will be notified via email! The notification template used for the email is fully configurable with placeholders, snippets and other MODX template specific features.
• Assign MODX User Group(s) and Roles / The User Groups tree
  Check one or more MODX User Groups and the imported users will be automatically added to this Groups.
• MODX User Roles
  Select a Role and it will be assigned to all imported users. Please note that at least the Role "Member" is used if no other Role is selected (this is a base requirement of the MODX ACL system!).

The GoodNews Tab (only v2.x and later)

(Screenshot: GoodNews groups and categories assignment)

• Assign GoodNews subscriber Groups and Categories
  Check one or more GoodNews subscriber groups and/or categories to import users as GoodNews susbcribers. This tab is only visible if the additional GoodNews add-on is installed!

The Notification Template Tab

(Screenshot: User Import Management Interface - Notification Template Screen)

• Mail Subject
  The subject for the notification email.
• Mail Body
  The body for the notification email. The body can contain plain text or HTML including all user-object placeholders, snippet calls and system setting placeholders!
• Mail Format (only v2.x and later)
  The format for the mail body. Can be HTML or Plain text.

The Import Process

To start the import process, simply hit Start import button from the Action bar (top right). A MODX console log window opens and you can watch how your users are imported. The console will also show any errors which occure.

(Screenshot: User Import Management Interface - Console)

The date/time of the import and a unique Import-Key is written to the extended fields of each imported user. With this unique Import-Key it is easy to identify each batch of imported users for later reference.
One of the next versions of User Import will include a feature to completely roll back an import based on this Import-Key!

Saving Import Presets

On the top right (action buttons) you will find a Save Settings button. Hitting this button will save most of the interface field values as system settings. Each time you load the User Import manager page, the corresponding fields will be prefilled with their values from system settings.

The following fields are saved as system settings

• Batch Size
• Field Delimiter Character
• Field Enclosure Character
• Set Email Adress as Username
• Create Import Markers
• Notify Users
• Mail Subject
• Mail Body
• Mail Format

Please note that the field values are not saved as presets by starting an import process! You always need to hit the Save Settings button.