plugin sdk entity ownership

About plugin entity ownership

When a plugin creates entities in Security Center using the SDK, those entities are owned by the plugin and marked with special properties that distinguish them from entities created by Config Tool or external applications. Understanding plugin entity ownership is crucial for proper plugin development.

What is Plugin Entity Ownership?

Plugin entity ownership is an automatic mechanism where entities created by a plugin are:

• Owned by the plugin's role
• Marked as synchronized (entity.Synchronised = true)
• Added to the plugin's root area (for hierarchical entity types)
• Managed by the plugin for running state and lifecycle

This ownership model allows Security Center to track which plugin is responsible for an entity and ensures proper cleanup when the plugin is uninstalled or removed.

How Ownership is Applied

When you create an entity from within a plugin using engine.CreateEntity(), the SDK automatically applies ownership:

What happens automatically:

• The entity is assigned to your plugin's role as the owner
• The entity is marked as Synchronised = true
• Hierarchical entities (areas, doors, access points, elevators, zones) are automatically added to the plugin's root area
• The entity becomes read-only to other plugins and external applications

Entity Properties Related to Ownership

OwnerRole Property

The OwnerRole property returns the GUID of the role that owns the entity. For plugin-created entities, this is the GUID of the plugin's role.

// Get the owner role GUID
Guid ownerRoleGuid = entity.OwnerRole;

// For plugin-owned entities, this returns the plugin's role GUID
if (entity.IsOwnedByPlugin)
{
    // ownerRoleGuid is the GUID of the plugin role
    var pluginRole = engine.GetEntity<Role>(ownerRoleGuid);
    Console.WriteLine($"Entity owned by plugin: {pluginRole.Name}");
}

OwnerRoleType Property

The OwnerRoleType property returns the type of role that owns the entity. For plugin-created entities, this is RoleType.Plugin.

// Check the owner role type
RoleType ownerType = entity.OwnerRoleType;

if (ownerType == RoleType.Plugin)
{
    // Entity is owned by a plugin
}
else if (ownerType == RoleType.SecurityCenter)
{
    // Entity is from a federation
}
else if (ownerType == RoleType.Archiver)
{
    // Entity is owned by an Archiver role
}
// ... other role types

Common RoleType values:

• RoleType.Plugin - Plugin role
• RoleType.SecurityCenter - Federation (from another Security Center system)
• RoleType.Archiver - Archiver role
• RoleType.AccessManager - Access Manager role
• RoleType.IntrusionDetection - Intrusion Detection role
• Many others (see SDK documentation for complete list)

IsOwnedByPlugin Property

// Check if an entity is owned by a plugin
if (entity.IsOwnedByPlugin)
{
    // This entity was created by a plugin
}

This property returns true when the entity's master role type is a plugin. It helps differentiate between:

• Plugin-owned entities (synchronized from plugins)
• Federation-synchronized entities (from other Security Center systems)
• Regular entities (created by Config Tool or external applications)

Synchronised Property

The Synchronised property indicates whether an entity is synchronized (from a plugin or federation):

// Check if entity is synchronized
if (entity.Synchronised)
{
    // This entity is synchronized (plugin-owned or federated)
}

Important

Synchronized entities can only be modified by their owner. If you try to modify a synchronized entity that your plugin doesn't own, you'll get a SdkException(SdkError.ReadonlyField).

Plugin Responsibilities for Owned Entities

1. Managing Running State

Plugin-owned entities do not automatically have their running state managed. The plugin must explicitly set and maintain the RunningState property.

Why entities appear "red" in Config Tool: When a plugin creates an entity but doesn't set its running state, the entity appears offline (red) in Config Tool because its running state defaults to State.NotRunning.

Solution - Set Running State:

engine.TransactionManager.ExecuteTransaction(() =>
{
    var userGroup = (UserGroup)engine.CreateEntity("My User Group", EntityType.UserGroup);
    userGroup.Description = "Created by my plugin";
    
    // IMPORTANT: Set running state so it doesn't appear red
    userGroup.RunningState = State.Running;
});

Updating Running State:

// The plugin should update running state based on its operational status
if (pluginIsOperational)
{
    entity.RunningState = State.Running;
}
else if (pluginHasWarnings)
{
    entity.RunningState = State.Warning;
}
else
{
    entity.RunningState = State.NotRunning;
}

