workspace sdk image extractors

About image extractors

Image extractors are components that provide images from external sources for use in Security Center. When a user needs to set an image (cardholder photo, entity thumbnail, or custom field value), the system displays a menu of available image extractors. Each extractor represents a different image source: file system, clipboard, webcam, camera snapshot, or custom hardware like signature pads and scanners.

Image extractors appear in image selection controls throughout Config Tool and Security Desk. The system filters available extractors based on context and displays them ordered by priority.

Common use cases include:

• Data import: Import cardholder photos from HR systems, vCard contact files, or employee databases
• Hardware integration: Capture images from signature pads, document scanners, or badge cameras
• Custom workflows: Load images from specific network locations or apply organization-specific processing

How image extractors work

An image extractor is a workspace component that you initialize and register from your module. After registration, Security Center evaluates SupportsContext(ImageExtractorContext) and Priority to decide which extractors to show in each image-selection workflow.

When the operator selects the extractor, the SDK calls GetImage() and uses the returned ImageSource as the selected image.

ImageExtractor

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

public sealed class VCardImageExtractor : ImageExtractor
{
    public override Guid UniqueId { get; } = new("5EDBB0B6-8253-433E-99A1-9021E498437A");

    public override string Name => "Load from vCard...";

    public override ImageSource Icon { get; } = new BitmapImage(new Uri("pack://application:,,,/ImageExtractorSample;Component/Resources/Icon.png", UriKind.RelativeOrAbsolute));

    public override ImageSource GetImage()
    {
        var dialog = new OpenFileDialog
        {
            Filter = "vCard files (*.vcf)|*.vcf|All files (*.*)|*.*",
            Title = "Select vCard File"
        };

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

        return VCardReader.ReadVCard(dialog.FileName)?.Picture;
    }

    public override bool SupportsContext(ImageExtractorContext context)
    {
        return context == ImageExtractorContext.CardholderPicture;
    }
}

When an operator clicks the cardholder photo and selects Load from vCard..., the extractor opens a file dialog, parses the selected vCard file, extracts the embedded photo, and returns it for display.

ImageExtractor 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 image selection menu. Include an ellipsis (...) if the extractor shows a dialog.
Icon	The icon shown next to the name in the menu. Use a 16x16 or 24x24 pixel image.
GetImage()	Called when the user selects this extractor. Display any required UI and return the captured image as a BitmapSource (for example, a BitmapImage or RenderTargetBitmap), or null if cancelled.
SupportsContext(ImageExtractorContext)	Returns whether this extractor is available for a given context.

ImageExtractor optional members

Member	Default	Description
Priority	int.MaxValue	Controls menu ordering. Lower values appear first.
IsAvailable	true	Set to false to hide a registered extractor from matching menus. Set it back to true to show it again.

GetImage

The GetImage() method is called on the UI thread when the user selects your extractor from the menu. Display dialogs, interact with hardware, or perform any operation needed to obtain an image.

In the vCard extractor, GetImage() displays a file dialog and parses the selected file:

public override ImageSource GetImage()
{
    var dialog = new OpenFileDialog
    {
        Filter = "vCard files (*.vcf)|*.vcf|All files (*.*)|*.*",
        Title = "Select vCard File"
    };

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

    return VCardReader.ReadVCard(dialog.FileName)?.Picture;
}

Return null if the user cancels the operation or if the image cannot be obtained. The system handles null returns gracefully and leaves the current image unchanged.

Important

The GetImage() method runs on the UI thread. For long-running operations like network requests or hardware communication, display a progress dialog to keep the application responsive.

Context filtering

The SupportsContext method determines where your extractor appears. The system calls this method when building the image selection menu and excludes extractors that return false.

The vCard extractor only appears when setting cardholder photos, not for other image contexts:

public override bool SupportsContext(ImageExtractorContext context)
{
    return context == ImageExtractorContext.CardholderPicture;
}

Available contexts

Context	Description
Unspecified	Default context when no specific context is set
CardholderPicture	Cardholder photo field in the cardholder configuration page
CustomFields	Image-type custom fields on cardholders and other entities

To support multiple contexts, check for each one:

public override bool SupportsContext(ImageExtractorContext context)
{
    return context == ImageExtractorContext.CardholderPicture
        || context == ImageExtractorContext.CustomFields;
}

To support all contexts, return true unconditionally.

Priority and menu ordering

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

public override int Priority => 200;

Built-in extractors use these priority values:

Extractor	Priority
File	100
Webcam	200
Camera snapshot	300
Clipboard	400
Scanner/Signature pad	500

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

Registering an image extractor

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

public class SampleModule : Module
{
    private VCardImageExtractor m_imageExtractor;

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

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

The extractor becomes available immediately after registration and appears in image selection menus that match its supported contexts.

Note

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

Dynamic availability

Registered extractors are available by default. Set IsAvailable to false when a required condition is not met, and set it back to true when the extractor can run again.

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

When IsAvailable is false, the extractor does not appear in image selection menus.

ImageExtractor 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 (abstract)	Gets the icon shown in menus
Type	Property	Gets the component type GUID (always Components.ImageExtractor)
Priority	Property (virtual)	Gets the menu ordering priority. Default is int.MaxValue.
IsAvailable	Property	Gets or sets whether the extractor is currently available
Workspace	Property	Gets the workspace after initialization
GetImage()	Method (abstract)	Called to obtain an image. Return a BitmapSource (for example, a BitmapImage or RenderTargetBitmap), or null.
SupportsContext(ImageExtractorContext)	Method (abstract)	Returns whether this extractor supports a given context
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 cardholder fields extractors: Importing cardholder data from external sources.
• About Workspace SDK certificates: Certificate requirements for workspace components.