You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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.
The text was updated successfully, but these errors were encountered:
ktuite
changed the title
Refactor Form creation/update paths to fit better with entities
Streamline Form creation/update/publish paths
May 2, 2024
ktuite
changed the title
Streamline Form creation/update/publish paths
Streamline Form creation/update/publish paths to better fit with Entities
May 2, 2024
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
Forms.createNew(...)
form.create
Path 2: Create new form draft and publish immediately
/projects/:projectId/forms?publish=true
Forms.createNew(...)
which can publish while insertingform.create
andform.update.publish
Path 3: Copy published form def to make new draft
/projects/:projectId/forms/:id/draft
(empty body)Forms.createVersion(...)
on partial pulled from previous form def as though it were uploadedform.update.draft.set
Path 4: Upload form to make new draft
/projects/:projectId/forms/:id/draft
(with new xml)Form.createVersion(...)
form.update.draft.set
Path 5: Upload form to overwrite draft
/projects/:projectId/forms/:id/draft
(with new xml, very similar to above)Form.createVersion(...)
which removes intermediate draftPath 6: Publish form while making a copy of the draft def with a different version
/projects/:projectId/forms/:id/draft/publish?version=newVersion
Form.createVersion(...)
with publish=false flagform.update.draft.set
Forms.publish(...)
form.update.publish
Path 7: Publish draft form
/projects/:projectId/forms/:id/draft/publish
Forms.publish(...)
form.update.publish
Path 8: Encrypting a form
Forms.createVersion
and either publishes or notOther things going on when creating a new version of a form:
There are some things that happen both for new forms and updated forms
getFormFields(xml)
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
andcreateVersion
didn't conditionally publish.Forms.publish()
call. This path mainly exists for our convenience as devs for testing.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 happenpublishedAt
timestamp to thecreatedAt
timestamp when the intention is for these things to happen simultaneously.The Dataset functions like
createOrMerge
andpublishIfExists
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 inForms.publish
for example.createNew
andcreateVersion
could share form/dataset parsing functionality, potentially.The text was updated successfully, but these errors were encountered: