Features: Return publishing notes for the Form and Versions API (#1823)

* Features: Return publishing notes for the Form and Versions API

* Incorporated PR Feedback

* Include publishNotes explicitly instead

Author: sadiqkhoja

docs/api.yaml

@@ -41,6 +41,11 @@ info:
 
     Here major and breaking changes to the API are listed by version.
 
+    ## ODK Central v2026.2
+
+    **Changed**:
+    - The [Getting Form Details](/central-api-form-management/#getting-form-details), [Listing Published Form Versions](/central-api-form-management/#listing-published-form-versions) and [Getting Form Version Details](/central-api-form-management/#getting-form-version-details) endpoints now return a `publishNotes` field in extended metadata. 
+
     ## ODK Central v2026.1
 
     **Added**:
@@ -3356,7 +3361,7 @@ paths:
                 updatedAt: 2018-03-21T12:45:02.312Z
             application/json; extended:
               schema:
-                $ref: '#/components/schemas/ExtendedForm'
+                $ref: '#/components/schemas/ExtendedFormWithPublishNotes'
               example:
                 projectId: 1
                 xmlFormId: simple
@@ -3384,6 +3389,7 @@ paths:
                   deletedAt: 2018-04-18T23:42:11.406Z
                 entityRelated: false
                 publicLinks: 4
+                publishNotes: 'Fixed validation rules for required fields'
     delete:
       tags:
       - Individual Form
@@ -4613,6 +4619,7 @@ paths:
                   type: user
                   updatedAt: 2018-04-18T23:42:11.406Z
                   deletedAt: 2018-04-18T23:42:11.406Z
+                publishNotes: Fixed validation rules for required fields
   /v1/projects/{projectId}/forms/{xmlFormId}/versions/{version}:
     get:
       tags:
@@ -4654,6 +4661,9 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Form'
+            application/json; extended:
+              schema:
+                $ref: '#/components/schemas/ExtendedFormVersion'
   /v1/projects/{projectId}/forms/{xmlFormId}/versions/{version}.xml:
     get:
       tags:
@@ -12609,6 +12619,15 @@ components:
               type: number
               example: 4
               description: The number of Public Links that can submit to the Form. This does not include Public Links that have been revoked.
+    ExtendedFormWithPublishNotes:
+      allOf:
+        - $ref: '#/components/schemas/ExtendedForm'
+        - type: object
+          properties:
+            publishNotes:
+              type: string
+              example: Fixed validation rules for required fields
+              description: The notes provided when the current Form version was published (via the `X-Action-Notes` header). Only returned to users with `form.update` permission.
     ExtendedFormVersion:
       allOf:
         - $ref: '#/components/schemas/Form'
@@ -12620,6 +12639,10 @@ components:
             excelContentType:
               type: string
               description: If the Form was created by uploading an Excel file, this field contains the MIME type of that file.
+            publishNotes:
+              type: string
+              example: Fixed validation rules for required fields
+              description: The notes provided when this version was published (via the `X-Action-Notes` header). Only returned to users with `form.update` permission.
     FormAttachment:
       type: object
       required:

lib/model/frames/form.js

@@ -160,8 +160,9 @@ Form.Partial = class extends Form {};
 // EXTENDED FORM
 
 Form.Extended = class extends Frame.define(
+  into('formExtended'),
   'submissions',        readable,       'lastSubmission', readable,
-  'excelContentType',   readable,
+  'excelContentType',   readable,       'publishNotes',
   // counts of submissions in various review states
   'receivedCount',                      'hasIssuesCount',
   'editedCount',                        'entityRelated',  readable,
@@ -183,7 +184,11 @@ Form.Extended = class extends Frame.define(
   }
 };
 
-Form.ExtendedVersion = Frame.define('excelContentType', readable);
+Form.ExtendedVersion = Frame.define(
+  into('formVersionExtended'),
+  'excelContentType', readable,
+  'publishNotes'
+);
 
 
 ////////////////////////////////////////////////////////////////////////////////

lib/model/query/forms.js

@@ -607,7 +607,7 @@ const _getVersions = extender(Form, Form.Def)(Form.ExtendedVersion, Option.of(Ac
 select ${fields} from forms
 join form_defs on ${versionJoinCondition(Form.AllVersions)}
 ${extend|| sql`
-  left outer join (select * from audits where action='form.update.publish') as audits
+  left outer join (select "acteeId", "actorId", details, notes as "publishNotes" from audits where action='form.update.publish') as audits
     on forms."acteeId"=audits."acteeId" and audits.details->'newDefId'=to_jsonb(form_defs.id)
   left outer join actors on audits."actorId"=actors.id
   left outer join (select id, "contentType" as "excelContentType" from blobs) as xls
@@ -667,6 +667,8 @@ ${extend|| sql`
     on forms.id=submission_stats."formId"
   left outer join (select * from audits where action='form.create') as audits
     on forms."acteeId"=audits."acteeId"
+  left outer join (select "acteeId", details, notes as "publishNotes" from audits where action='form.update.publish') as publish_audits
+    on forms."acteeId"=publish_audits."acteeId" and publish_audits.details->'newDefId'=to_jsonb(form_defs.id)
   left outer join actors on audits."actorId"=actors.id
   left outer join (select id, "contentType" as "excelContentType" from blobs) as xls
     on form_defs."xlsBlobId"=xls.id

lib/resources/forms.js

@@ -29,14 +29,25 @@ const excelMimeTypes = {
   xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
 };
 
-const canReadForm = (auth, form) => {
+const checkActorVerbs = (actorVerbs, requiredVerbs) => {
+  const actorVerbsSet = new Set(actorVerbs);
+  if (requiredVerbs.every(v => !actorVerbsSet.has(v))) {
+    return reject(Problem.user.insufficientRights());
+  }
+};
+
+const canReadForm = async (authOrVerbs, form) => {
+  const verbs = authOrVerbs instanceof Array
+    ? authOrVerbs
+    : (await authOrVerbs.verbsOn(form));
   if (form.def?.publishedAt == null) {
-    return auth.canOrReject('form.update', form);
+    await checkActorVerbs(verbs, ['form.update']);
   } else if (form.state === 'closed') {
-    return auth.canOrReject('form.read', form);
+    await checkActorVerbs(verbs, ['form.read']);
   } else {
-    return auth.canOrReject(['open_form.read', 'form.read'], form);
+    await checkActorVerbs(verbs, ['open_form.read', 'form.read']);
   }
+  return form;
 };
 // Returns QueryOptions to use to limit entity access according to ownerOnly.
 const getOwnerOnlyOptions = async (auth, project) => ((await auth.can('entity.list', project))
@@ -276,9 +287,19 @@ module.exports = (service, endpoint, anonymousEndpoint) => {
     service.get(`${base}.xls`, getXls('xls'));
     service.get(`${base}.xlsx`, getXls('xlsx'));
 
-    service.get(`${base}`, endpoint(({ Forms }, { auth, params, queryOptions }) =>
-      getInstance(Forms, params, false, queryOptions)
-        .then((form) => canReadForm(auth, form))));
+    service.get(`${base}`, endpoint(async ({ Forms }, { auth, params, queryOptions }) => {
+      const form = await getInstance(Forms, params, false, queryOptions);
+
+      const verbs = await auth.verbsOn(form);
+
+      await canReadForm(verbs, form);
+
+      if (verbs.includes('form.update') && queryOptions.extended) {
+        return { ...form.forApi(), publishNotes: form.aux.formExtended.publishNotes };
+      }
+
+      return form;
+    }));
 
     // returns form fields, optionally sanitizing names to match odata.
     service.get(`${base}/fields`, endpoint(({ Forms }, { params, query, auth }) =>
@@ -365,12 +386,21 @@ module.exports = (service, endpoint, anonymousEndpoint) => {
   ////////////////////////////////////////
   // VERSIONS LISTING
 
-  service.get('/projects/:projectId/forms/:xmlFormId/versions', endpoint(({ Forms }, { auth, params, queryOptions }) =>
-    Forms.getByProjectAndXmlFormId(params.projectId, params.xmlFormId, Form.AnyVersion)
-      .then(getOrNotFound)
-      .then((form) => canReadForm(auth, form))
-      .then((form) => Forms.getVersions(form.id, queryOptions))));
+  service.get('/projects/:projectId/forms/:xmlFormId/versions', endpoint(async ({ Forms }, { auth, params, queryOptions }) => {
+    const form = await Forms.getByProjectAndXmlFormId(params.projectId, params.xmlFormId, Form.AnyVersion)
+      .then(getOrNotFound);
+
+    const verbs = await auth.verbsOn(form);
 
+    await canReadForm(verbs, form);
+
+    const versions = await Forms.getVersions(form.id, queryOptions);
+
+    if (verbs.includes('form.update') && queryOptions.extended) {
+      return versions.map(v => ({ ...v.forApi(), publishNotes: v.aux.formVersionExtended.publishNotes }));
+    }
+    return versions;
+  }));
 
   ////////////////////////////////////////
   // RESTORE / UNDELETE

test/integration/api/forms/forms.js

@@ -7,6 +7,7 @@ const superagent = require('superagent');
 const { DateTime } = require('luxon');
 const { testService } = require('../../setup');
 const testData = require('../../../data/xml');
+const { publishWithNote } = require('../../../util/scenarios');
 const { Form } = require(appRoot + '/lib/model/frames');
 const { exhaust } = require(appRoot + '/lib/worker/worker');
 const { omit } = require(appRoot + '/lib/util/util');
@@ -1092,6 +1093,115 @@ describe('api: /projects/:id/forms (create, read, update)', () => {
                     body.enketoOnceId.should.equal('::::abcdefgh');
                   }));
             }))));
+
+      describe('publishNotes', () => {
+        it('should return publishNotes with extended metadata', testService(async (service) => {
+          const asAlice = await service.login('alice');
+
+          await publishWithNote(asAlice, '2', 'this is a publishing note');
+
+          const { body } = await asAlice.get('/v1/projects/1/forms/simple')
+            .set('X-Extended-Metadata', true)
+            .expect(200);
+
+          body.publishNotes.should.equal('this is a publishing note');
+        }));
+
+        it('should not return publishNotes for app-user', testService(async (service) => {
+          const asAlice = await service.login('alice');
+
+          await publishWithNote(asAlice, '2', 'this is a publishing note');
+
+          const appUser = await asAlice.post('/v1/projects/1/app-users')
+            .send({ displayName: 'test app user' })
+            .expect(200)
+            .then(({ body }) => body);
+          await asAlice.post(`/v1/projects/1/forms/simple/assignments/app-user/${appUser.id}`)
+            .expect(200);
+
+          const { body } = await service.get(`/v1/key/${appUser.token}/projects/1/forms/simple`)
+            .set('X-Extended-Metadata', true)
+            .expect(200);
+
+          should.not.exist(body.publishNotes);
+        }));
+
+        it('should not return publishNotes for project-viewer', testService(async (service) => {
+          const asAlice = await service.login('alice');
+
+          await publishWithNote(asAlice, '2', 'this is a publishing note');
+
+          const chelsea = await service.login('chelsea');
+          const chelseaActorId = await chelsea.get('/v1/users/current')
+            .expect(200)
+            .then(({ body }) => body.id);
+          await asAlice.post(`/v1/projects/1/assignments/viewer/${chelseaActorId}`)
+            .expect(200);
+
+          const { body } = await chelsea.get('/v1/projects/1/forms/simple')
+            .set('X-Extended-Metadata', true)
+            .expect(200);
+
+          should.not.exist(body.publishNotes);
+        }));
+
+        it('should not return publishNotes for data-collector', testService(async (service) => {
+          const asAlice = await service.login('alice');
+
+          await publishWithNote(asAlice, '2', 'this is a publishing note');
+
+          const chelsea = await service.login('chelsea');
+          const chelseaActorId = await chelsea.get('/v1/users/current')
+            .expect(200)
+            .then(({ body }) => body.id);
+          await asAlice.post(`/v1/projects/1/assignments/formfill/${chelseaActorId}`)
+            .expect(200);
+
+          const { body } = await chelsea.get('/v1/projects/1/forms/simple')
+            .set('X-Extended-Metadata', true)
+            .expect(200);
+
+          should.not.exist(body.publishNotes);
+        }));
+
+        it('should not return publishNotes for data-collector using /forms endpoint', testService(async (service) => {
+          const asAlice = await service.login('alice');
+
+          await publishWithNote(asAlice, '2', 'this is a publishing note');
+
+          const chelsea = await service.login('chelsea');
+          const chelseaActorId = await chelsea.get('/v1/users/current')
+            .expect(200)
+            .then(({ body }) => body.id);
+          await asAlice.post(`/v1/projects/1/assignments/formfill/${chelseaActorId}`)
+            .expect(200);
+
+          const { body } = await chelsea.get('/v1/projects/1/forms')
+            .set('X-Extended-Metadata', true)
+            .expect(200);
+
+          body.length.should.be.greaterThan(0);
+          body.forEach((form) => should.not.exist(form.publishNotes));
+        }));
+
+        it('should not return publishNotes for data-collector using /projects?forms=true endpoint', testService(async (service) => {
+          const asAlice = await service.login('alice');
+
+          await publishWithNote(asAlice, '2', 'this is a publishing note');
+
+          const chelsea = await service.login('chelsea');
+          const chelseaActorId = await chelsea.get('/v1/users/current')
+            .expect(200)
+            .then(({ body }) => body.id);
+          await asAlice.post(`/v1/projects/1/assignments/formfill/${chelseaActorId}`)
+            .expect(200);
+
+          const { body: projects } = await chelsea.get('/v1/projects?forms=true')
+            .expect(200);
+
+          projects[0].formList.forEach((form) => should.not.exist(form.publishNotes));
+        }));
+      });
     });
 
     ////////////////////////////////////////