scadalink-design/Component-AuditLogging.md

Component: Audit Logging

Purpose

The Audit Logging component records all configuration and administrative changes in the system with the resulting state after each change, providing a queryable trail of who changed what and when.

Location

Central cluster. All auditable actions occur through central (sites receive configurations but do not originate changes).

Responsibilities

• Provide a service interface (IAuditService) for components to log changes after successful operations.
• Serialize entity state as JSON and store audit entries in the configuration MS SQL database.
• Write audit entries synchronously within the same database transaction as the change (via the unit-of-work).
• Provide query capabilities for the Central UI audit log viewer.

---

Integration Pattern

Audit logging uses a direct service call pattern. Components call IAuditService after a successful operation:

IAuditService.LogAsync(user, action, entityType, entityId, entityName, afterState)

• user: The authenticated AD user who performed the action (provided by Security & Auth).
• action: The type of operation (create, update, delete, deploy, disable, enable).
• entityType: What was changed (template, instance, alarm, shared script, etc.).
• entityId: Unique identifier of the specific entity.
• entityName: Human-readable name of the entity.
• afterState: The entity's state after the change, serialized as JSON. Null for deletes.

The IAuditService interface is defined in Commons (alongside the other shared interfaces). The implementation is provided by the Audit Logging component and registered in the DI container.

Transactional Guarantee

Audit entries are written synchronously within the same database transaction as the change. Since all central components use the unit-of-work pattern (EF Core's DbContext), the audit entry is added to the same DbContext and committed in the same SaveChangesAsync() call. This guarantees:

• If the change succeeds, the audit entry is always recorded.
• If the change fails and rolls back, the audit entry is also rolled back.
• No audit entries are lost due to process crashes between the change and the audit write.

Integration Example

Template Engine: Update Template
    │
    ├── repository.UpdateTemplate(template)
    ├── auditService.LogAsync(user, "update", "Template", template.Id, 
    │       template.Name, serialize(template))
    └── repository.SaveChangesAsync()  ← both the change and audit entry commit together

---

Audited Actions

Category	Actions
Templates	Create, edit, delete templates
Scripts	Create, edit, delete template scripts and shared scripts
Alarms	Create, edit, delete alarm definitions
Instances	Create, override values, bind connections, area assignment, disable, enable, delete
Deployments	Deploy to instance (who, what, which instance, success/failure)
System-Wide Artifact Deployments	Deploy shared scripts / external system definitions / DB connections / notification lists to sites (who, what, result)
External Systems	Create, edit, delete definitions
Database Connections	Create, edit, delete definitions
Notification Lists	Create, edit, delete lists and recipients
Inbound API	API key create, enable/disable, delete. API method create, edit, delete
Areas	Create, edit, delete area definitions
Sites & Data Connections	Create, edit, delete sites. Define and assign data connections to sites
Security/Admin	Role mapping changes, site permission changes

---

Audit Entry Schema

Each audit log entry contains:

Field	Type	Description
Id	Long / GUID	Unique identifier for the audit entry.
Timestamp	DateTimeOffset	When the action occurred (UTC).
User	String	Authenticated AD username who performed the action.
Action	String (enum)	The type of operation: Create, Update, Delete, Deploy, Disable, Enable.
EntityType	String	What was changed: Template, Instance, SharedScript, Alarm, ExternalSystem, DatabaseConnection, NotificationList, ApiKey, ApiMethod, Area, Site, DataConnection, LdapGroupMapping.
EntityId	String	Unique identifier of the specific entity.
EntityName	String	Human-readable name of the entity (for display without needing to deserialize state).
State	JSON (nvarchar(max))	The entity's state after the change, serialized as JSON. Null for deletes.

State Serialization

• Entity state is serialized as JSON using the standard .NET JSON serializer.
• JSON is stored in an nvarchar(max) column in SQL Server.
• The UI can render the JSON state for inspection. SQL Server's built-in JSON functions (JSON_VALUE, OPENJSON) can be used for ad-hoc queries against the state if needed.
• For delete operations, the state is null (the entity no longer exists). The previous state can be found by querying the most recent prior audit entry for the same entity.

Granularity

• One audit entry per save operation. When a user edits a template and changes multiple attributes in a single save, one audit entry is created containing the full template state after the save.
• This captures the complete picture of what the entity looked like after each change without requiring per-field tracking.

Reconstructing Change History

Since only the "after" state is stored, a full change history for an entity can be reconstructed by querying all audit entries for that entity ordered by timestamp. Comparing consecutive entries (entry N-1's state vs. entry N's state) reveals what changed at each step. This is a query-time concern handled by the Central UI, not a write-time concern.

---

Storage

• Stored in the configuration MS SQL database in a dedicated audit table, accessed via the IAuditLoggingRepository.
• Entries are append-only — audit records are never modified or deleted.
• No retention policy — audit logs are retained indefinitely.
• Indexes on: Timestamp, User, EntityType, EntityId, Action for efficient filtering.

---

Query Capabilities

The Central UI audit log viewer can filter by:

• User: Who made the change.
• Entity type: What kind of entity was changed.
• Action type: What kind of operation was performed.
• Time range: When the change occurred.
• Specific entity ID/name: Changes to a particular entity.

Results are returned in reverse chronological order (most recent first) with pagination support.

---

Dependencies

• Configuration Database: Storage for audit entries via IAuditLoggingRepository. Audit entries participate in the same unit-of-work transaction as the changes they record.
• Security & Auth: Provides the authenticated user identity for each entry.
• Commons: Defines the IAuditService interface and AuditLogEntry entity class.

Interactions

• All central components that modify state: Call IAuditService.LogAsync() after successful operations. This includes Template Engine, Deployment Manager, Security & Auth, Inbound API, External System Gateway, and Notification Service.
• Central UI: Provides the audit log viewer for querying and displaying entries.
• Configuration Database: Audit entries are committed in the same transaction as the changes they record.