plugin sdk entity mappings

About plugin entity mappings

The EntityMappings property is a List<EntityMapping> collection on the Role entity that allows plugins to store custom configuration data or metadata associated with specific entities. This is a plugin-specific feature for maintaining private data relationships between your plugin role and other entities in Security Center.

Think of EntityMappings as private custom fields that belong to your role. While Security Center's custom fields are system-wide and visible to all applications, EntityMappings allow your role to maintain its own private data associated with any entity. This data is only accessible through your role and won't interfere with other applications or system-wide configurations.

EntityMapping class structure

The EntityMapping class contains three key properties:

public class EntityMapping
{
    public Guid LocalEntityId { get; set; }
    public Guid RoleId { get; set; }
    public string XmlInfo { get; set; }
}

Properties

• LocalEntityId: The GUID of the entity being mapped (for example, Door, AccessPoint, Cardholder).
• RoleId: The GUID of the role that owns this mapping.
• XmlInfo: A string field for storing custom configuration data, typically XML but can contain any string data.

Common use cases

Use entity mappings when your role needs private, role-scoped data associated with Security Center entities.

Plugin role configuration

EntityMappings is typically used with plugin roles to store custom configuration data specific to individual entities. This is the most common and recommended use case.

Unlike custom fields that are visible in Config Tool and Security Desk, EntityMappings provides role-private storage. Your plugin can associate custom data with any entity (doors, cardholders, cameras, etc.) without affecting other applications or appearing in Security Center's user interfaces.

Entity-specific role configuration

Store entity-specific configuration data within any role type. This allows roles to maintain custom settings or metadata for each entity they manage.

Custom entity configuration

EntityMappings can store any custom configuration data that needs to be associated with a specific entity within a role's context.

External system integration

EntityMappings is commonly used to map Security Center entities to external third-party systems. This enables integration plugins to maintain correlations between entities and external data sources:

• Map cardholders to employee IDs in HR systems
• Connect entities to external database records

EntityMappings vs custom fields

Feature	EntityMappings	Custom fields
Scope	Role-private	System-wide
Visibility	Only accessible through your role	Visible in Config Tool and other applications
Purpose	Internal plugin data and integration mappings	User-configurable entity properties
UI integration	No automatic UI representation	Appears in Security Center interfaces
Use case	Plugin-specific configuration and external system mappings	Business properties users can modify

EntityMappings is ideal when you need to store configuration data that should remain private to your application and not appear in the standard Security Center user interfaces.

EntityMappings property

The role.EntityMappings property returns a copy of the mapping collection, not a live collection reference. This means:

// This will NOT work as expected
role.EntityMappings.Add(newMapping); // Adding to a copy, not the original

// This is the correct approach
var mappings = role.EntityMappings;
mappings.Add(newMapping);
role.EntityMappings = mappings; // Assign the modified list back

The Role class provides convenience methods for working with EntityMappings:

AddMapping method

public void AddMapping(Guid localEntity, string info);

This method creates and adds a new EntityMapping to the role's EntityMappings collection.

RemoveMapping method

public void RemoveMapping(EntityMapping mapping);

This method removes the specified EntityMapping from the role's collection.

Performance considerations for bulk operations

When working with large numbers of mappings, direct list assignment is significantly faster than using the individual helper methods:

Slow approach for bulk operations

// Inefficient for many mappings
foreach (var mapping in manyMappings)
{
    role.AddMapping(mapping.LocalEntityId, mapping.XmlInfo);
}

Fast approach for bulk operations

// Efficient for bulk operations
var mappings = role.EntityMappings;
mappings.AddRange(manyMappings);
role.EntityMappings = mappings;

Use the helper methods (AddMapping, RemoveMapping) for single operations, but prefer direct list manipulation for bulk operations.

Working with EntityMappings

Use these patterns to add, update, and retrieve mapping data consistently.

Adding a mapping

To add or update an EntityMapping:

void SaveMapping(Role role, Guid entityId, string data)
{
    var mappings = role.EntityMappings;
    var existing = mappings.FirstOrDefault(m => m.LocalEntityId == entityId);
    
    if (existing != null)
        existing.XmlInfo = data;
    else
        mappings.Add(new EntityMapping { LocalEntityId = entityId, RoleId = role.Guid, XmlInfo = data });
    
    role.EntityMappings = mappings;
}

Retrieving a mapping

To retrieve configuration data from an EntityMapping:

bool TryGetMapping(Role role, Guid entityId, out string data)
{
    EntityMapping mapping = role.EntityMappings
        .FirstOrDefault(m => m.LocalEntityId == entityId);
        
    if (mapping != null)
    {
        data = mapping.XmlInfo;
        return true;
    }
    
    data = default;
    return false;
}

Removing a mapping

To remove an EntityMapping from a role:

role.RemoveMapping(mapping);

Event notifications

When EntityMappings are modified, the system raises the following events:

• EntityInvalidated: Raised on the Engine instance for the specific role entity.
• EntitiesInvalidated: Raised on the Engine instance for the collection of roles affected.
• FieldsChanged: Raised on the role instance to indicate that a field has been updated.

These events allow applications to respond to changes in EntityMappings and update their own cached data or user interfaces accordingly.

Data persistence

Changes to EntityMappings are automatically persisted to the Security Center database when you set the EntityMappings property or call AddMapping() or RemoveMapping().

For bulk operations, prefer using the EntityMappings property setter as shown in the performance considerations section above. This is a single operation regardless of how many mappings are in the list.

If you must use AddMapping() or RemoveMapping() in a loop, wrap the operations in a transaction to batch them:

engine.TransactionManager.ExecuteTransaction(() =>
{
    foreach (var mapping in mappingsToAdd)
    {
        role.AddMapping(mapping.LocalEntityId, mapping.XmlInfo);
    }
});

See also

• Plugin SDK overview: Plugin architecture, lifecycle, and components.
• Plugin SDK configuration: Role-level configuration storage and update flow.
• Plugin SDK entity ownership: Plugin-owned entities and their running-state contract.
• About entities: Entity model and IPartitionSupport.
• About transactions: Batching multiple entity operations into one request.