Form Change Logs

Enterprise applications require accountability. When a patient’s medication dosage changes in a healthcare workflow, someone needs to know who changed it, what the previous value was, and when the modification occurred. When an insurance claim amount is adjusted, the audit trail must be unimpeachable. When contract terms are modified in an approval process, legal needs documentation that proves exactly what happened.

Form.io provides two complementary logging systems that together create a complete audit picture. Submission Revisions track field-level changes within individual submissions over time. Server Audit Logging captures all system activity including form access, user authentication, and data modifications at the API level. 

Submission Revisions: Field-Level Change Tracking

Submission Revisions track every modification to a submission’s data after initial capture. When enabled on a form, each update to a submission creates a new revision record containing the complete submission state, the user who made the change, a timestamp, and optional notes explaining why the change was made.

Enable Submission Revisions in the form’s settings under the Revisions section. Select “Enable” from the Submission Revisions dropdown. From that point forward, every submission update preserves the previous state.

{
  "_id": "657b9e7b4001c82890626a5e",
  "_vid": 3,
  "data": {
    "patientName": "Jane Doe",
    "dosage": "50mg",
    "prescribingPhysician": "Dr. Smith"
  },
  "modified": "2024-01-15T14:32:00.000Z",
  "modifiedBy": "659d83632824949f20a88389",
  "revisionNote": "Dosage adjusted per patient follow-up consultation"
}

The _vid field indicates the submission version. Each update increments this value. The modifiedBy field references the user who made the change. The revisionNote field captures context provided by the user at the time of modification.

The portal’s submission view displays the complete revision history. You can see every version, compare changes between versions, and revert to any previous state. Reverting does not destroy history; it creates a new revision that copies the selected previous state.

How Submission Revisions Differ from Form Revisions

Submission Revisions and Form Revisions serve different purposes and track different things. Understanding the distinction matters for compliance planning.

Form Revisions track changes to the form schema itself. When you add a field, remove a field, or modify validation rules, Form Revisions preserve the previous form structure. Submissions reference the form revision against which they were captured via the _fvid property.

Submission Revisions track changes to individual submission data. When a user updates their answers, corrects a mistake, or an administrator modifies a value, Submission Revisions preserve the previous data state.

A typical audit scenario involves both: “This submission was captured on January 5th using form revision 3. The user then updated their response on January 10th, creating submission revision 2. The form itself was modified on January 15th, creating form revision 4, but the original submission still renders against form revision 3.”

Both systems are part of the Security Module. Contact Form.io for licensing details.

PDF Change Log Export

For compliance documentation that needs to leave the system, Form.io generates PDF reports containing the complete submission revision history. Enable this in form settings under PDF Settings by checking “Show Change Log.”

When you download a PDF of any submission with this option enabled, the document includes a change log section containing the revision ID for each version, the user who made the modification, the date and time of the change, any revision notes provided, and a field-by-field list of what changed between versions.

This PDF output serves as compliance evidence for audits. Healthcare organizations use it to document medication changes for HIPAA compliance. Financial services firms use it to demonstrate SOX compliance for data modifications. Government contractors use it to satisfy FedRAMP audit requirements.

The PDF export happens through Form.io’s PDF generation system. You can customize headers and footers to include organization branding, submission identifiers, or other context that auditors require.

Server Audit Logging: System-Wide Activity Tracking

While Submission Revisions track data changes, Server Audit Logging captures the broader context of system activity. Every API request, authentication attempt, form access, and data modification generates a log entry.

Audit logs output to standard out for the Docker container and can be routed to any log aggregation system. The Audit Logging documentation provides configuration details for integration with Elasticsearch or Kibana enterprise logging.

Each log entry follows a standard format:

date EVENT uuid projectId sessionId userId [additional information]

Events tracked include authentication success and failure (with counts for brute force detection), API request start and completion with response codes and timing, data access events for submissions, forms, projects, and roles, data modification events including creation and updates, and form revision access.

For example, when a user views a submission:

