Client Audit Logs

Introduction

This specification is a sub-specification of the ODK XForms Specification. It describes the structure of client audit logs which a form definition can request using the orx:audit element as listed in the metadata section.

CSV Format

Audit log CSVs generated by clients must:

  • use UTF-8 character encoding
  • use commas as separators
  • use NIX line endings (\n)
  • escape values with commas or newlines by wrapping the value in double quotes (")
  • escape double quotes by prepending another double quote only if a value containing commas or newlines also contains double quotes
  • include a single header row including some or all of the column names described below

Header Column Names

All audit log CSVs generated by clients must include a header row. That header row must define the following columns:

  • event: an identifier for the event being tracked (see Events section for valid identifiers)
  • node: for events that refer to a specific node, the XPath path of that node
  • start: a timestamp represented as the number of milliseconds since midnight, January 1, 1970 UTC
  • end: for events that have an end time, a timestamp represented as the number of milliseconds since midnight, January 1, 1970 UTC

If location tracking is configured by the form definition (see audit attributes), audit log CSVs generated by clients must define the following additional columns:

  • latitude
  • longitude
  • accuracy

If change tracking is configured by the form definition (see audit attributes), audit log CSVs generated by clients must define the following additional columns:

  • old-value: the value of the node at time of the start of the event
  • new-value: the value of the node at time of the end of the event

Events

Currently, ODK Collect is the only client known to implement this sub-specification. Supported events are listed in its user-facing documentation. As additional clients implement audit logging, standard and client-specific events will be listed here.