workspace sdk incidents

About incidents

Incident builders add custom incident types to Security Center's incident management system. They define the data fields for an incident type and provide the user interface for creating and viewing incidents. Creating a custom incident type requires two classes:

• IncidentBuilder - registered as a component, defines the incident's data fields and creates the editing view
• IncidentView - provides the user interface for entering and displaying incident data

Use incident builders when you need to capture structured data specific to your organization's incident workflows. Examples include:

• Recording vehicle accident details (license plate, damage assessment, insurance information) for a parking management integration
• Capturing safety inspection results (equipment checked, compliance status, corrective actions) for a workplace safety system
• Logging visitor incidents (visitor identity, escort assigned, areas accessed) for a visitor management integration

How incidents work

1. The module registers an IncidentBuilder with the workspace during Load
2. When an operator creates or edits an incident, the system calls IsSupported() with an IncidentContext containing the edit mode, attachment type, and existing data
3. If supported, the system calls CreateView() with the Incident being edited
4. The system calls Initialize() on the view with the workspace
5. If editing an existing incident, the system sets the view's IncidentData property with the stored data entries
6. The operator enters data through the view's interface; the view raises IncidentDataChanged when values change
7. When the operator saves the incident, the system reads the view's IncidentData property to persist the data
8. If CanExport is true, the system calls Export() after saving to allow the view to export data (such as video clips)
9. If ShouldProtect is true, the system calls Protect() after saving to allow the view to protect associated video data
10. When generating incident reports, the system calls GetFieldValue() on the builder to extract field values for report columns
11. When the incident dialog closes, the system calls Dispose() on the view

IncidentBuilder

Inherit from IncidentBuilder and implement the abstract members:

public class MyIncidentBuilder : IncidentBuilder
{
    public override string Name => "My Incident Type";

    public override Guid UniqueId => new Guid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890");

    public override string IncidentDataType => "MyIncident";

    public override List<IncidentField> Fields =>
        new List<IncidentField>
        {
            new IncidentField
            {
                Name = "Location",
                DisplayName = "Location",
                DisplayInReport = true
            },
            new IncidentField
            {
                Name = "Severity",
                DisplayName = "Severity Level",
                DisplayInReport = true
            }
        };

    public override IncidentView CreateView(Incident incident)
    {
        return new MyIncidentView();
    }

    public override string GetFieldValue(List<IncidentDataEntry> incidentData, string fieldName)
    {
        var entry = incidentData
            .FirstOrDefault(e => e.Identifier == fieldName);
        return entry?.Data;
    }
}

IncidentBuilder members

Member	Type	Description
IncidentDataType	Property (abstract)	Unique string identifier for this incident data type.
Fields	Property (abstract)	The list of data fields defined by this incident type.
CustomFilter	Property (virtual)	A custom ReportFilter to display in the incident report. Defaults to null.
Priority	Property (virtual)	Display order in the incident dialog tabs. Lower values appear first.
CreateView(Incident)	Method (virtual)	Create the editing view for the incident. Receives the incident being edited.
GetFieldValue(List<IncidentDataEntry>, string)	Method (abstract)	Extract the value of a specific field from incident data. Used by the reporting system to populate field columns.
IsSupported(IncidentContext)	Method (virtual)	Return true when the incident type is available in the given context.

IncidentField

Each field in the Fields list defines a data column for the incident type:

Member	Type	Description
Name	string	Unique identifier for the field. Used as the key in GetFieldValue.
DisplayName	string	Column header displayed in incident reports.
DisplayInReport	bool	Whether the field appears as a column in incident reports.

IncidentContext

The context passed to IsSupported provides:

Member	Type	Description
EditMode	bool	Whether an existing incident is being edited.
AttachmentType	string	The type of data attached to the incident.
Data	IList<IncidentDataEntry>	The attached incident data entries.
IncidentId	Guid?	The incident identifier when editing an existing incident.

IncidentDataEntry

Incident data is stored as a list of key-value pairs:

Member	Type	Description
Identifier	string	The data entry key. Corresponds to an IncidentField.Name.
Data	string	The data entry value.

IncidentView

Inherit from IncidentView to create the incident editing interface:

public class MyIncidentView : IncidentView
{
    public override string IncidentDataType => "MyIncident";

    public override List<IncidentDataEntry> IncidentData
    {
        get
        {
            return new List<IncidentDataEntry>
            {
                new IncidentDataEntry("Location", m_location),
                new IncidentDataEntry("Severity", m_severity)
            };
        }
        set
        {
            foreach (var entry in value)
            {
                switch (entry.Identifier)
                {
                    case "Location":
                        m_location = entry.Data;
                        break;
                    case "Severity":
                        m_severity = entry.Data;
                        break;
                }
            }
        }
    }
}

IncidentView required members

Member	Type	Description
IncidentDataType	Property (abstract)	The incident data type. Must match the builder's IncidentDataType.
IncidentData	Property (abstract)	The current incident data as a list of IncidentDataEntry objects.

IncidentView optional members

Member	Type	Description
IncidentId	Property (Guid?)	The incident identifier when editing an existing incident. Set by the system.
IncidentName	Property (virtual)	The incident name.
IncidentTime	Property (virtual)	The incident timestamp.
IncidentDescription	Property (virtual)	The incident description.
References	Property (virtual)	Entity references associated with the incident.
Title	Property (virtual)	The tab title displayed in the incident dialog.
IsDataEmpty	Property (virtual)	Whether the incident data is empty.
CanExport	Property (virtual)	Whether the incident data supports export.
ShouldProtect	Property (virtual)	Whether the incident data supports protection.
Initialize(Workspace)	Method (virtual)	Initialize the view with the workspace.
Export()	Method (virtual)	Export the incident data. Return false if the operation is canceled.
Protect()	Method (virtual)	Protect the incident's video data.
Dispose()	Method (virtual)	Release resources used by the view.

Events

Event	Description
ReferencesChange	Raised when the References property changes.
IncidentDataChanged	Raised when the incident data changes. Call NotifyIncidentDataChanged() to raise this event.

Registering an incident builder

Important

This component requires a valid SDK certificate.

Register the builder in your module's Load method:

public class SampleModule : Module
{
    private MyIncidentBuilder m_incidentBuilder;

    public override void Load()
    {
        m_incidentBuilder = new MyIncidentBuilder();
        m_incidentBuilder.Initialize(Workspace);
        Workspace.Components.Register(m_incidentBuilder);
    }

    public override void Unload()
    {
        if (m_incidentBuilder != null)
        {
            Workspace.Components.Unregister(m_incidentBuilder);
        }
    }
}

See also

• About the Workspace SDK: Workspace SDK architecture and module lifecycle.
• About components: The component registry and registration lifecycle.
• About workspace modules: Workspace module class and Load/Unload lifecycle.
• About Workspace SDK certificates: Certificate requirements for workspace components.