Available in PaperCut NG and PaperCut MF.

User card and ID numbers

PaperCut NG/MF supports two closely related features:

As both card numbers and ID numbers function as a unique number identifying a user, they both share the same field in the User record of the database—the card/ID number. This means that all administrative functions related to card numbers and ID numbers are the same, because they operate on the same database field.


Although we use the term "number", PaperCut NG/MF permits any string containing both letters and numbers in the card/ID field. If used as an ID number to be typed at a numeric keypad, a purely numeric number is best. ID numbers generated by PaperCut NG/MF are always purely numeric.

PaperCut NG/MF supports two different card/ID numbers for each user. These are called the primary and the secondary card/ID number. There are many reasons why having two numbers is useful. For example:

  • One number can be for a card, and the other for an ID number in case the user misplaces their card.

  • Different card readers can sometimes read different numbers from the same card, so having two numbers allows both types of readers to be supported.

  • You can issue new cards to users and phase out the old card with an overlap period in which they both work.

Use of either the primary or secondary card/ID number field is optional.

PaperCut NG/MF offers a range of tools for managing card/ID numbers allowing for either centrally managed or user managed card/ID numbers:

Automatic card/ID generation

PaperCut can generate random card/ID numbers for your users. This might be the ideal solution if you don't already have ID numbers assigned for other purposes. PaperCut provides a number of options allowing you to choose whether to centrally administer the card/ID numbers or to allow users to generate and manage their own numbers. You can:

After you generate numbers for your users, you need to inform them what their number is. PaperCut can help with this task as well. You can:

  • Send an email to each user with their new number. This is set up in Options > Notifications > Card/ID Number Notification. See Card/ID number notification for more information.

  • Allow users to view their number in the user web portal. To enable this feature, select the Allow users to view their card/ID numbers check box in Options > General > User Features . Specify whether you want users to view their primary or secondary card/ID number.


When generating card/ID numbers, you are asked to specify the length or number of digits you require in the generated numbers. Short numbers are easier to remember and faster to key in, but it is also easier to guess someone else's number. If your number is too short, PaperCut cannot generate sufficient numbers to cover all your users. A good rule of thumb is to make the number 3 digits longer than the number of users in your organization. If you have 10-20 users, a 4 digit number is probably sufficient. However, if you have 1000 users, you probably need a 7 or 8 digit number.

User management of card/ID number and PIN

You can allow users to manage their own card/ID number or PIN or both. These options are controlled in Options > General and result in different functionality in the Change Details menu item of the User web interfaceThe User web interface provide a range of services for users, including a summary of usage and balance history, a list of the shared accounts that the user can use for printing, the current costs for printing usage, ability to add balance by using a TopUp/Pre-Paid Card or an external payment system (when using the payment gateway module), transfer funds to other users, view a history of balance transactions, view a list of the user's recent printing, and view print jobs pending release (when using a Release Station)..

Allow users to edit the card/ID PIN

When using card number and PIN authentication, you might want to allow users to change their PIN in a similar way to changing passwords.

To enable this feature:

  1. Click the Options tab. The General page is displayed.

  2. Select the Allow users to change their card/ID PIN check box.

When users log in to the User interface, the option Change Card/ID PIN is available under the Change Details menu item.

Allow users to generate a card/ID number

You can allow users to generate their own card/ID number from the Change Details page:

  1. Click the Options tab. The General page is displayed.

  2. Select the Allow users to change their card/ID number check box; then select which card number they can change. Users can edit the prinary number, or the secondary but not both.

  3. Select the Auto-generate random number (users cannot manually enter a number) check box. This option gives users the ability to generate a new random number, but not to create a number of their own choosing.

    If this check box is cleared, users can select any number they want. Please note that this may be a potential security risk as it may allow users to confirm the existence of a valid card number used by someone else. We recommend that sites enable two-factor authentication by also requiring users to have a secret PIN number.


    To change the number of digits used when users auto-generate their own card/ID number, change the user.auto-generate-card-id.length value by using the Config EditorThe Config Editor stores information used by PaperCut to configure advanced options and functions. This information is stored in config keys, which are editable by an administrator.. In version 14.3 or later, you can also set this in the Admin web interface under the Auto-generate random number option, by setting the 'Length' value.

Users can then log in into the User interface and under the Change Details menu, the Change Card/ID option is available.

Batch user card/identity update

The batch user card/ID update feature allows the administrator to update user card/ID numbers and optionally import or update PINs by reading data from a simple text file. User card/ID numbers can also be imported using the batch user import/update feature (see Batch import and update user data).

Example: To update/import the card/ID numbers or PINs of all the users in the import.txt file on a windows system.

C:\> cd C:\Program Files\PaperCut NG/MF\server\bin\win

server-command batch-import-user-card-id-numbers "C:\card numbers\import.txt"

