platform sdk incidents

About incidents

Security Desk operators report incidents: records with a title, a category, notes, a timestamp, and references to the entities involved. The Platform SDK creates and manages these incident reports through Engine.IncidentManager and searches them with IncidentSdkQuery. Incidents are records, not entities: they have no entity type and are not part of the entity cache.

Note

Incident reports are the classic Security Desk feature (the Report an incident dialog and the Incidents task). They are not Genetec Mission Control incidents, which belong to the separately licensed Mission Control product with its own life cycle, tasks, and APIs. For the product features, find Reporting incidents and What is Mission Control on the Genetec TechDoc Hub.

Creating an incident

CreateIncident returns a new Incident; it throws SdkException with SdkError.UnsufficientPrivilege when the logged-on user cannot create incidents. Set the incident's properties, add the entities it concerns to References, and persist it with SaveIncident:

public Incident ReportIncident(
    Engine engine, Door door, string title, string notes)
{
    IncidentManager manager = engine.IncidentManager;

    Incident incident = manager.CreateIncident();
    incident.Title = title;
    incident.Notes = notes;
    incident.Timestamp = DateTime.UtcNow;
    incident.References.Add(door.Guid);

    manager.SaveIncident(incident);
    return incident;
}

Category can be empty; when set, it must match an existing incident category, or SaveIncident throws SdkException with SdkError.InvalidOperation and the message Could not save incident: Unknown category. The creation and modification metadata properties are read-only: CreatedBy, CreationTime, LastModifiedBy, and LastModificationTime.

Managing categories

Incident categories are system-wide strings. AddIncidentCategory, EditIncidentCategory, and RemoveIncidentCategory return false when the operation does not apply (an existing name on add, an unknown original or an existing replacement on edit, or blank names); GetIncidentCategories returns the current list:

public void ConfigureCategories(Engine engine)
{
    IncidentManager manager = engine.IncidentManager;

    bool added = manager.AddIncidentCategory("Vandalism");
    bool renamed = manager.EditIncidentCategory(
        "Vandalism", "Property damage");
    Console.WriteLine(
        $"Added: {added}, renamed: {renamed}");

    foreach (string category in
        manager.GetIncidentCategories())
    {
        Console.WriteLine(category);
    }
}

The SystemConfiguration entity exposes the same four category methods.

Retrieving incidents

GetIncident returns one incident and throws SdkException with SdkError.InvalidValue when no incident has the requested id. To search, run IncidentSdkQuery; it does not support QueryAsync, so run it with BeginQuery/EndQuery:

public async Task ListRecentIncidentsAsync(Engine engine)
{
    var query = (IncidentSdkQuery)engine.ReportManager
        .CreateReportQuery(ReportType.Incident);
    query.IncidentTimeRange.SetTimeRange(
        DateTime.UtcNow.AddDays(-7), DateTime.UtcNow);

    QueryCompletedEventArgs results =
        await Task.Factory.FromAsync(
            query.BeginQuery, query.EndQuery, null);

    foreach (DataRow row in results.Data.Rows)
    {
        var guid = (Guid)row[
            IncidentSdkQuery.InstanceGuidColumnName];
        var title = (string)row[
            IncidentSdkQuery.TitleColumnName];
        Console.WriteLine($"{guid}: {title}");
    }
}

The filters and result columns are listed in the query reference.

Deleting an incident

DeleteIncident returns true on success and false when the incident does not exist or could not be deleted. It throws SdkException with SdkError.InvalidValue for an empty id, and with SdkError.InvalidOperation when the system rejects the operation, for example when the logged-on user lacks the Delete incidents privilege.

Attaching a tile recording

Video sequences are attached to incidents from a Security Desk tile. In a Workspace SDK tile component, TileState.StartIncidentRecording begins collecting the tile's playback information, and StopIncidentRecording ends the collection and returns the recording; the collection it returns contains at most one TileIncidentRecording. Attach the result to an incident and save it:

public void AttachRecording(
    Engine engine, Guid incidentGuid,
    TileIncidentRecording recording)
{
    IncidentManager manager = engine.IncidentManager;
    Incident incident = manager.GetIncident(incidentGuid);
    incident.SetAttachedRecordingData(recording);
    manager.SaveIncident(incident);
}

GetTileRecording reads the attached recording back from an incident.

See also

• Incidents in the Web SDK: Creating and managing the same incident records over the Web SDK.
• Custom incident types: Extending Security Desk with custom incident types through the Workspace SDK.
• About the ReportManager: Running queries and processing results.