new: Support Audit log

[florianm]

• Closes Support for timing audit #164
• Closes new: metadata kind email and new control for Audit #284 - this PR presents audit options in a more logical manner to the user.
• Audit settings are form properties like autosend/delete. Audit settings are form-wide, once per form, have no defined position in the form (unlike questions where position matters), and must be unique (once or nonce per form, again unlike questions). All of this speaks against a drag and drop question like metadata, and for form properties.
• Code comments and console logging for clarity, if a bit noisy. Note: I've swapped the order of logging halfway through screenshotting the walk-through - track changes logs before location audit.
• Form props modal widened to fit four new fields by dropping CSS class .narrowModal. Field labels are wider to accommodate the longer new labels. Could use a designer's eye to verify spacing / margins.
• User-facing labels and wording are as clear as I could make them, not directly as per the terser and more technical wording in the XForms spec.
• Internal labels are exactly as per XForms spec to facilitate code search.

Impressions

Screen shots and walk-through below.

New form defaults

A new form shows "all off" defaults.

New form, track changes

Enable track changes adds data/meta/audit and <bind nodeset="data/meta/audit" type="binary" odk:track-changes="true"/>.

<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://openrosa.org/javarosa" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:orx="http://openrosa.org/xforms" xmlns:odk="http://www.opendatakit.org/xforms">
  <h:head>
    <h:title>Untitled Form</h:title>
    <model>
      <instance>
        <data id="Untitled-Form" version="1644203944">
          <meta>
            <instanceID/>
            <audit/>
          </meta>
        </data>
      </instance>
      <itext>
        <translation lang="English">
        </translation>
      </itext>
      <bind nodeset="/data/meta/instanceID" type="string" readonly="true()" jr:preload="uid"/>
      <bind nodeset="data/meta/audit" type="binary" odk:track-changes="true"/>
    </model>
  </h:head>
  <h:body>
  </h:body>
</h:html>

Console log:

New form, track changes, track location

Setting the "Track device location" to e.g. "Balanced", retaining the defaults for min interval and max age:

This adds the three location audit attributes to the bind node <bind nodeset="data/meta/audit" type="binary" odk:location-priority="balanced" odk:location-min-interval="20" odk:location-max-age="60" odk:track-changes="true"/>:

<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://openrosa.org/javarosa" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:orx="http://openrosa.org/xforms" xmlns:odk="http://www.opendatakit.org/xforms">
  <h:head>
    <h:title>Untitled Form</h:title>
    <model>
      <instance>
        <data id="Untitled-Form" version="1644204193">
          <meta>
            <instanceID/>
            <audit/>
          </meta>
        </data>
      </instance>
      <itext>
        <translation lang="English">
        </translation>
      </itext>
      <bind nodeset="/data/meta/instanceID" type="string" readonly="true()" jr:preload="uid"/>
      <bind nodeset="data/meta/audit" type="binary" odk:location-priority="balanced" odk:location-min-interval="20" odk:location-max-age="60" odk:track-changes="true"/>
    </model>
  </h:head>
  <h:body>
  </h:body>
</h:html>

Console log:

New form, disable track changes, keep location audit

Setting "Track changes" to "No" and changing "Track device location" to "High accuracy":

The data/meta/audit node is still there, and the bind node now shows track changes as false

<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://openrosa.org/javarosa" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:orx="http://openrosa.org/xforms" xmlns:odk="http://www.opendatakit.org/xforms">
  <h:head>
    <h:title>Untitled Form</h:title>
    <model>
      <instance>
        <data id="Untitled-Form" version="1644204368">
          <meta>
            <instanceID/>
            <audit/>
          </meta>
        </data>
      </instance>
      <itext>
        <translation lang="English">
        </translation>
      </itext>
      <bind nodeset="/data/meta/instanceID" type="string" readonly="true()" jr:preload="uid"/>
      <bind nodeset="data/meta/audit" type="binary" odk:location-priority="high-accuracy" odk:location-min-interval="20" odk:location-max-age="60" odk:track-changes="false"/>
    </model>
  </h:head>
  <h:body>
  </h:body>
</h:html>

Console log:

Existing form

In an existing form, the new form properties are not set, defaulting to "all off".

Exporting to XML creates neither a data/meta/audit node nor a bind node.

Existing form plus track changes

Exported XML now has data/meta/audit node and <bind nodeset="data/meta/audit" type="binary" odk:track-changes="true"/>.

Existing form plus track changes plus location audit

Location min interval and max age are kept empty.

Exported XML has data/meta/audit node and has expanded <bind nodeset="data/meta/audit" type="binary" odk:track-changes="true" odk:location-priority="balanced" odk:location-min-interval="20" odk:location-max-age="60"/> with sensible defaults.

The console explains what happened:

Existing form with location audit minus track changes

