[nodebb-plugin-import-users-csv] User Migration via CSV Upload

julian

This plugin exposes a new admin page and endpoint for automatically creating users in the NodeBB instance via CSV upload.

Required fields are one of username or firstname (lastname is automatically appended if present), and email.

Additional fields can be present in the CSV file, but are ignored, unless explicitly specified via the admin panel.
If an additional field is specified, then it will be saved into the user's hash.

Installation

There is an identically named package not under the @nodebb scope, be sure to install the properly scoped plugin instead:

npm install @nodebb/nodebb-plugin-import-users-csv

Screenshots

A modal containing a table displaying a list of users successfully imported in

Plugin Hooks

This plugin fires off a single hook when user import has completed. To use it, listen for the action:importUsersCSV.created hook, e.g.

const plugins = require.main.require('./src/plugins');

plugins.hooks.register('myPlugin', {
    hook: 'action:importUsersCSV.created',
    method: ({ uids, users }) => { ... },
});

julian

Ah, it turns out there is already a package by the name of nodebb-plugin-import-users-csv. Great minds, think alike

This plugin has now been published under the @nodebb namespace:

npm i @nodebb/nodebb-plugin-import-users-csv

meelash

Hi @julian, new user of nodebb, but with extensive node.js experience. I installed, activated this plugin, but when I hit Upload, I'm getting a "Bad Gateway" error and I briefly get a disconnected from the backend message that goes away.

I see in the logs that after installing and activating the plugin, it now shows Adding 1 route(s) to api/v3/plugins where before that was 0.

Any tips for debugging this?

julian

@meelash it sounds like your backend is crashing (and coming back up). What version of NodeBB are you using?

meelash

@julian 3.2.0. You're right, it is crashing; I found the following the error log:
error: uncaughtException: Cannot read properties of undefined (reading 'upload')
Jul 08 19:13:55 ich-bb env[1008]: TypeError: Cannot read properties of undefined (reading 'upload')
Jul 08 19:13:55 ich-bb env[1008]: at Controllers.handleUpload (/home/nodebb/nodebb/node_modules/@nodebb/nodebb-plugin-import-users-csv/lib/controllers.js:22:17)

Also, I'm running node 18.16.1, connect-multiparty 2.2.0, and the version of multiparty installed in node_modules is 4.2.3.

meelash

@julian I'd love to fix this and send a pull request over, but it seems like the repository is private? npm shows this as the repo: https://github.com/nodebb/nodebb-plugin-import-users-csv but I can't access it. Any possibility it could be made public?

julian

@meelash Done, thanks!

meelash

@julian awesome, thank you very much. Opened an issue here: https://github.com/NodeBB/nodebb-plugin-import-users-csv/issues/6
I identified the issue, but want to confirm the most appropriate approach for fixing it; because I'm not too familiar with nodebb best practices and conventions. Whatever you suggest, I'll implement and send a pull request.

Thanks!

julian

v1.1.1 contains the ability to customize the delimiter if your export tooling doesn't use commas to separate values.

Finally, support for my new esoteric format, ♫sv

julian

Additionally, the following versions have been deprecated on npm due to an incorrect compatibility string (thanks @meelash for noticing!)

v1.0.2
v1.0.3
v1.1.0

Merrgo92

Hi @julian and @meelash ,
first, thanks for this nice feature!
I upgraded my forum and i'm trying out to put some new users via csv.
Unfortunately I receive the following message: "The following 0 user(s) have been successfully imported.".

I used this format in csv-Format:
[email protected],Testuser

As there is no clear error message, i'm not sure what is wrong with my csv.. could you provide an example or help here?

Thanks in advance

julian

@Merrgo92 do you have headers in your CSV file?

Merrgo92

@julian exactly that was the problem, thanks for the hint!

for others who face maybe similiar issues:
The following format worked for me (.csv format):

username, email
User1,[email protected]
User2,[email protected]

Eduardo Silva

@julian , how can I see all the available field names?

Would love to add users and put them in the appropriate groups in one go.

Could I do it directly with this plugin or would I need to add this custom behavior via a plugin?

I'm still new in the NodeBB world, so any approach recommendation will be super useful!

julian

@Eduardo-Silva If you're looking to update parts of the user profile via this plugin, then this API call would show relevant fields.

Anything outside of that, it just puts it in the user hash but NodeBB doesn't do anything with it. For example, you can set email as one of the additional fields, but because NodeBB stores email outside of the user hash, it doesn't mean anything to have it there... but you can do it if you like

Group memberships are stored outside of the user hash. You'd probably want to have a custom plugin listen for when users are imported, and handle their group memberships that way.

Eduardo Silva

@julian Great! Thank you :))

Eduardo Silva

One more point, @julian.

Where the User Import (.csv) screen should be located?

Already activated the plugin, rebuilt & restarted, searched and it doesn't show anywhere I could find.

julian

If it doesn't show up then it might be there was an error during build, or when you restarted you didn't actually restart the actual running instance.

Eduardo Silva

@julian It's working in my local env, but still not in the hosted forum. I'll deal with it later.

Another question : how can I access the additional fields that are put in the user hash? (edit: solved below)

Already tried "User.getUsersWithFields" and it returns null for any custom field.

It does not show in the DB Explorer plugin either.

I'm developing a "nodebb-plugin-group-membership-for-user-csv-importing" (https://github.com/Latitud/nodebb-plugin-group-membership-for-user-csv-importing).

Hope it will be helpful to others!

SOLVED:
Just forgot the click save before importing.

Eduardo Silva

Just so you know, if you use fields that already exist on the user profile as Additional Fields the profile will actually be updated.

This info will show up on the user profile page, for example.

I tested and I'm currently using with
'fullname', 'website', 'location', and 'aboutme'.

The following fields may be updated as well, as far as I understood it.

It may be nice to update the plugin documentation, so others can use this unintended functionality as well!