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. A mapping associates the role with another entity, such as a door, a camera, or a cardholder, and stores a string payload of custom data or metadata for it.

A mapping behaves like a custom field scoped to a role rather than to the mapped entity: unlike system-wide custom fields, mappings do not appear in Config Tool, Security Desk, or other standard interfaces. They are not access-restricted to the application that created them, though. Any application that can access the role can read its mappings, and any application with write access to the role, whether a plugin, a workspace module, or an external application, can add, change, or remove them.

Important

Because of this, mappings are not a secure or private store. Do not use them for secrets or for data that must be hidden from other integrations.

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 a role needs 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-scoped storage that does not appear in Security Center's user interfaces. Your plugin can associate custom data with any entity (doors, cardholders, cameras, and so on).

Entity-specific role configuration

Store entity-specific configuration data within any role type, not only plugin roles. EntityMappings is defined on the base Role, so a built-in role can hold mappings as well; for example, mapping cameras on the Archiver role attaches custom metadata to those cameras.

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-scoped	System-wide
Visibility	Not shown in Config Tool or Security Desk, but readable by any application with access to the 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 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 adds a mapping for the entity. It does not update an existing mapping; to change a mapping, modify the EntityMappings collection and reassign it.

RemoveMapping method

public void RemoveMapping(EntityMapping mapping);

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

Mapping lifecycle

Mappings are removed automatically when either end is deleted. Deleting the role removes all of its mappings, and deleting a mapped entity removes the mappings that reference it, so you do not need to clean up mappings yourself when an entity is removed.

Adding, changing, or removing a mapping requires write access to the role. Reading a role's mappings requires only that your application can access the role.

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;

Direct assignment is faster because the setter applies the entire collection in one update transaction and reconciles it in a single pass over the mappings. Each AddMapping or RemoveMapping call runs its own update transaction and scans the role's mappings on every call, so changing N mappings one at a time is N transactions (2N when you remove and re-add) with a scan per call. For a large set, that is one bulk update instead of thousands of individual ones.

Tip

Use AddMapping or RemoveMapping for a single change. To change many mappings at once, read EntityMappings, modify the list, and reassign it so the whole set is applied in one transaction.

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 a role's mappings change, applications with the role loaded receive Engine.EntitiesInvalidated, with the role among the invalidated entities. Mapping changes do not raise the role's FieldsChanged event, which reports changes to the role's own fields, not to its mappings. The invalidation signals that the role changed but does not identify which mapping was added, changed, or removed. To act on a change, handle EntitiesInvalidated, check whether the role is in the invalidated set, then re-read role.EntityMappings and compare it against your cached copy.

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.