[Levelbuilder] Foorm Editor: Editing a Form
If you have a json parsing error, the preview will turn off and you will see error messages next to your json. Sometimes the errors can be a little confusing. It is helpful to know the basics of JSON to fix these. For example, if you have a list of items, it will be surrounded by [ and ]. If you are missing the starting [, the error message will show up on the closing ] and say it expected a different symbol.
Most validation errors are around missing name/value for a question. The error will be specific about the question/choice with an issue.
If you aren’t using the advanced feature of [library questions](insert link here), you won’t see this message. If you have a library error, the preview will disappear and the message will be something such as “There is an error in the use of at least one library question. The error is: cannot find library item with library name surveys/pd/workshop_element, version: 0 and question name survey_preamble_header_and_text.”. This means the library question referenced in the form cannot be found--usually this is due to a typo in the reference.
Forms have a concept of published and draft. A published form is ready for use in production or is already in use. A draft is still in progress and not ready for use in production. This is currently a convention and is not enforced on our backend, but is helpful for marking survey status. When editing a published form, take care to only make safe edits. If you need to make an unsafe edit to a published form, consider versioning instead.
The reason to be careful when editing a published form is any old survey responses will now be referenced against the configuration you have made edits to. If you are sure the published form has not been used yet, you can make any changes you want. You can always fix a typo or grammar issue in a published form, as long as it doesn’t change the meaning of the question. It is generally ok to add a question or add an option to a question, as long as you are aware that old form responses will never choose that option or answer that question.
There are some cases when you must version to make a change to a published form. If you want to remove a question or choice, you need to version, as old responses will look invalid after the question/choice is removed. If you want to change the meaning of a question you will also need to version.
When you are ready to save a form, click the save button at the bottom of the screen. If you are working on a draft form you can save anytime you have valid json and a valid survey (save will fail if the survey is invalid). If you are working on a published form, you will see a pop-up reminding you to check that the edits are safe.
If you are working on a new form, you will need to name the form before saving. A form name has two components: a category and a name. The categories we allow are 'surveys/pd' (professional development) and 'surveys/teacher' (teacher-specific surveys). If you need a new category, reach out to engineering. The name component must be all lower case, with words separated by _. After you select the category and name you can save the form. After saving you will see the new form name at the top of the page, which will be the category combined with the form name.