Survey lifecycle
Author a draft, publish explicitly, and preserve every response snapshot.
Each survey stores three independent concerns:
draftJson— the editable SurveyJS documentpublishedJson— the document new responses may startsettings— collection policy owned by dimah-survey
Creator writes the draft. Publishing explicitly promotes that draft. Starting
a response copies the published document into response.definition.
saveSurvey only replaces draftJson. It never publishes, changes collection
settings, or updates an existing response.
Status and availability
| Status | Meaning | Can start a response? |
|---|---|---|
draft | No published document exists | No; NOT_PUBLISHED |
active | publishedJson is available to fill | Yes, while collection is open |
archived | Collection is stopped; published JSON is retained | No; NOT_PUBLISHED |
GET /survey/published on the fill handler returns publishedJson and
settings for an active survey. It never exposes draftJson. The read remains
available outside the collection window so the application can render a closed
state; start and writes fail with SURVEY_CLOSED.
Authoring operations
| Operation | Effect |
|---|---|
saveSurvey | Create the row or replace draftJson; insert default settings once |
publishSurvey | Copy draftJson to publishedJson, set active, and update publishedAt |
archiveSurvey | Set archived without deleting either document |
resumeSurvey | Return an archived, previously published survey to active |
saveSurveySettings | Replace the complete settings object without touching either document |
resumeSurvey does not copy draftJson. An already active survey is returned
unchanged. An archived survey with no published document throws
NOT_PUBLISHED, and resume never runs publish hooks.
Publish runs onPublish before the write and afterPublish after it.
onPublish may abort; an afterPublish failure leaves the published row in
place. See Configuration.
IDs and slugs
The application chooses id. On create, slug defaults to that id and must be
unique; a conflicting write throws SLUG_TAKEN.
getSurvey and getPublishedSurvey accept an id or a slug in the id query.
startResponse accepts either value in surveyId.
Protect concurrent changes
Draft, publish, archive, settings, and resume accept expectedUpdatedAt from
the last read. The store compares it inside the write and rejects a stale
request with STALE_UPDATE.
Omit the token only when a last-write-wins update is intentional. Creating a
survey with expectedUpdatedAt set fails with STALE_UPDATE, because there is
no row to compare.
useSurveyDraft sends the token it last read. See Creator.
Publish changes the future, not history
Existing drafts, submitted responses, and abandoned responses keep their stored
definition. Only a newly created response copies the latest
publishedJson.
There is no separate survey-version table. The snapshot on each response is the version history that matters.