Bulk importing user data using CSV

What is the user data import tool?

You can add and update users in PaperCut Hive and Pocket in many ways, including:

• manually adding users via email address
• syncing users from an Identity Provider (IdP) via a user sync Add-on
• allowing users to request access via a QR code on a printer.

But there are some occasions when bulk managing your users via a CSV (or TSV) file is a better fit. For example, you might be:

• migrating users from PaperCut NG or PaperCut MF (or another print management solution).
• setting up a new PaperCut Hive or Pocket organization, but:
  • you don’t use an identity provider (like Microsoft Entra ID or Google Workspace), or
  • you have a large number of new users which would be difficult to manually invite.
• changing all your users’ access card numbers, and want to update your users’ card numbers so they can continue to print without interruption.

Keep reading to learn how to use a CSV/TSV file to get your users printing as quickly as possible.

Benefits of managing users via a CSV/TSV file

• Streamlines migrations: The user data import tool simplifies the process of migrating users from another print management solution or from PaperCut NG/MF.
• Simplifies onboarding: The user data import tool provides a simple, flexible way to bulk import key user data like email addresses, user balances, card numbers, and access codes. This is particularly useful for new customers who can use their preferred IdP add-on and use a CSV/TSV file to fill any gaps in their IdP user data.
• Saves time and reduces errors: No need for manual data entry, allowing admins to import or update hundreds of users in bulk.
• Ensures a smooth start for users: Users can start printing right away with their existing cards, which reduces complaints and confusion. This means a better user experience and less support load on admins and resellers from day one. Refer to Known Limitations section for more details about card numbers.

Data types that can be bulk imported or synced into PaperCut Hive and Pocket

Before discussing scenarios of when you might want to use the user data import tool, let’s first understand which different types of data can be imported/synced into PaperCut Hive or Pocket:

Next, let’s look at when you might want to use the user data import tool, a user sync Add-on, or a combination of both.

When to manage users via a CSV file

With so many ways to bulk add/update users into PaperCut Hive and Pocket, you might be wondering when to use a user sync Add-on, when to use the user data import tool, or when to use a combination of both. The tables below unpack some of the common scenarios for bulk adding (or updating) users, and a recommended approach.

Frequent scenarios: new PaperCut Hive or Pocket installations

Frequent scenarios: migrating from PaperCut NG/MF

Data format requirements for CSV files

How the user data import tool reads your CSV file

It’s important to understand these general rules when working with the user data import tool in PaperCut Hive and Pocket:

• Cells with no data are ignored.
• Each user (determined by unique email address) must only have a single line/row. If the user data import tool identifies a single user as having multiple rows, the import will fail. If sequential data operations are required, split these into different CSV files, and upload them in the appropriate order.
• Data included in the Email, Username, Access code, and Access card must be unique to each user. If the user data import tool identifies repeats of these data across multiple users, the import will fail.
• Any data in a cell will overwrite the equivalent value in PaperCut Hive or Pocket (if it already exists).
• Adding a hyphen to a cell will delete the equivalent value in PaperCut Hive or Pocket (if it already exists). In some cases, this will cause an error (refer to the exceptions table below).
• The data in the file will override any other specific new user settings in PaperCut Hive and Pocket.
  For example, a setting that all newly-added users receive $5 and “restricted” account types will be ignored if the CSV field includes specific balances and restricted statuses against the added users.
• Users can only be added (created) or updated. Deleting a user in the file has no effect on the User List in PaperCut Hive or Pocket — although we are working on this functionality.

Specifics of, and exceptions to, how the user data import tool reads your CSV file

Specific data format requirements

The User data import tool accepts both CSV and TSV files, as long as your user data meets these data format requirements:

• Each user is on a unique row.
• The file contains an “Email” column.
• The following columns do not contain any cross-user duplicate data: Username, Email, Access code, Access card. If duplicates are detected, the import will fail.
• Any other column names match the names in the Data file column descriptions table below, including capitalization and must be in the English language. Any other columns will be ignored.
• The file is less than 65 MB.
• The file is saved with UTF-8 (UCS Transformation 8) encoding.

Data file column descriptions

