Overview
The Import Users module is part of the Pro Suite of modules for the Uncanny LearnDash Toolkit. This module lets you not only create new users in bulk but if you have LearnDash installed you can also add them to courses and LearnDash Groups and set custom user meta values, all from a CSV file. You can update existing users via CSV import too. Your users can be notified when their account is created or updated. This is a huge time-saving feature for those who need to manage a large number of users on their site manually.
This is a complex module and we recommend starting by watching the YouTube video above in its entirety.
Here are some case scenarios when you might consider importing users from CSV:
- Your site does not allow self-registration. You need to manually create a batch of new users at a time.
- You create generic user accounts and recycle them. You need to reset user passwords before each new cycle.
- You sell access to organizations. You need to set up a new LearnDash Group for each organization and quickly add their users to this new group.
- You introduced a new course. A company bought access for their staff but they’re not all in groups. You need to add their users to this new course quickly.
Importing users involves a four-step process. It’s important that you review the instructions and download our sample CSV to see examples of the fields that can be included. We also recommend that you test your import with a small number of users first.
Step 1: Review Options
To get started, in your admin panel (/wp-admin) go to Users > Import Users.
Use the Options tab to configure:
- Whether to update or ignore users that already exist on your website
- Role to assign to imported users
- Course(s) to enroll imported users into
- LearnDash Group(s) to assign imported users to
Step 2: Review Email Settings
Use the Email Settings tab to:
- Enable email notifications to new and/or updated users
- Customize email templates
Here is an example of an email template with variables which will be replaced with specific account and site information when the email is sent to users.
Note: Version 3.4.4 added the %Reset Password Link% token that generates a link to let users set a password with a single click. This is a more secure practice than emailing passwords directly to users.
Step 3: Create a CSV file
Your CSV file must be comma-delimited with a .csv extension. It requires the user_email column, and can include any number of optional fields below.
| Column Heading | Description | Required/Optional |
|---|---|---|
| user_login | The user's username | Optional; if omitted, user_email will be assigned as username (for new users only) |
| user_email | The user's email | Required |
| user_pass | The user's password | Optional |
| first_name | The user's first name | Optional |
| last_name | The user's last name | Optional |
| display_name | The user's display name | Optional |
| wp_role | Role to assign to the imported user, specified by role slug. If this column exists and cell is empty, the role in Options will be used. Available role slugs for your site are listed in the Available Meta Fields table in the Instructions tab. | Optional |
| learndash_courses | One or more courses to enroll the user into, specified by course ID. If this column exists and cell is empty, course(s) in Options will be used. Multiple course IDs must be separated by semi-colons, e.g., 96;107;92 | Optional |
| learndash_groups | One or more LearnDash groups to enroll the user into, specified by group ID. If this column exists and cell is empty, group(s) in Options will be used. Multiple group IDs must be separated by semi-colons, e.g., 91;102;98 | Optional |
| group_leader | Assign the associated user to a group as a Group Leader and add the Group Leader role. Separate multiple group IDs by semicolons (e.g. 1;2;3) if the user will be added to multiple groups. | Optional |
| ** | Any other column heading will be treated as a custom user meta value | Optional |
Notes:
- Use the column heading learndash_courses to enroll users in specific courses. For enrollment in multiple courses, separate course IDs with semicolons (;). If this column is blank or omitted from the spreadsheet altogether, users are enrolled in the courses specified in import options (Step 1 above). To find the ID for a course, edit the course and check the address bar in your browser; the course ID will be the number that appears in the URL (e.g. if the URL includes /wp-admin/post.php?post=670&action=edit, “670” is the course ID).
- Use the column heading learndash_groups to assign users to specific groups. For assignment to multiple groups, separate group IDs with semicolons (;). If this column is blank or omitted from the spreadsheet altogether, users are assigned to the groups specified in import options (Step 1 above).
- If you don’t include a wp_role column in your CSV, all imported users will get the subscriber role.
- If no user_pass column or value is present for new users, a password will be auto-generated.
- Any other column heading not recognized as a standard WordPress meta key will be created as a custom user meta key.
- Username and email address cannot be updated via import.
- Although you may specify any role to assign to imported users, keep in mind certain roles (e.g., Group Leader) require additional setup. We recommend that you use import for learners (subscribers) only.
Let’s take a look at an example in which the same CSV file is used to create new users and update existing users (if Update is selected in Options). The CSV file contains the following data:
user_login,user_email,user_pass,first_name,last_name,wp_role,learndash_courses,learndash_groups
amiller,amiller@mymail.com,test1234,Anne,Miller,,,
ajones,ajones@mymail.com,,Arthur,Jones,,,
aryans,aryans@mymail.com,,Annie,Ryans,,11;22,100;200
- Suppose the first user, Anne Miller, is a new user. Her new account will be created with a manual password and the default role, course(s), and group(s) specified in Options.
- Suppose the second user, Arthur Jones, is also a new user. Because the user_pass field is empty, his password will be auto-generated. He will be added to the default role, course(s), and group(s) specified in Options.
- Suppose the third user, Annie Ryans, is an existing user. She will be enrolled into courses with IDs 11 and 22 as well as assigned the groups with IDs 100 and 200. There will be no change to her password.
Note that when you update existing users:
- If you leave their first name and/or last name empty, the user’s existing meta value will be replaced with the blank value.
- The course(s) and group(s) you specify in the CSV will be added to what’s already in the user’s profile rather than replacing them.
Step 4: Import Users
Go to the Import Users tab once your CSV file is ready to begin the import.
The Current Settings section shows you what has been configured in Options and Email Settings. Review these settings and make any changes as necessary.
When you are ready, proceed to the Import LearnDash Users section to upload your CSV file.
The validation results will show you any potential problems with the import. (The example below shows that one of the users has a malformed email address.)
Make any necessary corrections to your CSV file and re-upload it, or click on Perform Import to proceed with import.
When import is complete, the page will refresh and confirm the number of users that have been successfully created/updated. Please note the first validation is a quick check. It may not always coincide with the final upload results which may report other conflicts such as mismatched usernames and email addresses.
Important: Are you an Uncanny LearnDash Groups user? If you are, uploads to a group with a defined seat limit will change the seat count when users are added to the group. If the group contains available seats, uploaded users will count against those seats. If the group has no available seats, the total seat count will be increased to accommodate the number of users imported so that 0 seats remain.
Group Leader access
To grant unrestricted upload capabilities to your Group Leaders, the following snippet can be added to the functions.php file of your child theme:
add_filter('toolkit_learndash_user_import_capability', function($role){
return 'read_essays';
}, 99, 1);
Because Group Leaders don’t normally have access to the Users tab where we add the import action for administrators, the menu entry will be added to the Dashboard menu instead.
Please exercise extreme caution when enabling this for Group Leaders, as it would allow a Group Leader to create any type of user, including administrators.
Troubleshooting unexpected results
Are users being added to courses and groups that you weren’t expecting? This is a very common issue that is almost always unrelated to the import process.
Users might be added to unexpected courses because:
- Courses are set to “Open”
- A tag or membership level is adding users to the course
- Users are added to extra groups that apply course access
Users might be added to unexpected groups because:
- Group automatic enrollment is on (see https://www.learndash.com/support/docs/users-groups/groups/group-courses/#group_courses_auto-enroll). Even if that checkbox is unchecked, auto enrollment applies to anything in the box on the right.
- A user has a tag that automatically adds them to a group
Filters for developers
The uo_csv_overwrite_existing_roles filter can be used to enable the import to add new roles to existing users instead of replacing existing roles:
add_filter( 'uo_csv_overwrite_existing_roles', '__return_false' );
The csv_wp_insert_user filter can be used by developers to customize of the import process to allow more flexibility in setting values like Display Name (which cannot be upload as a column). Here’s an example of a code snippet that could be used in a functions.php file to set Display Name equal to First Name and Last Name as part of the import:
add_filter('csv_wp_insert_user', 'uo_kb_insert_filter', 10, 2);
function uo_kb_insert_filter( $userdata, $current_row ){
// $user_data give you an array of fields that can be a passed into the wp_insert_user function
/*
* ex.
*
$userdata = array(
'user_email' => 'aflinch@example.com',
'user_login' => 'aflinch',
'user_pass' => '4rV4Z1lQ9Jeg'
);
*/
// Add dsiplay name to user data as the first_name and last_name in the CSV row
// ex. ["aflinch","aflinch@example.com","Adrian","Flinch","4rV4Z1lQ9Jeg","subscriber"]
// 0 1 2 3 4 5
// You will have to find out the index of the CSV cell
$userdata['display_name'] = $current_row[2] . ' ' . $current_row[3];
return $userdata;
}
The uo_toolkit_csv_import_map filter can be used by developers to remap the column headings on import:
add_filter( 'uo_toolkit_csv_import_map', function ( $header ) {
return [
'user_login' => 'user-login',
'user_email' => 'user email',
'first_name' => 'first name',
'last_name' => 'last name',
'user_pass' => 'user pass',
'wp_role' => 'wp role',
'learndash_courses' => 'learndash_courses',
'learndash_groups' => 'learndash_groups',
'display_name' => 'custom display name',
];
} );
I there a way for group leaders to be able to use this function?
Hi Manny,
Our Groups plugin has a very limited version of the CSV user upload function, but I’m afraid this particular module is restricted to admins only. In the hands of Group Leaders it would be very dangerous and confusing, unless we modified it heavily to only support groups and courses associated with the Group Leader’s access. Even then, we would probably need to restrict email capabilities.
We know there is value in adding more options like this for Group Leaders, like some level of customization for welcome emails, but I’m afraid that for now this remains an admin only module.
Hi Ryan,
We have a multisite WP and our site level admin cannot view the import user page. How to I let our site level admin to do the importing task? Thanks.
Unfortunately, it looks like the Import LearnDash Users module is currently incompatible with multisite installations. We’re looking into whether we can add support in the next release. I’ll update here when we’re able to make that determination.
Is there a way to use the password reset link rather than password in the email (%Password%)?
To force the user reset their password, you can remove the %Password% token from the email and instead instruct them to follow a link to the password reset page on your site.
can you automatically set users to ‘completed’ status when importing? For example if you are moving to learndash from a different platform and want your users who have already completed the course to also have access to the new LD course but don’t want them to have to go through and complete all modules again. thanks!
Unfortunately, that’s not currently possible with this module.
Where do you get the group ID from?
You can get the group ID by going to LearnDash LMS > Groups, clicking on a group, then looking at the URL in your browser. It should contain something like “?post=2011”. That number is the Group ID.
Hi,
I downloaded the sample csv.
Then i put text to columns, make some changes and save as csv.
i get an error when oploading that i do not have the required email field.
Thats because my csv is not seperated with , but with ;
How can i change this setting?
Because in your video you can upload the file with the csv set to columns.
I do not want my client to do al lot of unnecesary steps of find and replacing all ; with , and then paste in the first column.
Kind regards.
This issue, where the delimiter is something other than a comma, is usually caused by the language settings on your computer and you use Excel to create the file. Changing your language settings is one option, or you might try importing the file into Google Sheets instead where it’s easier to export using a commas as the delimiter.
Thank you for your fast reply.
I am going to try that.
Does the option “to update or ignore users that already exist on your website” mean that you can enroll users who already have a site registration into a course via CSV? We have LearnDash running as part of a WP website with registered users, who are not necessarily enrolled in a course. So the uploaded CSV would include registered site users, so the uploader would ignore the registration process for them and just handle the course enrollment. Is that correct?
Exactly correct. Note though that to update an existing user’s course/group access the CSV file MUST include both the current username and email address of that WordPress user. If either value doesn’t match, the update will be ignored.
Hi,
I want to transfert learndash course.
If I use this plugin to import the existing users from the site1 to the site B,
Could you tell me if the progress of the user are imported ?
Thanks
Regards
Ludovic
Hi Ludovic,
There is definitely no way (short of a fair bit of development work) to move progress records in LearnDash from one site to another. This module will let you import users and usermeta, along with course and group enrollments, but not anything related to progress or quiz data.
Do you provide any add-on or other thing to import course progress/status of % or else using the .csv file? Like we can assign course id and % so the status will update on a system or something like that?
Thanks!
Sorry, it’s definitely not possible. The complexity would be enormous; you can’t populate just a % complete, you would need to identify which specific lessons and topics to mark as complete to have LearnDash generate the % complete.
Having said that, with Uncanny Automator you can use import files in this module to mark things as complete (including courses). Have a look at https://automatorplugin.com/run-actions-on-wordpress-users-in-bulk/ for more info. Note though that the import rules would apply to EVERYONE in the CSV file, there isn’t a way you could mark different things complete for different users in the same file.
Hi, is there a way to import more than 1000 users at once?
You could potentially override it with code, but I wouldn’t even recommend uploading 1,000 users at once. This will push your server resources too hard, it’s a lot of emails to send at once, if you have a mistake in the import file it’s harder to fix, etc. Smaller batches are safer. The 1,000 limit we force isn’t a technical restriction, we added it so we don’t overload servers.
Thanks Ryan, I actually don’t need to send emails, I was just wondering because I’m only adding my existing WishList Member users from their respective levels to their respective courses on LearnDash, so I don’t need to send emails out, I already did some testing in my staging site and 1000 users are getting updated in about 2 minutes.
I have 6 levels with 6,700 users each, I would have to create 7X6=42 CSV files to accomplish my import, since I’m not sending out emails I figure I could push it to 4,000 per file perhaps? or even 3,000 would save me some time.
What I’m trying to do is some kind of migration withing the site, from WishList Member levels, to LearnDash courses.
Certainly you could modify the code to allow that. It’s not something we could support, and if it were me I would probably still go with the 42 imports. 🙂
Thank you Ryan, I will do the 42 imports then, I’m good at listening to what is suggested.
Thank you very much for the fast responses also, I’m a new customer of yours, I just bought the pro version 2 or 3 days ago I think.
Hi, is there a way to import users automatically every x hours, not manually ?
Sorry, that’s unfortunately not something that’s supported (or planned).
Hi there,
I’ve downloaded the .csv sample file that you’ve got up here and exchanged the information for my own. It seems as the plugin will only import the first user from my list, and not the rest. Can you please help me understand why it’s not working for me?
Thanks in advance,
Christine
Sorry Christine, for anything like this you must submit a ticket and we really need to see the CSV file. Check it in a text editor; maybe there’s an invalid leading or trailing space in a column, maybe there’s an extra record and it’s formatted incorrectly, it’s really too hard to say without seeing the file.
Hello,
We are having issues with the import. It can only do 10 users at a time per CSV file. We have over a thousand users to import. We are following the instructions to the tee. Any insights?
You should definitely file a support ticket for this one and let us know what’s happening. It could be low PHP timeouts in the environment, looping through too much data if you’re adding significant volumes of records on the LearnDash side, it could be something else entirely. On larger sites where we’re adding course and group mappings plus usermeta we typically expect to process about 250 users every 10 minutes. Let us know exactly what you’re seeing and what data you’re importing when you open the ticket.
Just wanted to double-check – when importing users when you do not want to send an email – if I do not check the email boxes on the import, I’m hoping that also means that they will not receive the standard WordPress “Add User” email. Is that correct?
It sounds like maybe you mean the notification when admins create a new user in /wp-admin/ and the box is checked to send a notification email? If so, that’s correct, that email is not sent. No emails would be sent.
Hi there,
I’m considering getting the Pro plugin and I have a few questions related to this:
1) When you import users that way, can the plug-in also add them at the same time to a Mailchimp or GrooveMail list, in the correct group, using groups/tags? How?
2) Can you send a Mailchimp/GrooveMail automation when that happens, in replacement of the automated email?
3) In that case in there a way to pass the variables (username, password)? Or would it have to be two different emails, once from the plugin and the automation from Mailchimp/GrooveMail?
4) What is the security level of this import feature? Plug-ins able to import are frequently compromise, so what are the measures preventing a third party from importing themselves with admin rights?
Many thanks!
Manni
Hi Manni,
Good questions, but I’m afraid what you want to do for numbers 1 to 3 isn’t something we could support. It would just be far too slow to communicate out to an external system and wait for a reply for every record. You could instead run the import, then use a plugin like WP Fusion to pass tags and other data to a CRM as a batch afterwards?
As for security, that’s exactly why our importer in Uncanny Groups (for Group Leaders) is so locked down compared to this importer in Toolkit Pro. This one is only available to admins, and yes, they can add whatever users and data they want, including new admin users. We make the assumption that since users that can run imports are admins, they can add whatever user data they want.
Hello, I know you answered this question previously but I thought maybe it’s been added since 3 years have passed. Can I import a list of users and automatically set their course as completed when transferring to a new site?
Thank you.
Sorry, we still don’t support marking things complete via import. The load on servers would be very significant so it’s not currently planned either.
Hi,
I would like tot grant acces to a “lower level” admin with the use of User Role Editor. I can see all my plugins, but unfortunually I don’t see anything ot grant acces to the import of users. While this user DOES already has permission to add users manually. Any way to add fix this? I can’t make them a real admin since then they also can access stuff like general settings, theme options etc.
Hi Wilco,
In the next release of Toolkit Pro we will include support for a custom “Toolkit – Import Users” role that can be assigned to users and that will allow uploads from /wp-admin/. If you want the changes in advance you’re welcome to open a ticket and we can provide them, otherwise we’ll have the support in the next public release.
Is there an upper limit of how many users you can import at one time?
Yes, the current limit is 1,000 per file. It’s possible to override this with a snippet, but to keep everything easier to manage (especially if there are errors) and performant, we do have that default limit.
Thanks for letting know.
Hi Ryan,
We have a multisite WP and our site level admin cannot view the import user page. How to I let our site level admin to do the importing task? Thanks.
This is definitely that we should look at in a ticket. When you open it, maybe you can confirm if the plugin is site or network activated, what role the user has and whether role capabilities have been modified (I believe this requires manage_options).
hello, is there any way to overwrite users but now enrolled in courses? I’ve tried and it won’t let me.
Hi, you can add new course enrollments via import, but if you mean you need to remove people from existing courses, the import won’t support it. There are several ways to modify and add data to users with the import tool, just not remove existing records.
(There are potentially options via Uncanny Automator and https://automatorplugin.com/run-actions-on-wordpress-users-in-bulk/ though if you really need to trigger removals.)
Is there any way we can automate the csv file upload process to do bulk user profile and their courses/groups update?
Hi Kevin, so the upload would replace existing records and mappings rather than just add things? If there’s custom user meta in the upload the values would be replaced, and for more control over removing some things during upload you could use Uncanny Automator recipes to do additional processing. Otherwise though no, you can’t remove course and group mappings in an upload.
I want to import a user via csv but I don’t want them to be added to a group. I just want them be added with a specific course, is this possible
Absolutely. All columns are optional except the email columns, so you can leave the learndash_groups out of the CSV file and not select any groups from the Options tab.
Hi Just a follow up question, when i go to unselect a group from the options tab the last group I imported is selected in the options tab, how do I unselect this as it doesn’t seem to allow me to do this, its like I have to choose a group.
You should be able to use the CTRL key while clicking on Windows or Command key on Mac to unselect something that’s already been selected, but let us know if you run into any trouble.
Hola, Tengo una duda como se si ya los usuarios que estoy asignando a un cursos tienen una contraseña establecida, osea tengo muchos y no se cuando sean nuevos o no quiero hacer que si son nuevos la contraseña no se actualice y llenar el excel con los datos de contraseña general pero que los nuevos no se genere nueva contraseña si no que quede la misma
The module will create users that don’t exist and update users that don’t exist. If a user exists, a password field will be ignored and it will not be changed for the user. Similarly, if a matching email is found but the username is different, nothing will happen to the username; the import cannot update username records.
Hey Ryan,
Thank you for the detailed explanation. I have a couple of questions based on the YouTube Video, I understand that it may be a little dated, so thought it better to double-check with you.
1. What is the recommended number of Users to be imported at one time? On the video you mention only 100, or at tops 200, please can you confirm the best practice.
2. You mention an issue with emails being sent when importing Users and adding them to courses. Please can you clarify the best practice to ensure emails are sent when Users are added?
Thank you
Dave
Hi Dave,
For #1, it really depends. The hard limit in our code is 1,000 rows. In practice, we generally limit things to about 250 ourselves. If you’re running Automator recipes against imported users and/or mapping to a lot of groups on import, we might even suggest lower than 100.
For #2 you shouldn’t see any issues, but this may be a consideration if you use your web host for sending emails (vs. a transactional email service like Sendgrid, SES, Mailgun, etc.). In some cases your host or mail provider might limit the number of outgoing emails that are allowed, but you’d have to confirm with your provider.