Import annotation question templates

This feature is available only when your deployment enables annotation question import. You need permission to design the project's questions.

1. Open the project's Question Management → Design page.
2. Choose Import question template.
3. Upload an existing pilot workbook, or use Download blank template for the standard UTF-8 CSV. Standard XLSX tables use the same columns on a sheet named Questions, with their header in row 1.
4. Choose Validate and preview. Fix the indicated rows and upload again if validation fails. No questions are created during preview.
5. Check the question tree, parent conditions, options and answer modes. Expand Help text to check details moved out of a shortened question.
6. Select the review confirmation and choose Add questions. The entire batch is saved together or not saved at all.
7. Use the existing Assign tab to assign the new questions to stages.

Existing questions and study answers are not replaced. Importing the same file as a deliberately new operation creates another batch; retries of the same operation do not. Do not start a fresh import while a prior save is uncertain. Retry from the open dialog. After a page reload, reopen import in the same project: it finds the receipt or asks you to select the identical file. Only the operation identity and hashes are retained in browser session storage.

Limits

Use a nonempty .xlsx or UTF-8 .csv up to 5 MiB, with up to 500 custom questions, 100 options per question and 20 custom hierarchy levels. Displayed question text is limited to 80 characters. Put longer explanation into description (standard) or help_text (pilot). Author rows must be contiguous.

Macros, external workbook links and formulas in imported author fields are not supported. Pilot auto-guidance and original-text columns are ignored; their contents never become question wording. The importer does not modify your file.

Standard blank template

Each row has format_version=1. Required columns are format_version, row_id, order, question, category, question_type, control_type, optional, multiple, and answer_array. Boolean cells use true or false. order is a nonnegative integer, unique amongst siblings. IDs start with a letter and use letters, digits, underscores or hyphens, up to 64 characters.

Categories are Study, Disease Model Induction, Treatment, Outcome Assessment, Cohort and Experiment. Controls are textbox, dropdown, autocomplete, radio, checklist and checkbox. Textbox accepts string, integer or decimal data with no predefined options. Choice controls require options. Autocomplete is string-only; radio is single-answer; checklist uses a grouped array; checkbox is required boolean with no options or multiplicity.

options_json is an array such as [{"Value":"Yes"},{"Value":"No"}]. condition_json is either {"equalsBoolean":true} for a checkbox parent or {"anyOf":["Yes","Probably yes"]} for an option parent. Conditions use the parent's exact option values, not abbreviations or new labels. JSON cells in CSV need CSV quoting, normally handled by your spreadsheet application.

Optional author columns include description, parent_ref, condition_json, options_json, answer_label, and default_checkbox_status. Leave metadata_fields_json and response_modes_json empty: those future extensions are not silently dropped. Distinct option display labels are also not currently supported; use readable option values themselves.

Parent references and repeatable answers

@row:Factor attaches to the imported row whose ID is Factor. @question:<existing-question-UUID> attaches to a custom question already in this project. A blank Study parent is a root. A blank non-Study parent attaches to its category's existing system anchor, unconditionally.

Do not copy built-in system questions into the table. Reference the existing anchor instead:

Category	System parent reference
Disease Model Induction	@system:disease_model_induction_control
Treatment	@system:treatment_control
Outcome Assessment	@system:outcome_assessment_label
Cohort	@system:cohort_label
Experiment	@system:experiment_label

For a control-procedure Yes branch, use the matching system parent and {"equalsBoolean":true}. For No use false. Label anchors have no answer condition. Other system questions are not legal custom-question parents.

For a factor with its own follow-up questions, use multiple=true and answer_array=false: reviewers create separate factor instances with their respective children. multiple=true, answer_array=true groups answers in one array. answer_label can name an individual instance, for example confounding factor. The preview makes this distinction explicit.

Existing pilot workbooks

The pilot Questions sheet uses parent_row_id, data_type, help_text, show_when_parent_answer, pipe-separated options/option_labels, Yes/No booleans and optional answer_mode. Dotted hierarchical row IDs are allowed. answer_mode=Separate instances preserves separate repeatable annotations; blank or One list preserves grouped-array behaviour when multiple is Yes.

Instructions, Valid values, Source map, System parent guidance, Audit trail, Hierarchy overview, Examples and Reference sheets are recognised supporting sheets. Only Questions author fields are imported. The original-text audit column and review diagrams remain for human verification.

Recovery and audit

If the project changed after validation, validate again before applying. If a save has an unknown outcome, Retry same import returns the existing receipt or applies once with the same identity. Recent attempts are listed in the dialog. Successful receipts are immutable; source-free attempt records expire after 30 days. Neither record stores the uploaded file or original question cells.