How to import new users and/or update existing users into PaperCut Hive or Pocket via a CSV file

Before you start

To get ready to import or update user data, in the admin console, go to Users > Bulk management > Import user data (CSV).

You’ll use the data in a single Comma Separated Values (CSV) file to:

• create new (add) users (by adding and completing a new row), and/or
• edit the details of existing users (by amending their details in the associated row)

(Optional) If you have existing users in PaperCut Hive or Pocket, we recommend you export your existing user list before continuing.

1: Prepare your CSV file

Create a CSV file with your user data. The following table lists some of the options for creating the file and why you would use each one.

Here’s an example of correctly-created file:

2: Upload the CSV file

On the user data import tool popup, upload the CSV file.

In the Upload file section, drag and drop, or browse to, your saved CSV file containing your user data edits.

3: Choose the file processing type

Select the processing method that PaperCut Hive or Pocket will use for this file. There are two options: test and import.

How test processing works

Test processing is a dry run (simulation) of the import process that checks for errors. Testing is always a good idea before proceeding with the real import.

A test differs from a true import in the following ways:

• No user data is changed in your PaperCut Hive or Pocket organization.
• No user invitations are sent to new users included in your CSV file.
• Your CSV file is run through the User data import tool, which collects any data errors along the way, including missing or incorrect data.

After you start a test, the test runs in the background — you don’t need to keep PaperCut Hive or Pocket open. Because the test is a simulation of an import, the time it takes to complete will vary, depending on the amount of data in your CSV file, for example:

• Testing 1,000 users takes approximately 20 seconds
• Testing 10,000 users takes approximately 4 minutes.

After the test is complete, a test report is available in the Activity Log for up to 7 days.

How import processing works

Import processing is a true data import. With this option, you’re uploading new data into your PaperCut Hive or Pocket organization and making permanent changes. Proceed with caution!

Before importing your CSV, you should always:

• test your file, and
• export user data.

Here’s what’s important to know:

• If your CSV file contains new users, and in step 4 below you select the Create new users and update existing users option, new users will be created.
• If your CSV file contains new users, and in step 4 below you select an invitation type to send to new users, new users will be invited.
• The data in your CSV file’s columns will be imported against the respective user records, overwriting any existing data in the user records.
• After you start the import, you cannot stop it or undo it. The import runs in the background — you don’t need to keep PaperCut Hive or Pocket open.
• Indicative import processing times:
  • 1,000 users: approximately 2 minutes
  • 10,000 users: approximately 20 minutes

When the import is complete, a report is available in the Activity Log for up to 7 days.

4: Define how users are handled

In this section, you let the import tool know how to handle your imported user data for both new and existing users.

In How do you want to apply imported user data?, you can select between the following options:

• Update existing users only: The tool ignores any new user rows in your CSV file, and only applies data updates to your existing users in PaperCut Hive or Pocket. This is particularly useful if you’re importing users from another system with inactive users in it, and don’t want these inactive users imported.
• Create new users and update existing users: The tool imports data from all user rows. If any new users exist in the CSV file, they will be created in PaperCut Hive or Pocket.

In New users - invitation type, select the system’s invitation behavior for any new users being created. From the dropdown, select one of the following options:

• Don’t send invitation emails: The system won’t send invitations to any new users. After the import has finished, these users appear in your Users list as “Invitation not sent”. This might be a good option if you’re staging your users and aren’t ready to invite them yet.
• Email a link to the User Portal: After the data for each new user is processed, they are immediately emailed a link to log into the User Portal.
• Email a classic invitation email: After the data for each new user is processed, they are immediately emailed a classic invitation email.

One of the email options is identified in the dropdown as your “organization default” — this is just reminding you of the default invitation type that applies to manually inviting users in your organization.

Finally, in Access Code email notification, select whether or not any existing users whose access codes have been changed will be automatically notified of this change via email. If selected, access code update notification emails are sent to existing users. The email notification type is based exclusively on the organization’s selected setting in Easy Print & Scan > User Invites > Default manual invitation email:

• If set to classic invitation: Affected users will receive their updated access code via email.
• If set to User Portal: Affected users will be notified to log into the User Portal to view their updated access code.