Setting "Track changes" to "No" works as expected:
Exported XML has data/meta/audit node and has <bind nodeset="data/meta/audit" type="binary" odk:track-changes="false" odk:location-priority="balanced" odk:location-min-interval="20" odk:location-max-age="60"/>.

We still haven't bothered with min/max attributes and still get the explanation about the defaults.

Saving a new form with audit

A new form with audit properties set and saved does remember these settings when loaded again.

[florianm]

Re labels: More verbose labels could read like

Track form changes:

• No, do not track form changes
• Yes, track form changes

Track device location:

• No, do not track location
• Yes, with low accuracy and minimal power consumption
• Yes, with balanced accuracy and power consumption
• Yes, with highest accuracy and power consumption

The console log, if retained, could also be worded more consistently.

[lognaturel]

Looking great. I believe all my concerns from the prior PR have been addressed. I don't think the labels need to be more verbose. However, there is one option missing which is audit log without any modifiers. That's different from track changes. It's just collecting the flow through the form. Could you perhaps disable all of the modifiers you have now until audit is turned on?

[florianm]

Ah so there is a plain vanilla audit flavour without track changes or location?

Should I add another form property "Enable form audit" (yes/no) to toggle the audit bind node, and let the audit modifiers add attributes as appropriate?

Or should I merge this with "Track changes" into a form property "Form audit" with options

• Disabled
• Enabled, track screen flow
• Enabled, track screen flow and form changes

@lognaturel if I could pick your brain on the above (which impacts if/else logic building the bind node), I could get started and we could refine the wording of the labels later.

[lognaturel]

I take it there’s no straightforward way to do what I described with a first option to turn on audit and then a section that is only enabled/visible if audits are on?

If not, I guess your combination is ok. Then the location text can maybe make it clear that the flow is also captured. It’s weird because you could set “Disabled” for your new setting and configure location capture. But the basic audit would still be created. If that suits your needs, I’m fine with starting there and revisiting if needed.

It would be helpful to make it more clear that the new options added here result in data captured in a separate audit file.

[florianm]

Thanks for the clarification! I hear your preference as:

• A new form property "Form audit":
  • options yes/no
  • help text "Form audit logs the timing of how and when the form is filled."
  • If yes, the other audit options are shown as per screenshots and in the XML, audit nodes are inserted. The bind node has no attributes.
  • If no (or blank in existing forms), the other audit options are toggled invisible to avoid confusion.
• If any of the subsequent audit attributes are not blank (track changes or location), they will populate the attributes of the audit node added through the "Form audit".

Does the XForms standard support https://docs.getodk.org/form-audit-log/#reason-for-changes and https://docs.getodk.org/form-audit-log/#enumerator-identification? I'd expect we could include these options here too seeing Collect supports them since v1.25.0.

[florianm]

Teaser! Does this look about right?

[lognaturel]

A+++, thanks!

[florianm]

Update:
All in

XML: the "new-to-XForms" attributes odk:track-changes-reasons="on-form-edit" odk:identify-user="true" which are documented in the ODK docs but not yet in the XForms spec for audit attributes are included last in the bind node. They appear to work fine!

<bind nodeset="data/meta/audit" type="binary" odk:location-priority="balanced" odk:location-min-interval="20" odk:location-max-age="60" odk:track-changes="true" odk:track-changes-reasons="on-form-edit" odk:identify-user="true"/>

ODK Validate finds no errors, but also did not find an error I corrected since (odk:track-changes-reasons="true"), so I assume it does not support the new audit attributes yet.

Test Xform
Test submissions

Testing on my end: The above form seems to work as advertised.

• ODK Collect c2022.1.0
  • prompts for user identity (odk:identify-user="true") on form entry
  • tracks location (odk:location-priority="balanced" odk:location-min-interval="20" odk:location-max-age="60")
  • does capture start geopoint without my interaction
  • does capture geolocation when I press "start geopoint"
• ODK Central 1.3.0
• exports the audit in one file per submission, plus one master file with all audits (subtle differences: no change reason in master file)

Last nitpick is a minor bug in the visibility toggles for fresh loaded Build sessions when loading existing forms with saved "yes" attributes - they need to toggle to no, then to yes in order to show the initially hidden form properties.

[florianm]

Final touch: "show all properties" bottom right

The perfect solution would be if we could calculate visibility on each opening of the modal dialogue based on the saved fields, but I'm all out of playtime for this one.

This PR is ready to review again for requested changes.

[lognaturel]

Looks good! And there will be a corresponding 2xlsform thing?

[florianm]

Absolutely! We could go like this:
Once the current batch of PRs is in master I'll send corresponding PRs for build2xlsform. Once those are merged we could roll them out together (possibly in the all new docker-compose deploy), first to staging for a thorough test cycle, then to prod once all bugs are sorted out.