platform sdk security desk

Interacting with Security Desk

The Security Center SDK provides methods to interact with Security Desk, including displaying content in the Monitoring task, reading tile content, opening tasks, and sending messages or sounds to operators.

All methods described in this article require the target Security Desk to be connected. If the target is offline, actions are not queued and are silently lost. The calling user must have the appropriate privileges for each action.

Application entity

Every client that connects to the Directory creates an Application entity. Security Desk creates an Application entity with ApplicationType.SecurityDesk and registers one Monitor entity for each physical display attached to the workstation. The Monitors property on the Application entity contains the GUIDs of its registered Monitor entities.

For background on Application entities and the ApplicationType enumeration, see Connecting to Security Center.

Monitor entity

A Monitor entity (EntityType.Monitor) represents a physical display managed by a Security Desk application. When Security Desk starts, it detects the attached screens and creates one Monitor entity per screen.

The Monitor entity has two numeric identifiers:

Property	Type	Description
LogicalId	int?	A unique numeric identifier assigned in Security Center. Inherited from Entity.
MonitorId	int	The screen index on the local workstation. Identifies which physical display this monitor corresponds to.

These two properties serve different purposes and have different values. LogicalId is used to route actions to the correct monitor across the network. MonitorId is a local screen index that Security Desk uses to map the entity to a physical display.

Important

All ActionManager methods that accept a monitorId parameter expect the LogicalId value, not MonitorId.

The Monitor entity name follows the pattern "APPLICATION-NAME - LETTER", where APPLICATION-NAME is the parent Application entity's Name and the letter corresponds to the screen index (A for the first screen, B for the second, and so on). For example, "WS01 - SecurityDesk - A" and "WS01 - SecurityDesk - B".

Monitor entities are not visible in the Security Center user interface. Retrieve the LogicalId programmatically through the SDK using the Monitor.LogicalId property.

Monitor entities persist in the directory across Security Desk restarts. When Security Desk reconnects, it reuses the same Monitor entities and their logical IDs.

Finding a user's monitors

To display content on a specific user's Security Desk, locate their Application entity and retrieve its monitors.

Application entities must be loaded into the entity cache before they can be accessed. Query for them using EntityConfigurationQuery:

var query = (EntityConfigurationQuery)engine.ReportManager.CreateReportQuery(ReportType.EntityConfiguration);
query.EntityTypeFilter.Add(EntityType.Application);
query.DownloadAllRelatedData = true;
await Task.Factory.FromAsync(query.BeginQuery, query.EndQuery, null);

The following example finds all Security Desk sessions for a specific user and reads the content of their first tile on each monitor:

var securityDeskApps = engine.GetEntities(EntityType.Application)
    .OfType<Application>()
    .Where(app => app.ApplicationType == ApplicationType.SecurityDesk && app.IsOnline && app.LoggedUserGuid == userBGuid);

foreach (Application app in securityDeskApps)
{
    foreach (Guid monitorGuid in app.Monitors)
    {
        Monitor monitor = engine.GetEntity(monitorGuid) as Monitor;
        if (monitor?.LogicalId == null)
            continue;

        int logicalId = monitor.LogicalId.Value;

        // Read what is currently displayed in tile 1
        string tileContent = engine.ActionManager.GetTile(logicalId, 1);

        // Display a camera in tile 1
        string xml = $"<TileContentGroup><Contents><VideoContent VideoMode=\"Live\" Camera=\"{cameraGuid}\"/></Contents></TileContentGroup>";
        engine.ActionManager.DisplayInTile(logicalId, 1, xml);
    }
}

A user with multiple screens has multiple Monitor entities under a single Application. A user signed in on multiple workstations has multiple Application entities, each with its own set of monitors.

Displaying entities by user or group

DisplayEntityInSecurityDesk displays one or more entities on the Security Desk of a specific user or user group. This method targets recipients by GUID, so you do not need to know their monitor logical IDs.

engine.ActionManager.DisplayEntityInSecurityDesk(Guid recipient, Guid entity, bool forceDisplay);
engine.ActionManager.DisplayEntityInSecurityDesk(Guid recipient, Guid entity, bool forceDisplay, bool enableAudio);

Batch overloads accept IEnumerable<Guid> for both recipients and entities:

engine.ActionManager.DisplayEntityInSecurityDesk(IEnumerable<Guid> recipients, IEnumerable<Guid> entities, bool forceDisplay);
engine.ActionManager.DisplayEntityInSecurityDesk(IEnumerable<Guid> recipients, IEnumerable<Guid> entities, bool forceDisplay, bool enableAudio);

