Converting access card numbers

About access card number conversion

Access cards (also known as swipe cards or security cards) are one of the ways PaperCut Hive users can access MFDs with full embedded apps to release print jobs and more. Access cards can be added to PaperCut Hive in a variety of ways:

• Users self-associating access cards by swiping them at the MFD, then following the self-association process.
• Syncing access cards stored in an identity provider (such as Microsoft Entra ID or Google Workspace) via a user sync Add-on.
• Importing access cards in a CSV or TSV file using the Import User Data tool.

If users self-associate access cards, the MFD’s card reader will always read the card correctly. However, access card numbers from external systems — like door access card systems, PaperCut MF imports, or synced data from an identity provider — may require card number conversion before PaperCut Hive can match the access card to the user.

This article covers all you need to know about access card number conversion, including:

• Scenarios when access cards might not match in PaperCut Hive
• How to identify if you need to convert access cards
• How to develop an access card conversion formula
• How to implement access card conversion in PaperCut Hive

Scenarios when access cards might not match in PaperCut Hive

There are two main scenarios for when you might need to do an access card number conversion:

• Your users were brought into PaperCut Hive in bulk with the potential for card number mismatch and you don’t want your users to self-associate access cards. This might be via importing users in a CSV/TSV file, or by syncing users from an Identity Provider.
• You have a mixed fleet of devices/card readers that provide different values for a single card. You want to prevent a user from having to self-associate the same access card multiple times.

Here are more details about scenarios that might cause you to need to add an access card conversion formula to your MFDs.

Users imported via CSV/TSV

Administrators can use the Bulk User Data Import tool to import up to five access card numbers per user using a CSV or TSV file. These imported access card numbers often come from other print management software solutions, including PaperCut NG/MF. Without applying conversions, these access card numbers might be read differently in PaperCut Hive, for example, because an administrator applied conversions in the previous product, or changed card readers/MFDs.

If conversions are not applied in PaperCut Hive, the access card data will not match the users’ records. Users must perform self-association at the MFD to use their access cards. Adding an access card conversion formula to the MFDs avoids this need to self-associate, so users have a low-touch print experience.

Synced card numbers from Microsoft Entra ID or Google Workspace

With PaperCut Hive, you can automatically sync your users from Microsoft Entra ID and Google Workspace with a user sync Add-on. At the same time, you can also sync the users’ access card numbers. For more information, refer to:

• Sync users from Microsoft Entra ID
• Sync users from Google Workspace

These access card numbers have originally come from another source, such as a door access system, and have been added to the user directory. Therefore, when the card is swiped at the MFD, the raw string provided might be different from the value in the user directory.

In this instance, a conversion can be applied in PaperCut Hive to match the value from the card reader to the value in the user directory. This way, users can simply swipe to print without needing to self-associate their access cards.

Multi-brand MFD environment

In multi-brand MFD environments, there may also be a card number reading mismatch. This is because the access cards might be read correctly by one brand of MFD, but read incorrectly by another brand of MFD. Without using access card conversion, users will be able to use their access cards on one brand, but be asked to self-associate the access card on the other brand.

To avoid user confusion about why their access cards only work without self-association on some MFDs, add an access card conversion formula to any MFDs that aren’t reading the access card correctly.

How to identify if you need to convert access cards

If you’re in an environment that might require access card conversion, the first thing to do is figure out whether or not it’s actually required. To do this, you need to find out if there’s a difference between the access card numbers as read by the card reader, and the access card number stored in your users’ profiles in PaperCut Hive.

Here’s how it’s done.

1. Determine the raw card number

There are two main ways to determine the raw access card number string:

• check the Activity Log
• self-associat an unknown access card with a user.

Option 1 (recommended) — Retrieve the raw access card number via the Activity Log

1. Enable Diagnostic Mode in your PaperCut Hive organization. Learn how to enable Diagnostic Mode.
2. Make sure no access card number conversions are set, then swipe an unknown card at the MFD.
3. If the value is unknown, do not self-associate the card.
4. Log in to the PaperCut Hive admin console, then go to Logs > Activity Log.
5. In the Activity Log, find the unknown card swipe message that matches the device and time of card swipe. The message format is:
   “Unknown card swiped at MFD <MFD Name>. Card number: <XXXXXXX>.”
   The raw card number is the value of XXXXXXX.
6. Note down the raw data string.

Option 2 — Self-associate an unknown card at the MFD

