Available in PaperCut NG and PaperCut MF.

Batch import and update user data

The user data batch import and update feature allows the administrator to import users, user information and optionally update existing users details by reading data from a simple text file. It enables administrators to update the following user data:

  • Credit balance

  • Restriction status

  • Full name

  • Email address

  • Department

  • Office

  • Primary Card/ID Number

  • Card/ID PIN

  • Notes

  • Secondary Card/ID Number

  • Other email addresses

  • Username alias

  • Home folder

Examples of where the batch user details import feature is useful include:

  • To set the user email addresses that are stored in another system (like a student management system).

  • When importing user and balance data from another external or legacy system.

  • When moving user balances from previous PaperCut NG/MF editions to PaperCut NG/MF.

For more information on using the batch import to import data from previous PaperCut NG/MF editions, see Upgrade from PaperCut NG/MF Quota.

TIP

PaperCut NG/MF is designed to import user information from the underlying system or network domain. The batch user data import feature is not designed to replace this but rather complement it by allowing importing of user data from other systems or sources. For more information about managing a set of users in addition to those in a user directory, see Internal users (users managed by PaperCut NG/MF).

To perform a batch import:

  1. Manually inspect your file in a text editor and ensure it's in the prescribed tab-delimited format as detailed at Batch User Import File Format.

  2. Click the Users tab.

    The User List page is displayed.

  3. In the Actions menu, click Batch import.

    The Batch User Import and Update page is displayed.

  4. Click Browse to select the file to import. (The format of the file is described in Batch User Import File Format).

  5. Choose whether you want the import to create new users if they do not already exist. If you clear this check box, lines that contain users who do not exist are ignored and only existing users are updated.

  6. Click Import.

    A message is displayed informing you of how many users were updated and how many users were created.

CAUTION

Batch imports are a major operation modifying data en masse. Best practise suggests:

  • Always run a backup before proceeding with the import.

  • First experiment/test the import process with a small batch of users before moving onto the full batch.

IMPORTANT

Usernames are stored in PaperCut NG/MF as all lower case, regardless of the capitalization when the username is created. Entry of a username by an end user, however, is not case sensitive as it is converted to lowercase before the account is validated.

Batch user import file format

The import file is in tab delimited format and contains the following fields in the given order.

User Import File Format
No. Field Description Optional? Limitations
1. Username The user's username Mandatory Max. 50 characters
2. Credit Balance The user's credit balance Optional - balance not set if blank A number with no currency symbol or separators, using a full stop for the decimal separator. Correct: 1.23 Incorrect: $1.23 or 1,23 or 1,023.00
3. Restricted Status The user's restricted status. (Y/N) Optional - restricted status not set if blank
4. Full Name The user's full name Optional - full name not set if blank Max. 255 characters
5. Email The user's email address Optional - email not set if blank Max. 255 characters
6. Department The user's department or faculty Optional - department not set if blank Max. 200 characters
7. Office The user's office or location Optional - office not set if blank Max. 200 characters
8. Card/ID Number The user's primary identity/card number Optional - card/id number not set if blank Max. 100 characters, case insensitive
9. Card/ID PIN The user's card PIN number Optional - card/id PIN not set if blank. If the field is '-' then the PIN is set to zero. Max. 20 digits
10. Notes Notes about the user. Optional - notes not set if blank Max. 2000 characters
11. Secondary Card/ID Number The user's secondary identity/card number Optional - secondary card/id number not set if blank Max. 100 characters, case insensitive
12. Other email addresses The user's other email addresses Optional - other email addresses not set if blank Email addresses must be separated by commas
13. Username alias The user's alias. Only useful if username aliasing is enabled Optional - alias not set if blank Max. 100 characters, case insensitive
14. Home folder The user’s home folder Optional - required for scanning to a user’s home folder. Max. 256 characters

Other limitations: Although any actual limit to the size of an import file should be large enough for any purpose, we recommend keeping the file size below 10MB.

TIP

A simple way to create a tab delimited file is to create a spreadsheet in Microsoft Excel, and then save it in the Text (Tab delimited) format.

Import file format examples

The following lines show importing all the above fields. (The fields are separated by tabs).

matt 20.00 Y Matt Johnson mattj@email.com Science Dept Head office \
103251 912254 NoteA          
john 25.00 N John Jackson jj@domain.com Administration Other office \
963254 123254 NoteB          

Note: backslash indicates text should be displayed on the same line.

The following lines shows importing user email addresses only. NOTE: That the tabs still exist for balance, restriction, full name fields, but each entry is blank.

matt mattj@email.com john jj@domain.com

The following lines shows importing the credit balance and full name for the first user and the credit balance and email address for the second user. NOTE: That the tabs characters still exist for blank fields.

matt 10.00 Matt Johnson john 15.00 jj@domain.com

For more examples, refer to the following files in the install directory:

[server install]/server/examples/import/user/external/batch-user-example.tsv

[server install]/server/examples/import/user/batch-internal-user-example.tsv