Parameter	Type	Description
recipient / recipients	Guid / IEnumerable<Guid>	The GUID of a user or user group to receive the content.
entity / entities	Guid / IEnumerable<Guid>	The GUID of the entity to display (camera, door, area, etc.).
forceDisplay	bool	Controls what happens when the active page has no available tiles. See the following section.
enableAudio	bool	When true, audio is enabled automatically for cameras that support it.

When the recipient has multiple monitors, Security Desk searches for a monitor that can display the content, following the priority described in the forceDisplay section below.

Displaying content in a specific tile

DisplayInTile sends serialized content to a specific monitor and optionally a specific tile. Unlike DisplayEntityInSecurityDesk, this method targets a monitor by logical ID and accepts arbitrary content in XML format.

engine.ActionManager.DisplayInTile(int monitorId, int tileId, string xmlContent);
engine.ActionManager.DisplayInTile(int monitorId, int tileId, string xmlContent, bool forceDisplay);
engine.ActionManager.DisplayInTile(int monitorId, string xmlContent);
engine.ActionManager.DisplayInTile(int monitorId, string xmlContent, bool forceDisplay);

Parameter	Type	Description
monitorId	int	The logical ID of the target monitor.
tileId	int	The 1-based index of the tile in the tile layout. Tiles are numbered in row-major order (left-to-right, top-to-bottom). When omitted, the content displays in the first empty tile.
xmlContent	string	An XML string describing the content to display.
forceDisplay	bool	When true and the requested tile does not exist in the active page, Security Desk finds the first opened monitoring task with enough tiles, or opens a new one.

If the tileId exceeds the number of tiles in the current pattern and forceDisplay is false, the content is not displayed.

The forceDisplay parameter

The forceDisplay parameter controls how Security Desk places content when the active page cannot accommodate it. The behavior differs between DisplayEntityInSecurityDesk and DisplayInTile.

DisplayEntityInSecurityDesk

Security Desk searches for a monitoring task that has enough tiles, following this priority order:

1. The active page on the target monitor
2. Active pages on other monitors belonging to the same application
3. Inactive pages on other monitors
4. Inactive pages on the target monitor

If no suitable monitoring task exists, Security Desk creates a new one with a default tile pattern sized for the requested content.

When forceDisplay is false, the content is placed in free tiles only. When forceDisplay is true, the content can replace existing tile content.

DisplayInTile

When forceDisplay is false, Security Desk uses the active page on the target monitor. If the requested tile does not exist or the active page is not a monitoring task, the content is not displayed.

When forceDisplay is true, Security Desk searches the pages on the target monitor for a monitoring task with enough tiles (active page first, then other pages). If none is found, Security Desk creates a new monitoring task, switches to it, and displays the content there.

Guid userB = ...;
Guid camera = ...;

// Display in a free tile only
engine.ActionManager.DisplayEntityInSecurityDesk(userB, camera, forceDisplay: false);

// Display, replacing existing content if needed
engine.ActionManager.DisplayEntityInSecurityDesk(userB, camera, forceDisplay: true, enableAudio: true);

Tile numbering

Tiles are numbered starting from 1 in row-major order. The numbering follows the tile pattern applied to the monitoring task. For example, in a 2x2 pattern:

[1][2]
[3][4]

In a pattern with spanning tiles:

[1][2][3]
[  4 ][5]

Tile 4 spans two columns. The maximum number of tiles in a pattern is 16.

There is no ActionManager method to query the current tile pattern or tile count on a remote monitor. To discover the available tiles, use GetTile to read individual tile positions.

Content XML format

The xmlContent parameter accepts a TileContentGroup root element containing a Contents element with one or more content type elements.

<TileContentGroup>
  <Contents>
    <CONTENT-TYPE ATTRIBUTES />
  </Contents>
</TileContentGroup>

XML element names and attribute names are case-sensitive. Use the exact casing shown in the table below.

The following content types are supported:

XML element	Description	Key attributes
VideoContent	Live or playback video from a camera.	Camera (GUID), VideoMode (Live or Playback), CurrentTime (UTC ticks, for playback)
Map	A map entity.	Map (GUID)
WebContent	A web page.	Url (string)
TilePlugin	A tile plugin entity.	TilePlugin (GUID)

AlarmContent, EventContent, and CustomEventContent are not valid for DisplayInTile. These types are created by Security Desk in response to alarms and events and do not have public constructors.

For the complete content class hierarchy and properties, see About content builders.

Display a live camera

