Import User Records - Vanilla Success
<main> <article class="userContent"> <p>The <strong>Bulk User Import</strong> tool makes it easy for you to import a prepared file into your <strong>Higher Logic Vanilla</strong> (<strong>Vanilla</strong>) community in order to manage multiple user records simultaneously.</p><p>The file can be used to:</p><ul><li>create new user records,</li><li>update existing user records, or</li><li>invite users to join your community.</li></ul><h2 data-id="import-methods">Import methods</h2><p>You can import the file into your Vanilla community by <em>either</em>:</p><ul><li>uploading it from a "local" device or</li><li>downloading it from a URL/web address, such as <strong>https://yourdomain.com/user-upload.csv</strong>.</li></ul><h2 data-id="file-type-size">File type & size</h2><p>The following conditions apply to <em>any file used for this import</em>, regardless of whether the file is uploaded from a device or downloaded from a URL.</p><p><strong>File type</strong>: the <em>only</em> valid file type for these import options is <strong>.CSV</strong></p><p>✔️ <strong>TIP</strong>: Refer to <strong>UTF-8 for character integrity</strong>, below, if you have non-English-language characters in usernames</p><p><strong>File size</strong>: the <em>maximum size</em> for the import file is <strong>50MB</strong></p><h3 data-id="utf-8-for-character-integrity">UTF-8 for character integrity</h3><p>If you anticipate having usernames that contain non-English-language characters, save the import file as a <strong>CSV UTF-8 (Comma delimited)</strong> .CSV file. This better ensures that these characters are preserved and the import file doesn't get corrupted.</p><div class="embedExternal embedImage display-medium float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/NHAGJ4WC20MZ/save-as-options.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/NHAGJ4WC20MZ/save-as-options.png" alt="Save as - options.png" height="366" width="374" loading="lazy" data-display-size="medium" data-float="none"></img></a> </div> </div> <h2 data-id="prepare-the-import-file">Prepare the import file</h2><p>Before you import a file, reference the example file image below and then review the information that follows it. This increases the likelihood that the data and fields in your file are correctly formatted and populated.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/VO5DXIOI72HD/csv-file-example.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/VO5DXIOI72HD/csv-file-example.png" alt="CSV file example.png" height="233" width="635" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <ul><li>The data must be in <strong>three consecutive columns</strong>, <strong>in the order</strong> shown above, with no preceding blank columns.</li><li>The data can be in an <strong>unlimited number of consecutive rows</strong>, with each user record <strong>on its own row</strong>, and no preceding blank rows.</li><li>Email addresses <strong>must be text</strong>; they cannot be links.</li><li>Each row can have a <strong>maximum of three values</strong>; just two values is also valid in some instances.</li><li>The import file <strong>can have a header row</strong>; however, this must be indicated by checking the relevant box so that the importer knows to skip this row.</li><li>Refer to the sections below for information on the parameters (including details on which parameters are required and when) and the import options.</li></ul><h2 data-id="email-parameter">Email parameter</h2><p>This parameter (column <strong>A</strong> in the example image) can contain any valid email address.</p><ul><li>If you're using the <strong>update option</strong>, this is the "controlling" parameter.</li><li>The email address <strong>must be text</strong>; it cannot be a link.</li><li>This parameter is <strong>required for all of the import options</strong>.</li></ul><h2 data-id="username-parameter">Username parameter</h2><p>This parameter (column <strong>B</strong> in the example image) must be a <strong>minimum of three characters</strong> and a <strong>maximum of 40 characters</strong>.</p><p>Username is the "controlling" parameter for the <strong>insert option</strong> and <strong>must be unique</strong>. If a duplicate <em>username</em> is in the import file, that entire row (of any subsequent instances) of data is purged from the import. Only the row that has the <em>first instance of a username</em> is imported.</p><h4 data-id="username-exceptions">Username exceptions</h4><ul><li>If you're using the <strong>invitation option</strong>, <em>username</em> is optional and the "duplicate record" caveat does not apply.</li><li>If you're using the <strong>update option</strong>, <em>username</em> is optional because <em>email</em> is the controlling parameter that determines which row is updated.</li></ul><h2 data-id="role-parameter">Role parameter</h2><p>This parameter (column <strong>C</strong> in the example image) can have one or multiple values.</p><ul><li>The value <em>must exactly match</em> existing Roles in your Vanilla community; for example: <strong>Administrator</strong> is rejected if your community Role is <strong>Admin</strong>.</li><li>The value is <em>not case-sensitive</em>; for example: <strong>admin</strong> and <strong>Admin</strong> are valid and treated the same.</li><li>Multiple values must be separated by a colon ( <strong>:</strong> ); for example: <strong>guest:Member</strong></li><li>Roles that have spaces (e.g., <strong>Acct. Admin</strong>) do not require, but can be placed within, single ( <strong>'Acct. Admin'</strong> ) or double ( <strong>"Acct. Admin"</strong> ) quotation marks.</li></ul><h2 data-id="import-options">Import options</h2><p>There are three options (<strong>Invite</strong>, <strong>Insert</strong>, and <strong>Update</strong>) with the Bulk User Import tool. You choose an option after your file is loaded into the importer.</p><p>✔️ <strong>TIP</strong>: The table below is a quick reference of the parameter requirements for the import options. </p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/AA4GT4AQDOSQ/table.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/AA4GT4AQDOSQ/table.png" alt="TABLE.png" height="181" width="646" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h2 data-id="option-1-invite-new-users">Option 1 - Invite new users</h2><p>Choose this option to send an email invitation to users to join your Vanilla community.</p><p>The <em>username</em> parameter is optional for this option. If a user name is provided, it pre-populates the <em>username</em> field in the registration form, but can be changed by the user.</p><p>The default "Invitation" <a href="https://success.vanillaforums.com/kb/articles/317-email-notifications#default-language-in-email-notifications" rel="nofollow noreferrer ugc">email notification</a> is sent. It includes a link that the users can click to log in and then set their preferred username and password.</p><h4 data-id="registration-settings">Registration settings</h4><p>To use this option, check the following settings on the User Registration Settings page (<strong>Settings > Membership > Registration</strong>) in the Dashboard.</p><ul><li>Make sure the <a href="https://success.vanillaforums.com/kb/articles/303-registration-methods#invitation" rel="nofollow noreferrer ugc">Registration Method</a> is set to <strong>Invitation</strong>.</li><li>Make sure you have not exceeded the invitation "send" threshold that is set for your Role in <strong>Choose who can send out invitations to new members:</strong>. (Consider setting this to <strong>Unlimited</strong> to prevent this issue arising and causing delays.)</li></ul><h2 data-id="option-2-insert-new-user-records">Option 2 - Insert new user records</h2><p>Choose this option to create new user records in your Vanilla community.</p><p>All three parameters are <strong>required</strong>.</p><p>An email is sent to new users. It includes a link that the users can click to log in and then set their preferred username and password.</p><p>If a user record (based on the <em>username</em>) already exists in the community and the email and/or role value differs from the existing record, the record is updated.</p><h2 data-id="option-3-update-existing-user-records">Option 3 - Update existing user records</h2><p>Choose this option to update user records, based on <em>email</em>, in your Vanilla community.</p><p>The <em>email</em> and <em>roles</em> fields are required but <em>username</em> is optional.</p><p>If the value of <em>role</em> and/or <em>username</em> differs from the existing record, those values in the existing record are updated; new users are created and emailed.</p><h2 data-id="load-the-file">Load the file</h2><p>The <em>file upload</em> and <em>start import</em> actions are at the bottom of the <strong>Bulk User Import</strong> page. This is where you choose the import method and load the file into the importer.</p><p>1. Access the Dashboard.</p><p>2. Navigate to <strong>Settings > Import > Bulk User Import</strong> and scroll to the bottom of the page.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/UVCN7MSPFLL9/file-import-actions-choose-1.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/UVCN7MSPFLL9/file-import-actions-choose-1.png" alt="File import actions - choose 1.png" height="258" width="648" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>3. To load an import file, either:</p><ul><li>(<em>Upload CSV</em>) Click <strong>Choose Files</strong> to navigate to and select your prepared import file.</li><li>(<em>Download CSV</em>) Specify the URL of where the import file is stored.</li></ul><p>📝 <strong>NOTE</strong>: If both methods are used, the Upload CSV option takes precedence.</p><p>4. Optionally, check the box to have the importer ignore the first row (column headers) of data in the file.</p><p>5. Click <strong>Start</strong>.</p><p>📝 <strong>NOTE</strong>: You will select the import option on the next page.</p><p>🛑 <strong>IMPORTANT</strong>: The import will fail if the syntax of the CSV file is not correct; review the example earlier in this article.</p><h2 data-id="import-the-file">Import the file</h2><p>After you've loaded the import file and clicked <strong>Start</strong>, you have to choose an import option.</p><p>1. Review the <strong>name of the file</strong> and the <strong>row count</strong> to make sure they are what's expected.</p><p>📝 <strong>NOTE</strong>: You can abort the process at this point by either clicking <strong>Back</strong> (to the <strong>Bulk User Import</strong> page to start again) or navigating away from the page.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/Y06SJ14IFOBU/pg-2-begin-import.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/Y06SJ14IFOBU/pg-2-begin-import.png" alt="pg 2 - begin import.png" height="352" width="736" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>📝 <strong>NOTE</strong>: If you get the "0 invitations available" message, you can either: choose a different import option <em>or</em> navigate to <strong>Settings > Membership > Registration</strong> and increase the invitation "send" threshold for the Role, if possible.</p><p>2. Choose one of the options under <strong>What do you want to do with the user import data?</strong>.</p><p>3. Click <strong>Begin processing</strong>.</p><h2 data-id="post-import-notifications">Post-import notifications</h2><p>After the import has processed, the page indicates the "success/failure" of the import, as shown in the following images.</p><h3 data-id="failed-import">Failed import</h3><p>In this import, there were two errors, as indicated by <strong>Errors (2)</strong>:</p><ul><li>The <strong>First line has headers</strong> box was not checked, so those [Line 1] values were deemed invalid.</li><li>The Role in the community is <strong>administrator</strong>; <strong>admin</strong> does not match so it is invalid.</li></ul><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/I1ZYE9X2LFUC/post-import-errors.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/I1ZYE9X2LFUC/post-import-errors.png" alt="post-import__errors.png" height="223" width="870" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <h3 data-id="successful-import">Successful import</h3><p>Having used the error information, the corrections were made and the import was retried. This time, because there isn't an error message, we know that the import was successful.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/JKZUCT176WGO/post-import-success.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/JKZUCT176WGO/post-import-success.png" alt="post-import__success.png" height="173" width="846" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p><br></p> </article> </main>