> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logs

> Track user actions and data changes for compliance and troubleshooting

## Overview

bLIS maintains comprehensive audit logs for regulatory compliance, security monitoring, and troubleshooting. Two types of logs track different aspects of system activity:

* **Action Logs**: High-level user actions and events
* **Audit Logs**: Low-level database changes and data modifications

## Action Logs

Action logs track user activities and system events at a high level. They answer questions like "Who created this accession?" or "When was this result validated?"

### What's Logged

Action logs capture:

* User who performed the action
* Timestamp of the action
* Action type (e.g., "create\_accession", "validate\_result")
* Subject/accession the action relates to
* Description of what happened
* Additional details in JSON format
* Client IP address
* Transaction UUID for grouping related actions

### Action Types

Common action types include:

| Action              | Description                     |
| ------------------- | ------------------------------- |
| `create_accession`  | New accession created           |
| `receive_accession` | Accession marked as received    |
| `cancel_accession`  | Accession cancelled             |
| `create_hold`       | Hold placed on accession        |
| `resolve_hold`      | Hold resolved                   |
| `enter_result`      | Result entered or updated       |
| `validate_result`   | Result validated by second user |
| `finalize_result`   | Result finalized for reporting  |
| `generate_report`   | Report PDF generated            |
| `create_subject`    | New subject/patient created     |
| `update_subject`    | Subject information updated     |

### External Actions

The **Is External** flag distinguishes:

* **Internal** (`false`): Actions from authenticated users in the UI
* **External** (`true`): Actions from integrations, APIs, or automated systems

This helps identify whether an action was human-initiated or system-driven.

### Transaction Tracking

Related actions are grouped by **Transaction UUID**. For example, creating an accession might generate multiple action log entries:

1. Create subject
2. Create accession
3. Create samples
4. Create test orders

All four actions share the same `txnUuid`, making it easy to see the complete operation.

## Audit Logs

Audit logs track low-level database changes. They capture the exact before/after state of data modifications for complete traceability.

### What's Logged

Audit logs record:

* Table and schema where change occurred
* Action type (INSERT, UPDATE, DELETE)
* Complete "before" state (old data)
* Complete "after" state (new data)
* User who made the change
* User's email address
* Related accession (if applicable)
* Transaction UUID
* Timestamp

### Use Cases

Audit logs are essential for:

* **Compliance**: CLIA, HIPAA, and other regulatory requirements
* **Forensics**: Investigating data discrepancies or errors
* **Recovery**: Understanding what changed and when
* **Security**: Detecting unauthorized modifications

<Info>
  Audit logs are stored in a separate `blis_hidden` schema with restricted access. Only administrators can query these logs directly.
</Info>

## Viewing Logs

### Action Log Access

Action logs are accessible through the bLIS interface:

1. Navigate to the **Audit** section
2. Filter by user, date range, or action type
3. View action details including description and metadata
4. Follow transaction UUIDs to see related actions

### Search and Filter

Find specific actions by:

* **User**: See all actions by a specific user
* **Date Range**: Actions within a time window
* **Action Type**: Specific types of actions
* **Subject/Accession**: All actions for a patient or work order
* **Transaction UUID**: All actions in a single operation

### Audit Log Access

Audit logs require administrative database access. Query examples:

```sql theme={null}
-- Find all changes to a specific accession
SELECT * FROM blis_hidden.audit_log
WHERE accession_id = 12345
ORDER BY action_tstamp DESC;

-- See who modified test results today
SELECT user_email, action, table_name, action_tstamp
FROM blis_hidden.audit_log
WHERE table_name = 'test_order_results'
  AND action_tstamp::date = CURRENT_DATE;

-- Track changes by a specific user
SELECT table_name, action, action_tstamp
FROM blis_hidden.audit_log
WHERE user_email = 'tech@example.com'
ORDER BY action_tstamp DESC;
```

## Compliance and Retention

### Regulatory Requirements

Many healthcare regulations require audit logs:

* **CLIA**: Document result entry, validation, and corrections
* **HIPAA**: Track access to protected health information
* **CAP**: Maintain complete audit trails for accreditation

bLIS audit logs satisfy these requirements by capturing:

* Who accessed or modified data
* When the action occurred
* What was changed (before/after states)
* Why (through action descriptions)

### Retention Policies

Establish audit log retention policies based on:

* Regulatory requirements (typically 2-7 years minimum)
* Organizational policies
* Storage capacity
* Legal hold requirements

<Warning>
  Audit logs should never be deleted or modified. They are immutable records of system activity.
</Warning>

## Monitoring and Alerts

### Common Monitoring Scenarios

Set up alerts for suspicious or important activities:

* Multiple failed login attempts
* After-hours data access
* Bulk deletions or updates
* Changes by unexpected users
* External API actions exceeding thresholds

### Review Practices

Regular audit log review helps:

* Identify training needs (repeated errors by specific users)
* Detect security issues early
* Verify compliance with procedures
* Improve workflows based on actual usage patterns

## Troubleshooting with Logs

### Investigating Issues

When problems occur, audit logs help answer:

1. **What happened?** Check action logs for high-level events
2. **When did it happen?** Use timestamps to establish timeline
3. **Who did it?** Identify the user or system responsible
4. **What changed?** Review audit log old/new data
5. **What else happened?** Follow transaction UUIDs to related actions

### Common Investigations

**Missing or incorrect results:**

1. Check action logs for `enter_result`, `validate_result` actions
2. Review audit log for `test_order_results` table changes
3. Compare old\_data vs new\_data to see what changed
4. Identify when and by whom corrections were made

**Accession workflow issues:**

1. Search action logs by accession ID
2. Look for status changes (received, completed, cancelled)
3. Check for holds that may have blocked processing
4. Verify all required steps were completed in order

**User access questions:**

1. Filter action logs by user email
2. Review `is_external` flag to distinguish UI vs API actions
3. Check timestamps against work schedules
4. Look for unusual patterns or access times

## Best Practices

### Logging Hygiene

* Never manually modify audit logs
* Set up regular automated backups
* Restrict direct database access to audit tables
* Monitor log storage growth

### Investigation Process

* Start with action logs for context
* Use transaction UUIDs to group related changes
* Drill down to audit logs for detailed before/after data
* Document findings for future reference

### Security

* Limit who can access audit logs
* Protect log export files with encryption
* Review access to audit logs themselves
* Alert on unexpected audit log queries

### Compliance

* Define retention policies in writing
* Regularly verify logs are being captured
* Test log restoration procedures
* Include logs in disaster recovery plans