string xml = $"<TileContentGroup><Contents><VideoContent VideoMode=\"Live\" Camera=\"{cameraGuid}\"/></Contents></TileContentGroup>";

engine.ActionManager.DisplayInTile(monitorId, 1, xml);

Display a playback stream starting at a specific time

string xml = $"<TileContentGroup><Contents><VideoContent VideoMode=\"Playback\" Camera=\"{cameraGuid}\" CurrentTime=\"{startTime.ToUniversalTime().Ticks}\"/></Contents></TileContentGroup>";

engine.ActionManager.DisplayInTile(monitorId, 1, xml, forceDisplay: true);

Reading tile content

GetTile retrieves the current content of a specific tile as an XML string in the same TileContentGroup format used by DisplayInTile.

string xml = engine.ActionManager.GetTile(monitorId, tileId);

GetTile reads from the active page on the target monitor. If the active page is not a tile-based page (for example, if the operator is viewing a report or configuration page), the call fails with an SdkException.

Returns String.Empty if the tile is empty or no response is received within 30 seconds. Throws SdkException if the tile does not exist or the active page has no tile layout.

Clearing tiles

ClearTile removes the content from a specific tile on a monitor.

engine.ActionManager.ClearTile(int monitorId, int tileId);

ClearTasksOnMonitor closes all task pages on the specified monitor.

engine.ActionManager.ClearTasksOnMonitor(int monitorId);

Sending a saved task

A user task is a saved workspace configuration that captures a complete snapshot of a task page, including which entities appear in which tiles and what tile layout pattern is used. User tasks are saved by operators and exist as EntityType.UserTask entities in Security Center. They are either public (visible to all users with sufficient access level) or private (saved in a specific user's profile).

SendUserTaskToMonitor sends a saved user task to a monitor. The task opens automatically on the target display without prompting the recipient. Because user tasks include both tile content and tile layout, this is the only way to remotely change the tile pattern on another user's monitor.

engine.ActionManager.SendUserTaskToMonitor(int monitorId, Guid userTaskId);

Parameter	Type	Description
monitorId	int	The logical ID of the target monitor.
userTaskId	Guid	The GUID of a saved user task entity.

If the task is not already open, it is added as a new page on the target monitor and becomes the active page. If the same task is already open on that monitor, it is reloaded in place. If the task is open on a different monitor, it is moved to the target monitor.

Retrieve available user tasks through UserTaskManager:

// Public tasks visible to the current user
IEnumerable<IUserTask> publicTasks = engine.UserTaskManager.GetPublicTasks();

// Private tasks for a specific user
IEnumerable<IUserTask> privateTasks = engine.UserTaskManager.GetPrivateTasks(userGuid);

IUserTask task = engine.UserTaskManager.GetPublicTasks().FirstOrDefault(t => t.Name == "Lobby Cameras");

engine.ActionManager.SendUserTaskToMonitor(monitorId, task.Guid);

Sending a message

SendMessage displays a dialog on the Security Desk of a specific user or user group. The dialog remains visible until the operator dismisses it or the timeout expires.

engine.ActionManager.SendMessage(Guid recipient, string message, int timeout);

Parameter	Type	Description
recipient	Guid	The GUID of a user or user group.
message	string	The message text to display.
timeout	int	The number of seconds the message stays visible. Use 0 for no timeout (the operator must dismiss it manually).

If a new message is sent while a previous message is still displayed, the previous message is closed and replaced.

engine.ActionManager.SendMessage(userBGuid, "Incident reported in lobby. Check camera 12.", 30);

Playing a sound

PlaySound plays a system sound on the Security Desk of a specific user or user group.

engine.ActionManager.PlaySound(Guid recipientId, Guid soundFileId);

Parameter	Type	Description
recipientId	Guid	The GUID of a user or user group.
soundFileId	Guid	The GUID of a sound file entity.

Toggling stream privacy protection

ShowOriginalStreamsForAllTiles and ShowProtectedStreamsForAllTiles switch all tiles in the active monitoring task between original and privacy-protected video streams.

engine.ActionManager.ShowOriginalStreamsForAllTiles(Guid recipient);
engine.ActionManager.ShowOriginalStreamsForAllTiles(IEnumerable<Guid> recipients);

engine.ActionManager.ShowProtectedStreamsForAllTiles(Guid recipient);
engine.ActionManager.ShowProtectedStreamsForAllTiles(IEnumerable<Guid> recipients);

Parameter	Type	Description
recipient / recipients	Guid / IEnumerable<Guid>	The GUID of a user or user group.