workspace sdk credential readers

About credential readers

Credential readers capture credential data from external hardware such as card readers, biometric scanners, and access control devices. They integrate into Security Center's credential management workflows for creating new credentials and retrieving existing ones.

Security Center natively supports common credential readers such as USB desktop card readers and door-based card swipe detection. Use custom credential readers when you need to capture credential data from hardware or protocols that Security Center does not natively support. Examples include:

• Capturing biometric data from a fingerprint or palm vein scanner.
• Reading credentials from a proprietary smart card protocol.
• Receiving mobile credentials through a custom NFC or Bluetooth protocol.

The SDK provides two base classes:

• CredentialReader for general-purpose credential reading.
• CardholderCredentialReader for readers that need to know which cardholder the credential is being assigned to.

How credential readers work

Credential readers appear in both Security Desk and Config Tool. The system presents registered readers when an operator performs credential operations such as adding a credential from a cardholder's page, opening the credential management task, or returning a card. The system manages the full lifecycle:

1. The module registers the credential reader with the workspace during Load.
2. When a credential workflow opens, the system filters available readers by calling SupportsOperationMode(). OperationMode is mutable context and can be assigned during reader selection or changed later.
3. The system calls CreateView() to obtain the reader's interface and displays it in the credential management dialog.
4. The system calls Activate() to start the reader, which begins listening for hardware events.
5. When the reader detects a credential, it raises CredentialRetrieved (new credential) or ExistingCredentialRetrieved (existing credential in the system).
6. The system reads the credential data from the event arguments.
7. The system calls Deactivate() when the workflow completes, and Dispose() to release resources.

For CardholderCredentialReader, CardholderId is always null while Activate() runs. When the workflow supplies a cardholder, the system assigns CardholderId after activation and raises CarholderIdChanged each time the value changes, including when it is cleared. Handle CarholderIdChanged, or read CardholderId at the moment you need it, instead of checking it in Activate().

CredentialReader

Inherit from CredentialReader and implement the abstract members:

public class MyCredentialReader : CredentialReader
{
    public override string Name => "My Credential Reader";

    public override Guid UniqueId => new Guid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890");

    public override bool IsValid => m_isConnected;

    public override OperationMode OperationMode { get; set; }

    public override bool SupportsOperationMode(OperationMode mode)
    {
        return mode == OperationMode.Creation
            || mode == OperationMode.Retrieval;
    }

    public override UIElement CreateView()
    {
        return new MyReaderControl();
    }

    public override void Activate()
    {
        // Start listening for credential scans
    }

    public override void Deactivate()
    {
        // Stop listening for credential scans
    }

    public override void Dispose()
    {
        // Release hardware resources
    }
}

CredentialReader members

Member	Type	Description
Name	Property (abstract)	Display name shown for the reader.
UniqueId	Property (abstract)	Unique identifier for this reader component.
IsValid	Property (abstract)	Whether the reader is in a valid state and ready to read credentials.
OperationMode	Property (abstract)	The current operation mode of the reader.
Priority	Property (virtual)	Display order when multiple readers are available. Lower values appear first. Defaults to int.MaxValue.
Activate()	Method (abstract)	Called when the reader is activated. Start listening for credential scans.
Deactivate()	Method (abstract)	Called when the reader is deactivated. Stop listening for credential scans.
CreateView()	Method (abstract)	Create the reader's visual interface. Returns a new UIElement each time it is called.
SupportsOperationMode(OperationMode)	Method (abstract)	Return true when the reader supports the specified operation mode.
Dispose()	Method (abstract)	Release resources used by the reader.

Raising credential events

When the reader detects a credential, raise the appropriate event:

// New credential detected
var format = new WiegandStandardCredentialFormat(FACILITY_CODE, CARD_NUMBER);
OnCredentialRetrieved(new CredentialRetrievedEventArgs(format));

// Existing credential detected
OnExistingCredentialRetrieved(new ExistingCredentialRetrievedEventArgs(credentialGuid));

Event	Description
CredentialRetrieved	Raised when a new credential is detected. The CredentialRetrievedEventArgs contains the CredentialFormat data.
ExistingCredentialRetrieved	Raised when an existing credential is detected. The ExistingCredentialRetrievedEventArgs contains the credential entity Guid.

OperationMode

The system uses SupportsOperationMode() to filter readers for the active workflow. OperationMode is mutable context and can be assigned during reader selection or changed later. Do not assume it has its final value when Activate() runs. Read its current value when handling a scan.

Value	Workflow	Description
Creation	Adding a new credential to a cardholder	The reader produces new credential data. If the detected credential already exists in the system, the workflow rejects it.
Retrieval	Returning a card, finding a visitor by credential	The reader identifies an existing credential. If the detected credential is not found in the system, the workflow rejects it.
BatchCreation	Enrolling multiple credentials in a single session	The reader produces new credential data in a batch enrollment page.
All	General credential management with both creation and retrieval rights	The reader accepts both new and existing credentials.

CardholderCredentialReader

CardholderCredentialReader is an alternative base class for readers that need cardholder context. It shares the same abstract members and events as CredentialReader, but adds a CardholderId property that the system sets when the reader operates within a cardholder workflow, such as adding a credential from a cardholder's page.

Use CardholderCredentialReader instead of CredentialReader when the reader's behavior or interface depends on which cardholder is being enrolled. For example, a reader can query the cardholder's existing credentials to prevent duplicate enrollment or display the cardholder's name in its interface for operator confirmation.

public class MyCardholderReader : CardholderCredentialReader
{
    // Implement the same abstract members as CredentialReader

    public MyCardholderReader()
    {
        CarholderIdChanged += OnCardholderIdChanged;
    }

    public override void Activate()
    {
        // CardholderId is always null at this point.
        // Start listening for credential scans.
    }

    private void OnCardholderIdChanged(object sender, Guid? cardholderId)
    {
        if (cardholderId.HasValue)
        {
            // The workflow now operates within a cardholder context.
        }
    }

    public override void Dispose()
    {
        CarholderIdChanged -= OnCardholderIdChanged;
        // Release hardware resources
    }
}

CardholderCredentialReader members

Member	Type	Description
CardholderId	Property (Guid?)	The contextual cardholder identifier. null when the reader is not loaded in a cardholder context.
CarholderIdChanged	Event	Raised when the contextual cardholder identifier changes. Note: the event name in the SDK is spelled CarholderIdChanged (missing 'd').

Registering a credential reader

Important

This component requires a valid SDK certificate.

Register the reader in your module's Load method:

public class SampleModule : Module
{
    private MyCredentialReader m_reader;

    public override void Load()
    {
        m_reader = new MyCredentialReader();
        m_reader.Initialize(Workspace);
        Workspace.Components.Register(m_reader);
    }

    public override void Unload()
    {
        if (m_reader != null)
        {
            Workspace.Components.Unregister(m_reader);
        }
    }
}

See also

• About the Workspace SDK: Workspace SDK architecture and module lifecycle.
• About components: The component registry and registration lifecycle.
• About credential encoders: Sending credential data to external encoding hardware.
• About Workspace SDK certificates: Certificate requirements for workspace components.