platform sdk entity write restrictions

About entity write restrictions

Security Center rejects writes to some entity members even when the logged-on user holds full administrative privileges. The restriction depends on where the entity comes from, which role owns it, and the partition rights of the logged-on user, not on the value you assign.

Each restriction raises an SdkException. Read ErrorCode to separate an imported-entity rejection (SdkError.RestrictedImportedEntity) from the other restrictions, which all raise SdkError.ReadonlyField. Check the entity state before the write to know which restriction applies, rather than handling the exception after it.

Entities created from an external source

An external source can supply the entities in a Security Center system. Active Directory synch for cardholders creates cardholders, credentials, and cardholder groups from directory accounts, and Federation supplies cameras and alarms from a federated system. The external source remains responsible for the members it supplies, so Security Center rejects writes to them.

A rejected write raises an SdkException with the error code SdkError.RestrictedImportedEntity and the message You only have read access on this member since it is part of an imported entity.

When your integration writes to a population that mixes both origins, the results look inconsistent. Entities created directly in Security Center accept the write and entities created from an external source reject it.

Members that reject the write

On a cardholder created from an external source, these members are read-only:

• Description
• EmailAddress
• FirstName
• LastName
• MobilePhoneNumber
• Name
• SetAccessPermissionLevel
• SetCustomIcon
• SetInheritAccessPermissionLevel

Picture and UseExtendedGrantTime stay writable on a cardholder that Active Directory supplies and are read-only on a cardholder from any other external source.

On a credential created from an external source, these members are read-only:

• BadgeTemplate
• CardholderGuid
• ChangeCredentialFormat
• Description
• Device
• Format
• InvitationDate
• InvitationExpirationDate
• MobileStatus
• Name
• ProfileReference
• SetCredentialFormat
• SetCustomIcon

Determining the origin of an entity

Some entity types expose a member that reports whether an external source supplied the entity. For cardholders, credentials, and cardholder groups, this check concerns Active Directory. For alarms and cameras, it concerns a federated system. Read the member before writing to the entity.

Entity type	Member	Indicates an external source when
Alarm	IsReactivationThresholdReadOnly, IsScheduleReadOnly	true
Camera	ExternalEntityGuid	Not Guid.Empty
Cardholder	IsActiveDirectoryEntity	true
CardholderGroup	ActiveDirectoryDomainName	Not empty
Credential	IsActiveDirectoryEntity	true

Cardholder and CardholderGroup also expose ActiveDirectoryDomainName, which returns the domain that supplied the entity. IsActiveDirectoryEntity returns false for a cardholder or credential that another external source supplies; a write to such an entity still raises SdkError.RestrictedImportedEntity.

This example renames a camera only when Security Center owns it. A federated camera keeps the name that the federated system assigns.

Camera camera = engine.GetEntity<Camera>(cameraGuid);

if (camera.ExternalEntityGuid == Guid.Empty)
{
    camera.Name = "Lobby entrance";
}

Changing activation and expiration on a cardholder or credential

Cardholder and Credential expose ActiveDirectoryOverride. Set it to true to allow the methods on the Status property to run against an entity that Active Directory supplied.

The override applies to Activate, Deactivate, ExpireOnFirstUseInDays, ExpireWhenNotUsedInDays, and SetExpirationToNever. The members listed above stay read-only.

Credential exposes two further methods on Status, Lost and Stolen, that raise SdkError.RestrictedImportedEntity on a credential created from an external source whatever the value of ActiveDirectoryOverride. Record the loss or theft in the system that supplies the credential.

This example deactivates a cardholder whether Security Center or Active Directory supplies it.

Cardholder cardholder = engine.GetEntity<Cardholder>(cardholderGuid);

if (cardholder.IsActiveDirectoryEntity)
{
    cardholder.ActiveDirectoryOverride = true;
}

cardholder.Status.Deactivate();

Note

Setting ActiveDirectoryOverride on a cardholder or credential that Active Directory did not supply raises an SdkException with the error code SdkError.InvalidOperation.

Writing custom fields

A custom field on an entity created from an external source stays writable unless Active Directory custom fields sync links that field to a directory attribute. A linked field raises SdkError.RestrictedImportedEntity in the same way as the members listed above.

When your integration must store its own values against cardholders that Active Directory supplies, use a custom field that the role does not link. For more information, see About custom fields.

Default system entities

Security Center creates a set of entities during installation, such as the root partition (SdkGuids.DefaultPartitionGuid) and the All cardholders group (SdkGuids.AllCardholders). Writes to these raise an SdkException with the error code SdkError.ReadonlyField and the message You only have read access on this member since it is a default system entity.

Create your own entity rather than modifying a default one.

Entities owned by another role

A role that creates an entity keeps responsibility for it. When a plugin creates an entity, only that plugin can modify the members that require ownership. A write from a different role, or from an application that is not the owning role, raises an SdkException with the error code SdkError.ReadonlyField and the message You only have read access on this member since it is an entity that you do not own.

When the owning role has marked the entity as synchronized (Synchronised returns true), a write to Name or Description from a different role or application raises an SdkException with the error code SdkError.ReadonlyField.

Read OwnerRole to determine which role owns an entity, OwnerRoleType to determine the kind of role, and IsOwnedByPlugin to determine whether a plugin owns it.

Partition rights

When the logged-on user lacks write access to the partition that contains an entity, a write raises an SdkException with the error code SdkError.ReadonlyField and the message You only have read access on this member.

This restriction responds to the rights of the logged-on user, so granting the user write access to the partition resolves it. The restrictions described in the preceding sections do not, because they depend on the entity rather than on the user.

Identifying the restriction that applied

Compare ErrorCode rather than matching the message text. SdkError.ReadonlyField covers partition rights, default system entities, and ownership by another role; read OwnerRole before the write when that difference matters to your integration. When you must handle the exception after the write, filter on the code, for example catch (SdkException ex) when (ex.ErrorCode == SdkError.RestrictedImportedEntity).

See also

• Entities: Entity types, retrieval, and the entity model
• About cardholders and credentials: Cardholder and credential members and lifecycle
• Partitions: Partition rights and how they affect write access
• Privileges: User privileges and how to verify them