5: Start processing

Select Start processing to begin your test/import. You cannot pause or stop this process, and depending on your amount of imported data, it might take a long time to complete.

You can check the outcome of your test or import in the Activity Log.

Best practices for preparing and importing CSV files

Using CSV files is a powerful way to change large amounts of data — but it also requires a lot of attention to detail. To help you avoid some common pitfalls, here are some additional best practices:

• Delete any unnecessary columns from your CSV file, so that only the “active” columns remain in the file. (Bonus: this also helps speed up processing time in PaperCut Hive and Pocket.)
• If your end-users are already using PaperCut Hive or Pocket, plan to process the CSV file during a period of low activity to minimize any potential disruption. Remember to review results and run some tests after!
• Consider splitting your data into separate CSV files, for example a sample of ten rows, then the remainder of your data in a separate file. You can test, then import and validate smaller, ten rows file first, including checking that those ten users can print and use secure release. When you’re confident that your results are what you expected, test, import, and validate the remaining data. This is especially useful when changing end-users’ access card numbers.
• Consider splitting new users and existing users into separate CSV files.
• After the import has finished processing, it’s best practice to run some checks. In addition to reviewing the import results in the Activity Log, also review your Users list in the admin console, and deep-dive into some users’ details. A test print/scan and testing any access cards/access codes is also a good idea!

Viewing test or import results

Changing user data with the user data import tool is irreversible, so it’s always best to start with testing your CSV file and viewing the results. A results summary is also available when the CSV file is imported, rather than just tested.

When and where to view test or import results

Depending on how big your CSV file is, the results appear in the Activity Log in anywhere from minutes to hours. Use the link to download a file and view your results. The link is available for a maximum of 7 days from the test or import.

Interpreting test or import results

The Activity Log results for the test or import contains details on:

• how many rows have been processed
• how many users were created
• how many users were updated, and
• any rows with errors that were not processed, and the reason why.

(If the “test” option was selected, these user data edits are simulated only, and your organization’s real data is unchanged.)

Read through the results carefully to check that how PaperCut Hive or Pocket processed your CSV file is what you expected. Common things to check include:

• Do any user details appear strange, such as showing up as icons instead of letters? (To avoid this, ensure you use UTF-8 encoding.)
• The number of processed users matches the number of user rows in your source CSV file.
• The number of created users matches the number of new users in your source CSV file, and that each user has a unique email address (main unique identifier).
• How many errors and skipped rows exist — you’ll need to investigate these further and troubleshoot them. Refer to the Data format requirements carefully during troubleshooting.

Once you’ve understood the results, edit your CSV file to fix anything that needs amending. For reassurance, consider running another test with the updated file to check that everything now processes correctly before commencing a true import.

Known limitations

Although the user data import tool allows you to import or update users in PaperCut Hive or Pocket, there are a few limitations to be aware of:

• No user deletions: Users can’t be deleted via importing a CSV file. To delete users, either manually delete them via the Users page, or set up automatic deletion via an identity provider add-on.
• Access cards are additive only: Access card numbers imported via CSV file are added to a user’s data in PaperCut Hive and Pocket. If a user already has access card numbers and then new ones are imported via CSV, the user will be associated with both the original and new card numbers after the import.
• Access cards cannot be individually modified or removed: Entering a “-” in any of the 5 available card number columns in the CSV template instructs the User Data Import tool to remove all previously added card numbers from the user. This includes card numbers synchronized from an IdP, self-associated card numbers, and those added from prior CSV imports. It is strongly recommended that you export user data before using the User Data Import tool to add or remove any card numbers so that you have a backup of card number values should you need to restore them later — refer to the Removing or Restoring Card Numbers section below.
• Specific progressive updates during tests or imports: On the Import user data (CSV) popup, after you select Start processing, the test or import will immediately start. This is noted in the Activity Log, along with the time that the test or import completes. Progressive updates during processing include:
  • New user created - in Activity Log
  • Generic note that an existing user’s details have changed (for example, card number change) - in Activity Log
  • Access code change - in Activity Log
  • Balance adjustment source note - in Transactions Log (including in User Portal view, if enabled)