1. Make sure no access card number conversions are set, then swipe an unknown card at the MFD.
2. If the value is unknown, the MFD will ask you to associate the access card. Self-associate the card by logging in with test user credentials.
3. Log in to the PaperCut Hive admin console, then go to Users > Select your test user > User access.
4. Under Access Cards, the raw data read by the MFD is displayed. Note down this raw data string.
5. Delete the access card number from the test user profile.

2. Compare the raw card number to the PaperCut Hive card number

The next step is to compare the raw data string (the number of the tested access card) against the user’s access card number string in your user’s records.

If the two strings are the same: PaperCut Hive is reading the access card number correctly. There is no need to add an access card conversion formula to the printer.

If the two strings are different: PaperCut Hive is not successfully matching the access card number. Add an access card conversion formula to the printer. Continue reading to learn how to implement access card conversion by:

1. Developing a formula telling PaperCut Hive how to convert the raw card number into the PaperCut Hive card number stored in the user’s profile.
2. Adding the formula to the relevant MFDs in PaperCut Hive.
3. Testing and rolling out the access card conversion throughout your environment.

How to develop an access card conversion formula

About access card conversion formulas

Now that you know how there’s a difference between how the MFD reads the card (the raw card number string) and what the output needs to be (the user’s access card number in PaperCut Hive), you can work on the conversion formula.

Adding this card number conversion formula to PaperCut Hive means that when your users swipe their access cards, PaperCut Hive will transform the raw card string to match the user’s access card number. Conversion formulas can be as simple as taking the raw data string from the card reader and capitalizing the letters, or as complex as applying multiple conversions and regular expressions in one go.

To develop the formula, you need to use one or more of the following available conversions to transform the raw card number into the user’s access card number.

Access card conversion types available to use in your formula

When developing your formula, use one or more of the following access card conversion types. Please note the conversion type is case sensitive.

Advanced: Piping conversions in your formula

For some access card numbers, a single conversion might not be enough to match the required output. Instead, to get the required output, you can perform piping in your access card conversion formula. Piping allows you to queue up multiple conversions to take place one after the other.

To pipe conversions, use the | character (often known as a ‘vertical bar’ or ‘pipe’) between conversion commands.

Conversions that are piped are applied sequentially. This means that the first conversion is applied, then the second conversion is applied to the result of the first conversion.

Example:

• Conversion: Hex2Dec|Regex:(\d{6}):Regex
• Input: ABC123
• Process: The conversion first changes ABC123 to 11256099 using Hex2Dec. The regex (\d{6}) then extracts the first 6 numbers.
• Final Result: 112560

You can pipe as many conversions as you need to correctly transform the access card number string. However, applying more conversions increases complexity and the probability of mistakes.

How to implement access card conversions in PaperCut Hive

How to add an access card conversion formula to a printer

Now that you have your access card conversion formula, it’s time to add it to an MFD:

1. Log in to the PaperCut Hive admin console.
2. In the left menu, select Printers.
3. Select the MFD to which you want to apply the conversion formula.
4. Select the Apps tab.
5. Under Card reader, select Swipe card.
6. Next to Converter, select Edit.
7. In the Formula field, enter your required conversion.
8. Select Apply formula.

How to test and troubleshoot your access card conversion formula

After you have added an access card conversion formula to a printer, you need to test that it is working correctly and matching your imported access card numbers:

• You successfully log in to the MFD.
  Congratulations, your access card conversion formula is working correctly on this MFD. If you have more MFDs that require access card conversion formulas, it’s time to take care of them. You can check the converted access card number in the users profile under the User Access tab. Remember to check all combinations of MFD, card reader, and access cards, as they might not all be the same.

• You are prompted to self-associate again.
  This means one of two scenarios has occurred:
  - The conversion has failed due to an incorrect formula: In the Activity Log, the log message will still contain the raw card number string. Check your conversion formula to identify any spelling mistakes, conflicts, or other errors. Update your conversion formula, add it to PaperCut Hive, then test again.

  - The access card value has been converted, but does not match the value in the user’s profile: In the Activity Log, the log message will contain the converted (but unassociated to a user) card number string. This means the conversion formula was successfully used by PaperCut Hive, but the output access card string did not match the user’s imported/synced access card number. Update your conversion formula, add it to PaperCut Hive, then test again.

If you are having difficulty troubleshooting access card number conversion, please contact your PaperCut Authorized Partner for support.