Streamline Form creation/update/publish paths to better fit with Entities

[ktuite]

There are a number of different paths that Forms can take (to be created, updated, or published) and the way these intersect with Datasets can be hard to keep track of.

The various lives of Forms

Path 1: Create new form draft

• /projects/:projectId/forms
• Uses Forms.createNew(...)
• Logs form.create

Path 2: Create new form draft and publish immediately

• /projects/:projectId/forms?publish=true
• Uses Forms.createNew(...) which can publish while inserting
• Logs form.create and form.update.publish

Path 3: Copy published form def to make new draft

• /projects/:projectId/forms/:id/draft (empty body)
• Uses Forms.createVersion(...) on partial pulled from previous form def as though it were uploaded
• Logs form.update.draft.set

Path 4: Upload form to make new draft

• /projects/:projectId/forms/:id/draft (with new xml)
• Uses Form.createVersion(...)
• Logs form.update.draft.set

Path 5: Upload form to overwrite draft

• /projects/:projectId/forms/:id/draft (with new xml, very similar to above)
• Uses Form.createVersion(...) which removes intermediate draft

Path 6: Publish form while making a copy of the draft def with a different version

• /projects/:projectId/forms/:id/draft/publish?version=newVersion
• Uses Form.createVersion(...) with publish=false flag
• Logs form.update.draft.set
• Uses Forms.publish(...)
• Logs form.update.publish

Path 7: Publish draft form

• /projects/:projectId/forms/:id/draft/publish
• Uses Forms.publish(...)
• Logs form.update.publish

Path 8: Encrypting a form

• ...
• Uses Forms.createVersion and either publishes or not

Other things going on when creating a new version of a form:

• Clearing draft submissions
• Clearing orphaned form drafts
• The schema is checked against existing form schemas to avoid duplicating form fields
• If the schema has changed, there are checks about structural changes (down casting field types, etc.)
• Form attachments are dealt with
• Form attachments may be auto-linked to datasets on publish
• Enketo ids generated (for drafts and published forms)

There are some things that happen both for new forms and updated forms

• Parsing of the form for the form fields: getFormFields(xml)
• Parsing of the dataset info out of the form: getDataset(xml)

Like Forms, Datasets can also be drafts or published, and it's hard to think about their state overlaid on Form states.

What I'd like to change:

• I wish createNew and createVersion didn't conditionally publish.

  • The case of creating a new form and publishing at the same time could be handled with a separate Forms.publish() call. This path mainly exists for our convenience as devs for testing.
  • The only time createVersion is ever used with published is when copying over a published form to encrypt it.

• Forms.publish() should be the only place publishing-related code has to happen

  • Enketo things can happen here
  • It can do more of the things around Dataset publishing. And auto-linking.
  • It could do something fancy like set the publishedAt timestamp to the createdAt timestamp when the intention is for these things to happen simultaneously.
  • Maybe it could also do the draft submission and draft form cleanup.

• The Dataset functions like createOrMerge and publishIfExists could stay the same. Maybe their meaning would be clearer without having to consider the conditional form publishing in which they are called.

  • publishIfExists could always only be called in Forms.publish for example.

• createNew and createVersion could share form/dataset parsing functionality, potentially.