workspace sdk cardholder fields extractors

About cardholder fields extractors

Cardholder fields extractors are components that import cardholder data from external sources into Security Center. When a user creates or edits a cardholder, the system provides an import option that lists available extractors. Each extractor represents a different data source: HR systems, vCard contact files, badge databases, or custom integrations.

Cardholder fields extractors appear in the cardholder configuration page in Config Tool and Security Desk. The system filters available extractors based on availability and displays them ordered by priority.

Common use cases include:

• HR integration: Import employee name, email, photo, and group assignments from HR systems.
• vCard import: Extract contact information from standard vCard (.vcf) files.
• Badge system migration: Import cardholder data and credentials from legacy badge systems.

How cardholder fields extractors work

A cardholder fields extractor is a workspace component that you initialize and register from your module. After registration, Security Center evaluates availability and priority to populate the import menu on the cardholder page.

When the operator selects the extractor, the SDK calls GetFields(CardholderFieldsExtractorData) and applies the returned CardholderFields values to the current cardholder form.

CardholderFieldsExtractor

Inherit from the CardholderFieldsExtractor base class and implement the required abstract members. The following example creates an extractor that imports cardholder data from vCard (.vcf) contact files, a common format for employee data exported from HR systems.

public class VCardFieldsExtractor : CardholderFieldsExtractor
{
    public override Guid UniqueId { get; } = new("88F33E43-1E51-4504-95BF-ADD2FBCBA8AD");

    public override string Name => "Read vCard...";

    public override CardholderFields GetFields(CardholderFieldsExtractorData data)
    {
        var dialog = new OpenFileDialog
        {
            Filter = "vCard files (*.vcf)|*.vcf|All files (*.*)|*.*",
            Title = "Open vCard File"
        };

        if (dialog.ShowDialog() != true)
            return null;

        VCard vCardInfo = VCardReader.ReadVCard(dialog.FileName);
        if (vCardInfo != null)
        {
            return new CardholderFields
            {
                FirstName = vCardInfo.FirstName,
                LastName = vCardInfo.LastName,
                Email = vCardInfo.Emails.FirstOrDefault(),
                Picture = vCardInfo.Picture,
                Description = vCardInfo.Note
            };
        }

        return null;
    }
}

When an operator clicks the import option and selects Read vCard..., the extractor opens a file dialog, parses the selected vCard file, and returns the extracted fields to populate the cardholder record.

CardholderFieldsExtractor required members

Member	Description
UniqueId	A GUID that uniquely identifies this extractor. Generate a new GUID for each extractor type.
Name	The display text shown in the import menu. Include an ellipsis (...) if the extractor shows a dialog.
GetFields(CardholderFieldsExtractorData)	Called when the user selects this extractor. Display any required UI, extract data from the external source, and return a CardholderFields object, or null if cancelled.

CardholderFieldsExtractor optional members

Member	Default	Description
Icon	Import icon	The icon shown next to the name in the menu.
Priority	int.MaxValue	Controls menu ordering. Lower values appear first.
IsAvailable	true	Set to false to hide the extractor from the import menu.

GetFields

The GetFields method is called on the UI thread when the user selects your extractor from the import menu. The method receives a CardholderFieldsExtractorData parameter containing the GUID of the cardholder being edited.

Return null if the user cancels the operation or if the data cannot be extracted. The system handles null returns gracefully and leaves the cardholder unchanged.

Fields left as null in the returned CardholderFields object do not override the existing values on the cardholder. Set only the fields you want to update.

Important

The GetFields method runs on the UI thread. For long-running operations like network requests or database queries, display a progress dialog to keep the application responsive.

CardholderFields properties

The CardholderFields class defines the cardholder data that an extractor can populate. Set only the properties you want to update.

Member	Type	Description
FirstName	string	The cardholder's first name
LastName	string	The cardholder's last name
Email	string	The cardholder's email address
Description	string	The cardholder's description
Picture	ImageSource	The cardholder's photo
CustomFields	IDictionary<Guid, object>	Custom field values keyed by custom field GUID. Read-only and initialized to an empty dictionary; add entries to it directly (fields.CustomFields[fieldId] = value) rather than assigning a new dictionary.
CardholderGroups	List<Guid>	Cardholder groups to assign. null by default; assign a list before adding groups.
BadgeTemplate	Guid?	Badge template to associate
ExpirationDate	DateTime?	The cardholder's expiration date
Credentials	List<CredentialFields>	Credentials to display in the cardholder editor. A supplied list replaces the current list; an empty list clears it. Leave null to preserve the current list.

Populating credentials

Assign a List<CredentialFields> to Credentials containing all credentials you want listed in the cardholder editor after import. Include existing credentials you want to retain by setting their CredentialGuid.

Member	Type	Description
CredentialGuid	Guid?	GUID of an existing credential to update
CredentialType	CredentialType?	The type of credential
RawData	string	Raw credential data
BitLength	uint?	Bit length of the credential
FriendlyName	string	Display name for the credential
CustomFields	IDictionary<Guid, object>	Custom field values for the credential. null by default; assign a new dictionary before adding entries.
Description	string	Credential description
ExpirationDate	DateTime?	Credential expiration date (UTC)
ActivationDate	DateTime?	Credential activation date (UTC)
CreationDate	DateTime?	Credential creation date (UTC)

Priority and menu ordering

Extractors appear in menus ordered by their Priority property. Lower values appear first.

public override int Priority => 200;

The default priority is int.MaxValue, which places unspecified extractors at the end of the menu.

Registering a cardholder fields extractor

Register your extractor in the module's Load method and unregister it in Unload.

public class SampleModule : Module
{
    private VCardFieldsExtractor m_extractor;

    public override void Load()
    {
        if (Workspace.ApplicationType is ApplicationType.SecurityDesk or ApplicationType.ConfigTool)
        {
            m_extractor = new VCardFieldsExtractor();
            m_extractor.Initialize(Workspace);
            Workspace.Components.Register(m_extractor);
        }
    }

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

The extractor becomes available immediately after registration and appears in the import menu on the cardholder configuration page.

Note

Cardholder fields extractors require a certificate file to load. See About Workspace SDK certificates for certificate requirements.

Dynamic availability

Extractors appear in the import menu by default. Set IsAvailable to false to hide an extractor when it cannot run.

protected override void Initialize()
{
    // Hide the extractor based on a condition
    IsAvailable = CheckRequiredCondition();
}

When IsAvailable is false, the extractor does not appear in the import menu.

CardholderFieldsExtractor members

Member	Type	Description
UniqueId	Property (abstract)	Gets the unique identifier for this extractor
Name	Property (abstract)	Gets the display name shown in menus
Icon	Property (virtual)	Gets the icon shown in menus. Default is the import icon.
Type	Property	Gets the component type GUID (always Components.CardholderFieldsExtractor)
Priority	Property (virtual)	Gets the menu ordering priority. Default is int.MaxValue.
IsAvailable	Property	Gets or sets whether the extractor appears in the import menu. Default is true.
Workspace	Property	Gets the workspace after initialization
GetFields(CardholderFieldsExtractorData)	Method (abstract)	Called to extract cardholder fields. Returns CardholderFields or null.
Initialize()	Method (virtual)	Override to perform setup. Called when Initialize(Workspace) is invoked.

See also

• About the Workspace SDK: Workspace SDK architecture and module lifecycle.
• About components: The component registry and registration lifecycle.
• About credential readers: Reading credential data from external hardware.
• About Workspace SDK certificates: Certificate requirements for workspace components.