%META:TOPICINFO{author="ProjectContributor" comment="" date="1655468868" format="1.1" version="1"}%
%META:TOPICPARENT{name="AdminToolsCategory"}%
---+ Bulk Registration

Administrators can use this topic to register (i.e. create logins and user topics) for a group of people in one batch.

Unlike normal registration the administrator is assumed to have correct e-mail addresses for the users, so *no verification is required.*
Note that the new users are not notified that they have an account. This is so you can prepare and verify the accounts before announcing them.
To announce them use the [[BulkResetPassword]] feature: this will assign a new random password and notify users.

---++ Bulk Registration usage

Note: this is an administrator job - only admistrators can run this.

If you are administrator, you will take these actions:
   1 (First time use) Create new bulk registration topics (see [[#Settings][Settings]] below).
   1 In the REGISTERTOPIC (%REGISTERTOPIC%) topic: create a table of new users. An example table is provided below to copy.
   1 Return to this topic and press the [[#RegisterForm]["Bulk Register" button]] to create the new topics.
   1 Read %LOGTOPIC% to verify if all has gone well.
   1 Visit %USERSWEB%.WikiGroups if the new users need to be added to any groups.
   1 When you are ready, use the [[BulkResetPassword]] page to assign passwords and notify the users of their new accounts.

Below are the details.

---++ Settings
   * Define where to pick up the table of users to register. It can be in any web, but defaults to the %USERSWEB% web.
      * Set REGISTERTOPIC = %USERSWEB%.UnprocessedRegistrations
   * Use this to define where to log the bulk registration process. It will be saved to the %USERSWEB% web.
      * Set LOGTOPIC = %REGISTERTOPIC%Log
   * Set this to 1 to make the bulk registration overwrite any existing user
     topics. By default, existing user topics are left alone.
      * Set OVERWRITEHOMETOPICS = 0

---++ The user table

This table is a template for user data that will be written to the new user topics. If you stick to these basic fields you can just use the first example below.
If you want to write more data (like phone number or country) read the section [[#CustomizingUserData][Customizing user data]] as well.

If the =Password= field is not included, then use the BulkResetPassword topic to assign new passwords.
If a password is included, it must be a valid password (&gt; minimum length, etc.)

%IF{"{Register}{AllowLoginName}" then="*Your system is configured to use Login Names.  Be sure to include the !LoginName column in your table*"}%

---+++ Example format

The following should be inserted into your %REGISTERTOPIC% as a table. This is the most simple format:

<verbatim class='tml'>
<noautolink>
%EDITTABLE{}%
| FirstName | LastName | Email | WikiName |
| Test | User | you@your.domain | TestUser |
</noautolink></verbatim>

*Usage:*
   1 Copy this text to your clipboard
   1 Click through and paste this on %REGISTERTOPIC%.
   1 Add and customize entries, save table. Note that the first row must not contain bolded entries, so don't apply any formatting.
   1 Return here

#CustomizingUserData
---+++ Customizing user data

You can write additional data to the new user topics. Do this by enhancing the user table with additional field names as table headers.

Any fields you define in this table will end up in the User's topic. If a form (such as %SYSTEMWEB%.UserForm) is attached to NewUserTemplate then the data will go in as META:FIELDS, meaning that you can use SEARCH formfield constructs to search.

If you use the %SYSTEMWEB%.UserForm then ensure that it contains all the fields you define here. Otherwise they will disappear when the user edits their home topic!

---++++ Mandatory fields
   * =WikiName=
   * =FirstName=
   * =LastName=

---++++ Optional fields
   * =LoginName= - __Required if the system is configured to__ ==AllowLoginName== (Commonly referred to as the UserName).
   * =Email= - If not provided, you must set a password, or password reset will not be possible.
   * =Password= - If not provided, set passwords later using BulkResetPassword.
   * =Confirm= - If provided, it must match the =Password= field. If missing, it will not be checked.
   * =templatetopic= - Template used when creating the User topic. If not provided, defaults to [[%USERSWEB%.NewUserTemplate]], or [[%SYSTEMWEB%.NewUserTemplate]].
   * =AddToGroups= - A comma-separated list of groups. When user is registered, they will be added to the listed groups. The groups must exist.

---++++ Customized table example

Make sure that the extra fields also appear on the %SYSTEMWEB%.UserForm.

<verbatim class='tml'>
<noautolink>
%EDITTABLE{}%
| FirstName | LastName | Email | WikiName | AddToGroups | CustomFieldThis | SomeOtherRandomField | WhateverYouLike |
| Test | User | you@example.com | TestUser | MyGroup, DocGroup | A | B | C |
</noautolink></verbatim>

---

%IF{
  "context passwords_modifyable"
  then=""
  else='<div class="foswikiHelp">%X% <strong>%MAKETEXT{"Caution: The password system is currently read only. Users will not be added to the Password file."}%</strong>%BR%
  %MAKETEXT{"If your wiki uses an external password manager, and the users you want to register are known to the password manager, then bulk registration may still be useful.  Please contact [_1] if you are unsure." args="%WIKIWEBMASTER%"}%</strong></div>'
}%
#RegisterForm
<form name="bulkRegister" action="%SCRIPTURLPATH{"manage"}%/%REGISTERTOPIC%" method="post">
<input type="hidden" name="action" value="bulkRegister" /><sticky>&nbsp;</sticky>
<input type="submit" class="foswikiSubmit" value="Bulk Register these people" />
<input type="hidden" name="LogTopic" value="%LOGTOPIC%" />
<input type="hidden" name="OverwriteHomeTopics" value="%OVERWRITEHOMETOPICS%" />
</form>

---++ <nop>%REGISTERTOPIC%

%INCLUDE{"%REGISTERTOPIC%" warn="Topic does not exist"}%

---++ <nop>%LOGTOPIC%

%INCLUDE{"%LOGTOPIC%" warn="Topic will be created during registration run."}%

---

*%MAKETEXT{"Related topics:"}%* AdminToolsCategory
