Authentication (Card Reader) controls how OptimiDoc turns the number a proximity card presents at a device into a value it can match to a user. You pick the reader type, build a card-number conversion pipeline, and — for HP CZ208A readers — choose which badge formats the reader should decode. A built-in wizard works out the right conversion for you from a few sample cards.
Overview
Many organisations authenticate users at MFP devices with proximity cards (HID, Mifare, FeliCa and similar). When a user taps a card, the reader sends a number to OptimiDoc, which must match it to a user account. Different readers and card technologies emit that number in different shapes — decimal, hexadecimal, byte-reversed, zero-padded — so OptimiDoc runs the raw value through a card conversion pipeline to produce the form stored against the user.
Accessing Authentication Settings
-
Open the React administration interface as an Admin user.
-
Go to Settings in the left sidebar (route
/config). -
Select the Authentication tab.
Card Reader Type
The Card reader type selector (labelled "HP only" in the interface) tells OptimiDoc how the reader hardware behaves. Most MFP built-in readers use Other and rely entirely on the conversion pipeline; the HP options apply a fixed, reader-specific normalisation before the pipeline runs.
|
Option |
Description |
|---|---|
|
Other |
No hardware-specific handling. The raw value goes straight into the conversion pipeline. Use this for most USB and built-in MFP readers. |
|
HP CZ208A |
HP's CZ208A USB reader. Strips the reader's fixed prefix (the nine-character |
|
RF Ideas |
An RF IDEAS reader handled with the legacy HP (CE931A) semantics — it trims the first three characters the reader emits before the pipeline runs. |
Card Conversion
The field is labelled Card conversion in the interface, with help text describing the pipeline syntax. It is not a regular expression — it is a small conversion pipeline language, described below. In 26.07 and earlier the field was mislabelled Card conversion regex; it never accepted regular expressions.
The card conversion is a sequence of conversion steps applied left to right. Semicolons (;) chain steps one after another; a plus (+) concatenates the outputs of parallel steps. Each step is a named primitive, some taking arguments, for example:
|
Primitive |
Effect (example) |
|---|---|
|
|
Replace each character with its hexadecimal code. |
|
|
Interpret the value as hexadecimal and output its decimal form. |
|
|
Reverse the string, or swap adjacent byte pairs (endianness). |
|
|
Take a substring from a start position for a length ( |
|
|
Bitwise-AND the value with a hexadecimal mask. |
|
|
Pad on the left with a character to a fixed width. |
|
|
Insert a constant, compute a checksum byte, and so on. |
A complete conversion is just these joined together — for instance ASCII2Hex;Hex2Dec reads the raw ASCII digits as hexadecimal and outputs decimal. There are around three dozen primitives in total; rather than memorise them, use the wizard below to find a working pipeline from sample cards.
Card Type 1 and Card Type 2 (HP CZ208A only)
These fields appear only when the reader type is HP CZ208A. They are numeric badge-format codes (HP's "HpCodes") that tell the reader which of its Wiegand badge-format profiles to decode; OptimiDoc sends them to the reader as an HID feature command. Set Card Type 1 for a single card technology, and use Card Type 2 as well when a site mixes two technologies. They have no effect with other reader types.
Card Conversion Wizard
The wizard finds a conversion for you when you know what a card reads as raw and what it should become, but not the formula between them.
Using the Wizard
-
Click Conversion Wizard next to the Card Conversion field.
-
Enter up to three Input / Expected Output pairs:
-
Input — the raw value the reader sends (recent raw values appear in Unauthorised Accesses).
-
Expected Output — the value as it is stored on the user.
-
-
Optionally seed a candidate in Conversion to test.
-
Click Evaluate.
Interpreting Results
OptimiDoc runs your samples through a library of about 196 known conversion pipelines and groups the results:
-
Exact conversion — pipelines that reproduce every expected output precisely. These are the ones to use.
-
Approximate conversion — pipelines that come close, ranked by how far their output is from the expected value (edit distance). Useful as a starting point when nothing matches exactly.
Select a result and click Select to drop it into the Card Conversion field, then Save.
Registering Cards to Users
Administrator Assignment
-
Obtain the (converted) card number — from the card or from the Unauthorised Accesses log.
-
Open the user's profile in Users, enter the value in the Card field and save.
Self-Registration via Unauthorised Accesses
-
The user taps an unregistered card at a device.
-
The value appears in Unauthorised Accesses.
-
An administrator opens the entry, assigns it to a user and confirms.
Login Protection
OptimiDoc does not lock individual accounts after failed logins. Instead, the login endpoint throttles by source address: more than five invalid attempts from the same IP within a rolling five-minute window are rejected with Too many invalid login attempts (HTTP 403). The counter is held in memory and clears as the window passes.
Tips
-
Read raw card values from Unauthorised Accesses and feed them straight into the wizard.
-
Validate a candidate conversion against several cards before rolling it out.
-
If a site mixes card technologies, provide the wizard with a sample from each so the chosen pipeline handles them all.
In Summary
Pick the reader type (usually Other), then let the wizard derive a card conversion pipeline from a couple of sample cards rather than writing one by hand. For HP CZ208A hardware, also set the Card Type badge-format codes. Once a card's converted value matches what is stored on the user, tapping the card logs that user in.
Related articles