2024-04-25T17:43:17.654Z SUBMISSION_READ
4d7649c7-d24c-4b61-bc7e-6e672186eca6 6627c5f740a5d95c7edc30ab 662aa339cf86fe3fba0343fe 659d83632824949f20a88389 662aa865cf86fe3fba034d96 662aa7bccf86fe3fba034afa

This entry captures the timestamp, event type, request UUID (for correlating related events), project ID, session ID, user ID, submission ID, and form ID. When an auditor asks “who accessed this submission and when,” the logs provide the answer.

Correlating Events with Request UUIDs

The UUID field in audit logs enables correlation of related events. Every API request generates a REQUEST_START event with a UUID. All subsequent events within that request share the same UUID until REQUEST_END.

This matters for understanding complex operations. A single user action might trigger validation, conditional logic evaluation, webhook firing, and database updates. The shared UUID groups all these events together, creating a coherent narrative of what happened during that request.

When investigating an incident, filter logs by UUID to see the complete sequence of events that constituted a single operation.

What Gets Logged vs What Does Not

Audit logging tracks access and modification events at the API level. It records that a submission was created, by whom, and when. It does not record what specific field values were set. For field-level detail, you need Submission Revisions.

The distinction is intentional. Audit logs generate at high volume in active systems. Including complete submission payloads would create storage and performance problems. Submission Revisions provide the field-level detail but only for forms where you explicitly enable the feature.

A complete compliance implementation typically uses both: audit logs for system-wide activity monitoring and access tracking, plus Submission Revisions on forms containing sensitive data that requires field-level change documentation.

Authentication events include additional detail for security monitoring. Failed login attempts log the attempted username and track consecutive failure counts. This enables detection of credential stuffing attacks or brute force attempts. The EAUTH_LOGINCOUNT event specifically tracks repeated failures for security alerting.

Integration with Log Aggregation Systems

Enterprise deployments route Form.io audit logs to centralized logging infrastructure. The documentation provides configuration examples for the Elastic Stack (Elasticsearch, Kibana, Filebeat).

The general pattern involves configuring Filebeat to read Docker container logs from /var/lib/docker/containers/, processing the JSON-formatted log entries, enriching with Docker metadata (container names, image names), and forwarding to Elasticsearch for indexing and retention.

Kibana then provides search, filtering, visualization, and alerting capabilities. You can create dashboards showing authentication failure rates, API request volumes, data modification patterns, or any other metrics relevant to your compliance and security monitoring requirements.

Other log aggregation systems like Splunk, Datadog, or AWS CloudWatch follow similar patterns. The key is that Form.io outputs structured log data to standard out, which container orchestration platforms can route wherever your infrastructure requires.

Retention and Storage Considerations

Submission Revisions store complete submission snapshots for every modification. For forms with frequent updates and large data payloads, this accumulates storage over time. Plan capacity accordingly and consider retention policies for older revisions.

Audit logs similarly accumulate at scale. A busy system might generate thousands of log entries per hour. Your log aggregation infrastructure needs appropriate capacity, and you should configure retention policies that meet compliance requirements without unbounded growth.

Form.io does not impose retention limits. Your compliance requirements determine how long to keep logs and revision history. Healthcare organizations might need seven years of records. Financial services might need different retention periods for different data types. Configure your infrastructure accordingly.

When to Enable Each Logging System

Enable Submission Revisions when:

  • The form captures data subject to regulatory audit requirements
  • Users or administrators will update submissions after initial capture
  • You need field-level change documentation for compliance
  • Legal or operational review requires understanding exactly what changed and when

Enable Server Audit Logging when:

  • You need to track who accessed what data and when
  • Security monitoring requires authentication event visibility
  • Compliance requires system-wide activity documentation
  • You need to investigate incidents or unusual activity patterns

For most enterprise deployments, both systems should be active. They complement each other: audit logs provide breadth across all system activity, Submission Revisions provide depth for specific sensitive forms.

Disabling Audit Logging

If your deployment does not require audit logging, set the NOAUDITLOG flag to true in your environment configuration. This reduces log volume and associated storage costs. Only disable if you have confirmed that your compliance requirements do not mandate activity logging.

Submission Revisions are controlled per-form, so you can enable them selectively only on forms that require change tracking rather than globally.

Related Resources