plugin sdk custom entities

Defining custom entity types

Custom entity types extend Security Center with new entity types specific to your plugin. Each custom entity type has its own type descriptor, icons, capabilities, and access privileges.

About custom entity types

A custom entity type defines a new category of entities in Security Center. Examples include:

• ATMs monitored for skimming devices and service status
• Evidence lockers with chain-of-custody tracking
• Casino gaming tables with occupancy and activity states
• Drone patrol units reporting position and battery level
• Clean room zones with contamination alerts

Custom entities differ from built-in entities like cameras and doors. You define their structure, behavior, and how they integrate with the Security Center UI.

Registering a custom entity type

Register custom entity types through SystemConfiguration.AddOrUpdateCustomEntityType(). Only administrators can register or modify custom entity types.

var systemConfig = (SystemConfiguration)engine.GetEntity(SystemConfiguration.SystemConfigurationGuid);

var descriptor = new CustomEntityTypeDescriptor(
    id: new Guid("YOUR-CUSTOM-TYPE-GUID"),
    name: "Evidence Locker",
    capabilities: CustomEntityTypeCapabilities.IsVisible | CustomEntityTypeCapabilities.HasRunningState,
    version: new Version(1, 0, 0));

systemConfig.AddOrUpdateCustomEntityType(descriptor);

The id must be a unique GUID that identifies your custom entity type. Use the same GUID consistently across plugin versions.

Type versioning

The version parameter is required but the platform does not act on it. Use it for your own internal versioning to track type definition changes.

Entities do not store their own version. They only store a reference to their type GUID. When you access entity.TypeDescriptor, it fetches the current type descriptor from SystemConfiguration. This means when you update the type descriptor version, all existing entities immediately see the new version.

// Check the registered version before updating
CustomEntityTypeDescriptor registered = systemConfig.GetCustomEntityTypeDescriptor(evidenceLockerTypeGuid);
Version currentPluginVersion = new Version(2, 1, 0);

if (registered == null)
{
    // First time registration
    var descriptor = new CustomEntityTypeDescriptor(
        id: evidenceLockerTypeGuid,
        name: "Evidence Locker",
        capabilities: CustomEntityTypeCapabilities.IsVisible,
        version: currentPluginVersion);
    systemConfig.AddOrUpdateCustomEntityType(descriptor);
}
else if (registered.Version < currentPluginVersion)
{
    // Type exists with older version - migrate existing entities first
    MigrateEntities(registered.Version, currentPluginVersion);

    // Then update the type descriptor
    registered.Version = currentPluginVersion;
    systemConfig.AddOrUpdateCustomEntityType(registered);
}

Since the platform does not compare versions, your plugin is responsible for:

• Checking the registered version at startup
• Migrating existing entity data before updating the type descriptor
• Updating the type descriptor after migration completes

CustomEntityTypeCapabilities

Capabilities define what features your custom entity type supports:

Capability	Description
None	No special capabilities
CreateDelete	Entities can be created and deleted from Config Tool
MapSupport	Entities can be placed on maps
HasRunningState	Entities display a running state indicator
CanBeFederated	Entities can be federated to other systems
IsVisible	Entities appear in the system UI
MaintenanceMode	Entities can be put into maintenance mode

Combine capabilities using bitwise OR:

var capabilities = CustomEntityTypeCapabilities.IsVisible
    | CustomEntityTypeCapabilities.HasRunningState
    | CustomEntityTypeCapabilities.MapSupport;

Restricting to a single instance

Set SingleInstance to true to allow only one entity of this type in the directory:

descriptor.SingleInstance = true;

Configuring icons

Set icons for your custom entity type to distinguish it in the UI:

descriptor.SetLargeIcon(largeBitmap);  // For entity browser and details
descriptor.SetSmallIcon(smallBitmap);  // For tree views and lists

Associating privileges

Custom entity types can require specific privileges for view, add, modify, and delete operations. See Defining custom privileges for how to define custom privileges.

// Associate custom privileges with the entity type
descriptor.ViewPrivilege = new SdkPrivilege(viewPrivilegeGuid);
descriptor.AddPrivilege = new SdkPrivilege(addPrivilegeGuid);
descriptor.ModifyPrivilege = new SdkPrivilege(modifyPrivilegeGuid);
descriptor.DeletePrivilege = new SdkPrivilege(deletePrivilegeGuid);

You can also set all privileges at once:

descriptor.SetAccessPrivileges(
    view: new SdkPrivilege(viewPrivilegeGuid),
    add: new SdkPrivilege(addPrivilegeGuid),
    delete: new SdkPrivilege(deletePrivilegeGuid),
    modify: new SdkPrivilege(modifyPrivilegeGuid));

Setting supported events

Define which events your custom entity type can generate:

// Support standard Security Center events
descriptor.SupportedEvents = new[]
{
    EventType.EntityOnline,
    EventType.EntityOffline,
    EventType.CustomEvent
};

// Support custom events by ID
descriptor.SupportedCustomEvents = new[] { 1001, 1002, 1003 };