Note: Quote the import path if it contains spaces.


The card/ID number must uniquely identify a user, so take care to ensure that no two users have the same card/ID number. Make sure the card/ID numbers defined in the import file are unique. If PaperCut NG/MF encounters a non-unique card/ID number, that user is not updated.

Perform a batch user card/ID update by calling the batch-import-user-card-id-numbers server-command. Use of server-command is detailed in Server commands (server-command). The import file format is detailed in Batch User Card/Identity Update File Format.


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

  • Always run a backup before proceeding with the import.

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

Batch user card/identity update file format

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

User Card/Identity Update File Format
No. Field Description Optional? Limitations
1. Username The user's username. Mandatory Max. 50 characters
2. Primary User Card/ID Number A unique primary card/ID number for this user. Optional (card/ID number not set if blank) Max. 100 characters. To specify that the number is blank, enter a hyphen (-).
3. User Card/ID PIN The user's card/ID PIN. Optional (card/ID PIN not set if blank) To specify that the PIN is blank, enter a hyphen (-).
4. Secondary User Card/ID Number A unique secondary card/ID number for this user. Optional (card/ID number not set if blank) Max. 100 characters. To specify that the number is blank, enter a hyphen (-).

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

If your card/ID numbers are stored in an external database, see Looking up card numbers in an external database.


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

Looking up card numbers in an external database

PaperCut NG/MF can import user card/ID numbers from Active Directory and LDAP. This is the recommended approach because it allows the card/ID numbers to be associated with users in a centralized location. For more information see Synchronize user and group details.

Card numbers can also be imported using the import file described in Batch user card/identity update.

In some circumstances the mapping between card numbers and users is stored in another external database (e.g. a database used for secure door access). In this case, it might be more convenient to look up the card numbers in this database in real-time.


This also allows users to be associated with more than two card/ID numbers. This is useful where users are allocated different types of authentication cards, or there are alternate card systems used throughout the organization.

To allocate multiple card numbers to a user, populate the mapping table with multiple entries per user, where different card numbers map to the same username.

Once external user lookups are enabled, PaperCut NG/MF does the following when looking up a user by card number:

  1. Looks for a user with the matching card number in the PaperCut NG/MF database.

  2. If not found, it looks up the card number in the external database.

  3. If it finds a match, it uses the information returned to find the matching user in the PaperCut NG/MF database. If a user is found the lookup is successful.

Configure external database lookup

To enable external card number lookups:

  1. Select Options > Advanced. The Advanced page is displayed.

  2. In the External User Lookup area, select the Use external database for card number lookup checkbox.

  3. Select the database type. If using Oracle or MySQL you must install the database driver as described in the We are here to help, and restart the Application ServerAn Application Server is the primary server program responsible for providing the PaperCut user interface, storing data, and providing services to users. PaperCut uses the Application Server to manage user and account information, manage printers, calculate print costs, provide a web browser interface to administrators and end users, and much more..

  4. Enter the database connection URL. For examples see Step 4 - Change the PaperCut NG/MF connection details of Upsize to an external database (RDBMS).

  5. Enter the database connection username and password.

  6. SQLStructured Query Language (SQL) is a special-purpose programming language designed for managing data held in a relational database management system (RDBMS), or for stream processing in a relational data stream management system (RDSMS). to map card number in external database to allows you to choose what the card number in your external database maps to. Select the option that matches the mapping in your external database. The options include:

    Lookup fieldUse if your external database contains a mapping between card numbers and
    user's identity numberuser ids. The user ids must have been imported and stored in PaperCut NG/MF.
    username aliasusername aliases. The username aliases must have been imported into PaperCut NG/MF and enabled. See Enable username aliasing.
    username or alias usernames OR aliases. A match with a username is tried first, and if no match is found, a second search looks for a match with the alias.
    emailemail addresses
  7. Enter an SQL select query that looks up the card number in your external database and returns either a username or user id as selected above. The query must return a single row with the first field being the username or user id (as found in PaperCut NG/MF). The SQL statement must contain {cardnumber}, which is replaced with the card number to find.

    Some example queries are:

    Lookup methodQuery
    emailselect email from users_table where card_number = {cardnumber}
    username aliasselect user_alias from users_table where card_number = {cardnumber}
    username / username or aliasselect user_name from users_table where card_number = {cardnumber}

    The {cardnumber} replacement does not require quotations (it is sent as a parameter). This also serves to prevent SQL injection attacks sent via card numbers.

Testing database lookup

  1. Click the Users tab.

    The User List page is displayed.

  2. Pick a card number from your external database that maps to a user in PaperCut NG/MF.

  3. In Quick Find, enter this card number; then click Go.

  4. Verify that the matching user is displayed. If the expected user is not displayed check the App Log tab for errors.