2. Entity Lifecycle Management

Plugin-owned entities follow the plugin's lifecycle:

• Created when the plugin creates them
• Maintained while the plugin is running
• Should be deleted or released when no longer needed

Plugin Root Area

Hierarchical entity types (areas, doors, access points, elevators, zones) created by plugins are automatically added to a plugin root area.

Purpose of Plugin Root Area:

• Organizes all hierarchical entities owned by the plugin
• Automatically created when the first hierarchical entity is created
• Named after the plugin role
• Hidden from UI when empty
• Managed automatically by the SDK

Hierarchical Entity Types:

• Area
• Door
• Access Point
• Elevator
• Zone

Non-Hierarchical Entity Types (not added to root area):

• Cardholder
• User
• User Group
• Partition
• Credential
• Access Rule
• Schedule
• Most other entity types

Deletion Restrictions for Plugin-Owned Entities

Plugin-owned entities cannot be deleted from Config Tool by administrators. Only the owning plugin can delete them using engine.DeleteEntity().

Why this restriction exists:

• Prevents data inconsistency when external deletions occur without the plugin's knowledge
• Ensures the plugin maintains control over its managed entities
• Allows the plugin to perform cleanup operations before deletion

Deleting Plugin-Owned Entities:

// Only the owning plugin can delete its entities
engine.TransactionManager.ExecuteTransaction(() =>
{
    engine.DeleteEntity(myPluginOwnedEntity);
});

Attempting Deletion from Another Context: If a different plugin or external application tries to delete a plugin-owned synchronized entity, the operation will fail with a SdkException(SdkError.ReadonlyField).

Releasing Entity Ownership

A plugin can release ownership of entities it created, transferring control back to Security Center. Once ownership is released:

• The entity is no longer synchronized (Synchronised = false)
• Config Tool administrators can modify and delete the entity
• The entity is removed from the plugin's root area
• The plugin is no longer responsible for managing the entity

engine.TransactionManager.ExecuteTransaction(() =>
{
    var userGroup = (UserGroup)engine.CreateEntity("Shared User Group", EntityType.UserGroup);
    userGroup.Description = "This will be managed by administrators";
    userGroup.RunningState = State.Running;

    // Release ownership to allow Config Tool management
    userGroup.ReleaseOwnership();

    // After this, the entity is no longer plugin-owned
});

What Happens When You Call ReleaseOwnership():

1. Synchronised is set to false
2. The plugin's ownership information is removed
3. The entity is removed from the plugin's root area (if applicable)
4. The entity becomes a regular entity manageable by anyone with appropriate privileges

Releasing Ownership for Areas

Areas have special behavior when releasing ownership because they may contain child entities. When you call ReleaseOwnership() on an area:

Area Release Behavior:

• The area itself releases ownership
• All child entities also release ownership recursively
• This ensures consistent ownership state for the entire hierarchy
• Access points, doors, elevators, and zones under the area are all released

Example:

engine.TransactionManager.ExecuteTransaction(() =>
{
    var area = engine.GetEntity<Area>(myAreaGuid);
    
    // Releases ownership of the area AND all its children
    area.ReleaseOwnership();
});

Common Scenarios and Solutions

Scenario 1: Entity Appears Red in Config Tool

Problem:

var userGroup = (UserGroup)engine.CreateEntity("My Group", EntityType.UserGroup);
// Entity appears red/offline in Config Tool

Solution:

engine.TransactionManager.ExecuteTransaction(() =>
{
    var userGroup = (UserGroup)engine.CreateEntity("My Group", EntityType.UserGroup);
    userGroup.RunningState = State.Running;  // Set running state
});

Explanation: Plugin-owned entities default to State.NotRunning which appears red/offline in Config Tool. Always set RunningState = State.Running when creating entities.

Related Guides

• Plugin SDK Overview - Plugin architecture
• Plugin SDK Lifecycle - Entity creation during lifecycle events
• Plugin SDK Threading - Threading for entity operations
• Plugin SDK State Management - Reporting plugin and entity health
• SDK Transactions - Transaction requirements for entity operations