Batch User Data Import and Update

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:

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

For more information on using the batch import to import data from previous PaperCut editions, please see Appendix H, Upgrading from PaperCut Quota.

Tip

PaperCut 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 our sources. For information about managing a set of users in addition to those in a user directory see the section called “Internal Users (users managed by PaperCut 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 the section called “Batch User Import File Format”.

  2. Navigate to the Users section.

  3. Click the Batch import ... action (on the left).

  4. Click Browse to select the file to import. (The format of the file is described in the section called “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 checkbox, lines that contain users that do not exist will be ignored and only existing users will be updated.

  6. Press the Import button.

  7. Upon completion you will be told 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.

Batch User Import File Format

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

No.FieldDescriptionOptional?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

Table 6.2. User Import File Format

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 shows importing all the above fields. (The fields are separated by tabs).

                    matt	20.00	Y	Matt Johnson	[email protected]	Science Dept	Head office	\
                    103251	912254	NoteA
                    john	25.00	N	John Jackson	[email protected]	Administration	Other office	\
                    963254	123254	NoteB
                

Note: backslash indicates text should appear 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				[email protected]
                    john				[email protected]
                

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			[email protected]
                

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