• PaperCut NG/MF exported User List CSV translated column names must be updated to English: Any non-English language column names must be changed to their English language equivalents listed in the Data format requirements . Any other column names will cause an error.
• PaperCut NG/MF Internal users are created as standard users: When exporting your User List from PaperCut NG/MF, any “Internal users” are included. If imported to PaperCut Hive or Pocket, these Internal users will be created as standard end-users.
• Some PaperCut NG/MF user data is imported but stored only: The PaperCut NG/MF User List export CSV file includes columns that are not used by PaperCut Hive or Pocket. These data are imported but stored only, and are not visible in the PaperCut Hive or Pocket admin console. These columns are:
  • [PaperCut Pocket only] Card numbers
  • Username
  • Department
  • Office
  • Created by date
  • Total printed page
  • Notes
  • Last activity
  • Other emails
  • Username alias
  • Internal user
  • Jobs

Removing or Restoring Card Numbers

There are two methods for removing unwanted card numbers from a user:

1. Delete each individual card number manually via the admin console: Users > [user email address] > User access > Access Cards, then select the trash icon.
   
2. Using the User Data Import tool, enter a “-” in any of the card number columns within the user’s row to remove all card numbers associated with the user.

If an organization wishes to use the User Data Import tool to:

• remove only certain card numbers from multiple users whilst retaining those users’ other card numbers, or
• restore to a prior set of card numbers after accidentally importing unwanted card numbers

…the following steps can be taken during a period where card number user login to MFDs will not be impacted (ideally outside of business hours):

1. Export user data from PaperCut Hive. Retain this export as a backup of current card numbers.
2. Create a copy of the backup user data export CSV.
3. In the copy, remove the values from all card number columns for the desired users.
4. For the same users, in column Card number 1, enter a “-”. This value instructs the User Data Import tool to remove all card numbers associated with the users.
5. Import the copy with the User Data Import tool. When the import completes, all the desired users will no longer be associated with any card numbers — card numbers will remain unchanged for users whose rows were not modified.
6. Create another copy of the backup user data export CSV.
7. In the new copy, remove only the unwanted card number values from the desired users.
8. Import the new copy with the User Data Import tool. When the import completes, all the desired users will be associated with only the card numbers specified in the new copy.

Frequently asked questions

Can I update an existing user's email address with the user data import tool?

No. The email address is a user's unique identifier in PaperCut Hive and Pocket. Adding a new email address against an existing user's name will create a new user.

Can I delete users with the user data import tool?

Not yet. Right now, users can be added or updated with the user data import tool. However, we're working on user deletion via CSV/TSV file, and this will be available soon.

Do I need to enable Cost Tracking before importing user balances or restricted users?

Enforcing balances and restrictions requires enabled Cost Tracking and Cost Profiles in PaperCut Hive or Pocket. Before you import user balances or user restriction statuses, set up Cost Tracking.

I'm doing a new installation. When should I prepare my user data?

If you're planning on installing PaperCut Hive or Pocket for the first time, preparing your CSV/TSV file in advance will make things smoother on installation day! You'll already have all the data types you need ready to import, without having to locate it all under pressure. If your PaperCut Authorized Partner has sent you a template, just follow the instructions on this page to fill it out.

If I sync users from an Identity Provider, will this override my imported user data?

Yes. Data imported by CSV/TSV is a one-time import. If you have an ongoing sync from a Identity Provider (IdP), any conflicting user will be overridden by data in the IdP next time the sync occurs.

Will user data I removed with the user data import tool be re-added by a user sync Add-on?

Let's say you have automatic user syncing set up from your identity provider via a user sync Add-on, and this synced data includes access cards. You then use the user data import tool to remove all of your users' access cards.

In this situation, next time the Add-on syncs with PaperCut Hive or Pocket, the access card numbers will be re-added against your users. To avoid this happening, you'll need to make changes to your Add-on or IdP.

Can I use column names in languages other than English?

No, column names must be in English and must be an exact match with the column names in the Data format requirements.

Can I import Shared Accounts from PaperCut NG/MF?

Importing Shared Accounts is currently not supported.