Configuring entity hierarchy

Custom entities can have hierarchical relationships with other entities.

Supported child types

The following entity types can be children of a custom entity:

• Area, Camera, Door, Elevator, Zone, IntrusionArea, Sequence, AnalogMonitor, ParkingZone, TilePlugin, TileLayout, CashRegister
• Cardholder, Credential
• VideoUnit, AccessControlUnit, LprUnit, Patroller
• Other custom entities (via HierarchicalChildCustomTypes)

Note

Device and AccessPoint cannot be added as children of a custom entity.

Define which entity types your custom entity accepts as children:

descriptor.HierarchicalChildTypes = new[]
{
    EntityType.Camera,
    EntityType.Door
};

descriptor.HierarchicalChildCustomTypes = new[]
{
    compartmentTypeGuid,
    shelfTypeGuid
};

Supported parent types

A custom entity can only have Area or another CustomEntity as a parent. See Managing hierarchical relationships for how to add parents programmatically.

Creating custom entity instances

Create instances of your custom entity type using CreateCustomEntity():

CustomEntity locker = engine.CreateCustomEntity("Locker A-101", customEntityTypeGuid);

To create with a parent entity:

CustomEntity compartment = engine.CreateCustomEntity("Compartment 1", compartmentTypeGuid, lockerGuid);

Storing entity data

Custom entities provide four storage fields:

Property	Persistent	Description
Xml	Yes	Primary configuration storage, persisted to the database
XmlExtra	Yes	Secondary configuration storage, persisted to the database
State	No	Primary runtime state, cleared when the entity goes offline or the system restarts
StateExtra	No	Secondary runtime state, cleared when the entity goes offline or the system restarts

Despite the property names, these fields accept any string format. You can store XML, JSON, or any serialized data:

var locker = (CustomEntity)engine.GetEntity(lockerGuid);

// XML format
locker.Xml = "<config><compartments>4</compartments></config>";

// JSON format works too
locker.XmlExtra = "{\"firmware\": \"2.1.0\", \"lastSync\": \"2024-01-15T10:30:00Z\"}";

// Runtime state (requires ownership when the entity is owned)
locker.State = "<state><locked>true</locked></state>";

Note

State and StateExtra require entity ownership. If the entity is owned by a plugin, only that plugin can modify them; otherwise any user with write access can. Any user with write access can modify Xml and XmlExtra.

Managing hierarchical relationships

Add and remove parent-child relationships:

var locker = (CustomEntity)engine.GetEntity(lockerGuid);

// Add a child entity
locker.AddHierarchicalChild(compartmentGuid);

// Remove a child entity
locker.RemoveHierarchicalChild(compartmentGuid);

// Add a parent (must be Area or CustomEntity)
locker.AddHierarchicalParent(areaGuid);

// Remove a parent
locker.RemoveHierarchicalParent(areaGuid);

Managing running state

Custom entity types with the HasRunningState capability can report their operational status. The owning plugin sets the running state when the entity is owned:

var locker = (CustomEntity)engine.GetEntity(lockerGuid);

// Set running state (requires ownership when the entity is owned)
locker.RunningState = State.Running;
locker.RunningState = State.Warning;
locker.RunningState = State.NotRunning;

Read the current state:

State currentState = locker.RunningState;
bool isOnline = locker.IsOnline;  // true when Running or Warning

Managing maintenance mode

Custom entity types with the MaintenanceMode capability can be put into maintenance mode. This sets the entity's maintenance state.

var locker = (CustomEntity)engine.GetEntity(lockerGuid);

// Enable maintenance indefinitely
locker.EnableMaintenance("Scheduled firmware update");

// Enable maintenance until a specific time
locker.EnableMaintenance(DateTime.UtcNow.AddHours(2), "Hardware inspection");

Check maintenance status:

bool inMaintenance = locker.IsInMaintenance;
bool supportsIt = locker.IsMaintenanceSupported;
DateTime? endTime = locker.MaintenanceEndTime;
string reason = locker.MaintenanceReason;

Querying custom entities

Query for custom entities using EntityConfigurationQuery:

var query = (EntityConfigurationQuery)engine.ReportManager.CreateReportQuery(ReportType.EntityConfiguration);
query.EntityTypeFilter.Add(EntityType.CustomEntity);
query.CustomEntityTypes.Add(customEntityTypeGuid);

QueryCompletedEventArgs results = query.Query();
foreach (DataRow row in results.Data.Rows)
{
    Guid entityGuid = (Guid)row["Guid"];
    var entity = (CustomEntity)engine.GetEntity(entityGuid);
}

Retrieving type descriptors

Get all registered custom entity types:

var systemConfig = (SystemConfiguration)engine.GetEntity(SystemConfiguration.SystemConfigurationGuid);
IReadOnlyCollection<CustomEntityTypeDescriptor> types = systemConfig.GetCustomEntityTypeDescriptors();

foreach (CustomEntityTypeDescriptor type in types)
{
    Console.WriteLine($"{type.Name} (v{type.Version})");
}

Get a specific type descriptor:

CustomEntityTypeDescriptor descriptor = systemConfig.GetCustomEntityTypeDescriptor(customEntityTypeGuid);

Access the type descriptor from an entity instance:

var entity = (CustomEntity)engine.GetEntity(entityGuid);
CustomEntityTypeDescriptor descriptor = entity.TypeDescriptor;

Removing custom entity types

Remove a custom entity type definition:

var systemConfig = (SystemConfiguration)engine.GetEntity(SystemConfiguration.SystemConfigurationGuid);
systemConfig.RemoveCustomEntityType(customEntityTypeGuid);

Warning

If any entities of this type exist, RemoveCustomEntityType fails with SdkException (TransactionFailed). Remove or migrate those entities before removing the type descriptor.

Configuring auditable properties

Define which properties within Xml or XmlExtra should be included in audit trails when they change:

descriptor.AuditableProperties = new[]
{
    new CustomEntityAuditableProperty
    {
        Path = "config/compartments",
        Name = "Compartment Count",
        SourceProperty = AuditPropertySource.Xml,
        Hints = AuditPropertyHints.Xml
    },
    new CustomEntityAuditableProperty
    {
        Path = "firmware",
        Name = "Firmware Version",
        SourceProperty = AuditPropertySource.XmlExtra,
        Hints = AuditPropertyHints.Json
    }
};

Path format

The Path property specifies the location of the auditable value within the serialized data. For XML, include the root node:

• config/compartments - Targets <config><compartments> in the Xml property
• settings/lastSync - Targets <settings><lastSync> in the XmlExtra property

For JSON data stored in these fields, use the same path format but set the appropriate hint.

AuditPropertySource

Value	Description
Xml	The auditable property is in the Xml field
XmlExtra	The auditable property is in the XmlExtra field

AuditPropertyHints

Combine hints using bitwise OR to control how the audit trail displays the value:

Hint	Description
None	Not valid by itself; use Xml or Json
UtcDate	Format the value as a UTC date
Collection	The value is a collection
Xml	The data format is XML
Json	The data format is JSON

Localized property names

Use NameKey instead of Name for localized audit trail entries:

new CustomEntityAuditableProperty
{
    Path = "config/compartments",
    NameKey = "AuditProperty_CompartmentCount",
    SourceProperty = AuditPropertySource.Xml
}

For localization to work, the NameKey value should exist in the resource manager specified by ResourceManagerTypeName on the type descriptor. If the key cannot be resolved, the audit trail falls back to the Name property, or displays the unknown label if Name is not provided.

Localizing custom entity types

Configure localization for your custom entity type to display translated names in the Security Center UI.

Setting up localization

1. Create a resource file (typically in your workspace module or plugin assembly) with translations for the languages you want to support. Missing translations will fall back to the Name property.
2. Set the ResourceManagerTypeName to the assembly-qualified name of your resource manager
3. Use NameKey instead of Name for the entity type name

descriptor.ResourceManagerTypeName = typeof(MyPluginResources).AssemblyQualifiedName;
descriptor.NameKey = "EntityType_EvidenceLocker";

The assembly containing the resource manager must be loaded on the client machine. This typically happens when your workspace module loads.

Localized audit property names

Audit trail entries can also be localized by using NameKey on CustomEntityAuditableProperty instead of Name. The key is resolved using the same resource manager.

Note

If the resource assembly is not available on the client, the localized value is not resolved. The audit trail uses Name when provided; otherwise it displays the unknown label.

Additional descriptor properties

Property	Description
Name	Display name for the entity type
NameKey	Localization key for the name
Version	Version number of the type definition
SingleInstance	When true, only one entity of this type can exist
DefaultMapLayerId	Default map layer for entities of this type
ResourceManagerTypeName	Assembly-qualified name of the resource manager for localization
AuditableProperties	Properties to include in audit trails

Custom properties

Store additional metadata in the type descriptor using the indexer:

// Set a custom property
descriptor["MyPlugin.Category"] = "Environmental";

// Get a custom property
string category = descriptor["MyPlugin.Category"];

// Enumerate all properties
foreach (var kvp in descriptor.EnumerateValues())
{
    Console.WriteLine($"{kvp.Key}: {kvp.Value}");
}

The following property keys are reserved for internal use. Setting any of these keys throws an SdkException:

Reserved Key	Purpose
SC.Name	Type display name
SC.NameKey	Localization key for name
SC.Capabilities	Capability flags
SC.LargeIcon	Large icon identifier
SC.SmallIcon	Small icon identifier
SC.SupportedEvents	Supported event types
SC.AccessPrivileges	Access privilege configuration
SC.ChildCustomEntityTypesSupported	Allowed child custom entity types
SC.ChildEntityTypesSupported	Allowed child entity types
SC.Version	Type descriptor version
SC.ResourceType	Resource manager type for localization
SC.AuditProperties	Auditable property configuration
SC.SingleInstance	Single instance restriction
SC.DefaultMapLayer	Default map layer identifier

Use a prefix that does not conflict with the current reserved keys, such as avoiding the SC. prefix.