workspace sdk badge printers

About badge printers

Badge printers integrate custom badge printing hardware with Security Center's cardholder management. They handle printing ID badges and can optionally encode credential data onto smart cards during the print operation.

Use badge printers when you need to support specialized badge printing hardware or add credential encoding capabilities. Examples include:

• Sending badge designs to a dedicated ID card printer with encoding support
• Encoding access credentials onto smart cards as part of the badge printing workflow
• Enrolling new credentials by reading data from blank cards during printing

How badge printers work

1. The module registers a BadgePrinter with the workspace during Load.
2. The system discovers available printers and sorts them by Priority.
3. The operator selects a printer when printing a badge from the cardholder's credential list.
4. When the operator prints a badge, the system checks SupportsEncoding:
   • If false, the system calls Print() with the credential, badge, and cardholder identifiers.
   • If true, the system calls PrintAndEncode() with the badge document and credential format data.
5. For enrollment workflows, the system calls PrintAndEnroll() and uses the returned BadgePrinterEnrollResult to create the credential. Enrollment is offered only for printers that return SupportsDecoding = true.
6. The operator's printer selection is persisted across sessions.

The paper-badge printing dialog offers only the built-in printer. Custom BadgePrinter components do not appear in that dialog.

BadgePrinter

Inherit from BadgePrinter. You must override Name and UniqueId; override Print, PrintAndEncode, or PrintAndEnroll for the operations your printer supports.

public class MyBadgePrinter : BadgePrinter
{
    public override string Name => "My Badge Printer";

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

    public override bool Print(Guid credential, Guid badge, Guid cardholderGuid)
    {
        // Send the badge to the printer
        return true;
    }
}

BadgePrinter members

Member	Type	Description
Name	Property (abstract)	Required override. Display name shown in the printer selection list.
UniqueId	Property (abstract)	Required override. Stable GUID that identifies the printer; used to persist and restore the operator's selection across sessions.
Priority	Property (virtual)	Display order when multiple badge printers are available. Lower values appear first. Defaults to int.MaxValue.
SupportsEncoding	Property (virtual)	Whether the printer supports encoding credentials onto badges. Defaults to false.
SupportsDecoding	Property (virtual)	Whether the printer supports decoding credentials from badges. Defaults to false.
Print(Guid, Guid, Guid)	Method (virtual)	Print a badge. Receives the credential identifier, badge identifier, and cardholder identifier. Return true on success.
PrintAndEncode(BadgePrinterEncodingData)	Method (virtual)	Print and encode a badge. Override when SupportsEncoding returns true. Return true on success.
PrintAndEnroll(BadgePrinterPrintData)	Method (virtual)	Print a badge and enroll the credential. Override when SupportsDecoding returns true. Returns a BadgePrinterEnrollResult.

Print data types

The badge printer APIs use different payload types depending on whether you only print, print and encode, or enroll a credential during the workflow.

BadgePrinterPrintData

Provides the information needed to print a badge.

Member	Type	Description
Document	FixedDocument	The badge document to send to the printer.
CardholderGuid	Guid	The cardholder's identifier. Returns Guid.Empty if the cardholder is not found.

BadgePrinterEncodingData

Extends BadgePrinterPrintData with credential format information for encoding operations.

Member	Type	Description
Credential	CredentialFormat	The credential's format data to encode onto the badge.

BadgePrinterEnrollResult

Represents the result of a print and enroll operation.

Member	Type	Description
Succeeded	bool	Whether the enrollment succeeded.
Credential	CredentialFormat	The credential's format data from the enrollment.

Registering a badge printer

Important

This component requires a valid SDK certificate.

Register the printer in your module's Load method:

public class SampleModule : Module
{
    private MyBadgePrinter m_printer;

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

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

See also

• About the Workspace SDK: Workspace SDK architecture and module lifecycle.
• About components: The component registry and registration lifecycle.
• About workspace modules: Workspace module class and Load/Unload lifecycle.
• About Workspace SDK certificates: Certificate requirements for workspace components.