diff --git a/source/calculate_questions.md b/source/calculate_questions.md index d7a9e9283..dcb6f0002 100644 --- a/source/calculate_questions.md +++ b/source/calculate_questions.md @@ -26,7 +26,7 @@ Calculation expressions are constructed using a combination of question referenc To learn more about each of these components, see Introduction to form logic in the Formbuilder.

-To display the result of the calculation in a note, use the [question referencing](https://support.kobotoolbox.org/form_logic.html#question-referencing) format `${data_column_name}`, replacing `data_column_name` with the [data column name](https://support.kobotoolbox.org/question_options.html#data-column-name) of the Calculate question. You can also use this format to reference the result of the calculation in a question label or in your form’s logic. +To display the result of the calculation in a note, use the [question referencing](https://support.kobotoolbox.org/form_logic.html#question-referencing) format `${question_name}`, replacing `question_name` with the [question name](https://support.kobotoolbox.org/question_options.html#question-name) of the Calculate question. You can also use this format to reference the result of the calculation in a question label or in your form’s logic. ![Question reference](images/calculate_questions/reference.png) diff --git a/source/cascading_select.md b/source/cascading_select.md index 08a429cdc..a890037c8 100644 --- a/source/cascading_select.md +++ b/source/cascading_select.md @@ -15,7 +15,7 @@ Cascading select questions allow you to create dynamic forms where the options i To import cascading select questions into the Formbuilder, you first need to prepare your choice list in Excel or another spreadsheet program. You can use this Cascade Import Template to get started. The choice table must include the following columns: -- **list_name:** Unique identifier for a question’s list of choices. This will also be the Data Column Name for the created question. +- **list_name:** Unique identifier for a question’s list of choices. This will also be the [question name](https://support.kobotoolbox.org/glossary.html#question-name) for the created question. - **name:** Unique identifier for each choice within a list. - **label:** Text that appears on the form for each choice. @@ -42,7 +42,7 @@ Once your choice list is ready, you can import it in the Formbuilder by followin ![Insert cascading select example](images/cascading_select/insert_cascading_select.png)

- Note: If you change the question label in the Formbuilder, ensure the Data Column Name in its settings still matches the list_name from your choice list table. + Note: If you change the question label in the Formbuilder, ensure the question name in its settings still matches the list_name from your choice list table.

## Advanced cascading select management using XLSForm @@ -66,7 +66,7 @@ If the choice list for the child question is empty, the child list is not seeing
Cascades break after you edit the form -Renaming a question or editing choice lists can change the backend code the cascade relies on. When renaming a question, ensure the Data Column Name remains the same as the corresponding list_name. For large choice list edits, either rebuild the cascade from scratch or download the XLSForm, make your changes there, and upload it back. +Renaming a question or editing choice lists can change the backend code the cascade relies on. When renaming a question, ensure the question name remains the same as the corresponding list_name. For large choice list edits, either rebuild the cascade from scratch or download the XLSForm, make your changes there, and upload it back.

@@ -77,7 +77,7 @@ To learn more about advanced cascading select using XLSForm, see Adding translations in XLSForm.

-Most elements displayed to respondents can be translated. These include **question labels, hints, choice labels, constraint messages**, and **required messages.** Elements that define the structure of the form, such as [data column names](https://support.kobotoolbox.org/glossary.html#data-column-name) and [XML values](https://support.kobotoolbox.org/glossary.html#xml-value), cannot be translated and should remain in the language you use for form development and data analysis. +Most elements displayed to respondents can be translated. These include **question labels, hints, choice labels, constraint messages**, and **required messages.** Elements that define the structure of the form, such as [question names](https://support.kobotoolbox.org/glossary.html#question-name) and [choice names](https://support.kobotoolbox.org/glossary.html#choice-name), cannot be translated and should remain in the language you use for form development and data analysis.

Note: XLSForm makes it easy to add translations in bulk using machine translation or online translation tools. Machine translations should always be reviewed by a fluent speaker to ensure accuracy, cultural appropriateness, and correct context. This helps maintain the quality and reliability of your translated content. @@ -75,7 +75,7 @@ To view your data table in a different language: 1. In your project, go to **DATA > Table.** 2. In the top right corner, click **Display Options.** -3. Under **Display labels or XML values?**, select the language you want to use. +3. Under **Column headers**, select the language you want to use. ![Display options table view](images/collecting_data_multiple_languages/table_view.png) @@ -117,6 +117,6 @@ To export your data report in a different language: Note: All form data is exported in the selected language, regardless of the language used for data collection, except for open text responses.

-You can also view or export your data using [XML values](https://support.kobotoolbox.org/glossary.html#xml-value). **XML values are not translated** and are usually generated in the language used during form development. +You can also view or export your data using [question and choice names](https://support.kobotoolbox.org/glossary.html#question-name). **Question and choice names are not translated** and are usually generated in the language used during form development. -Using XML values is recommended for analysis, as these provide short, consistent variable names and coded values that **remain consistent across translations**, regardless of the language used by respondents. +Using question and choice names is recommended for analysis, as these provide short, consistent variable names and coded values that **remain consistent across translations**, regardless of the language used by respondents. diff --git a/source/data_analysis.md b/source/data_analysis.md index bf72a0372..01e4813b0 100644 --- a/source/data_analysis.md +++ b/source/data_analysis.md @@ -62,9 +62,9 @@ You can export your data from KoboToolbox in several formats, depending on how y To learn more about exporting KoboToolbox data, see Exporting and downloading your data.

-When exporting data for analysis in external software, it is recommended to export your data as **XML values and headers**, and to **separate multiple choice responses** into separate columns. These settings make exported data easier to process and analyze. +When exporting data for analysis in external software, it is recommended to export your data as **Question & choice names**, and to **separate multiple choice responses** into separate columns. These settings make exported data easier to process and analyze. -If you are sharing raw data with non-technical audiences, **exporting labels** instead of **XML values and headers** may be more user-friendly. Labels can also be exported in multiple languages. +If you are sharing raw data with non-technical audiences, **exporting Question & choice labels** instead of **Question & choice names** may be more user-friendly. Labels can also be exported in multiple languages. Other export settings, such as storing date and number responses as text or including data from all form versions, depend on your analysis needs and preferences. diff --git a/source/data_through_webforms.md b/source/data_through_webforms.md index 0475707af..a9d155d2b 100644 --- a/source/data_through_webforms.md +++ b/source/data_through_webforms.md @@ -161,15 +161,15 @@ For example, you could share different links in different places, and each link To share a link that prefills a field in your form: -1. Add the question you want to prefill to your form, then set its [data column name](https://support.kobotoolbox.org/glossary.html#data-column-name). +1. Add the question you want to prefill to your form, then set its [question name](https://support.kobotoolbox.org/question_options.html#question-name). - This can be a [Hidden](https://support.kobotoolbox.org/form_logic.html#storing-constants-in-your-form) question if you want to store the value in the background, or any standard question type if you want respondents to see it in the form. 2. Copy your form link in **FORM > Collect data.** -3. Add `?d[data_column_name]=value` at the end of the URL, where `data_column_name` is the data column name of the Hidden question and `value` is the prefilled value. +3. Add `?d[question_name]=value` at the end of the URL, where `question_name` is the question name of the Hidden question and `value` is the prefilled value. - For example: `https://ee.kobotoolbox.org/x/[form_id]?d[prefilled_field]=12345`.

Note: -Use the full data column name in the URL parameter. If the question is inside one or more groups, the name must include the group name or names as well (e.g., group1/question1). You can find the exact name in the question’s Data column name field in the Formbuilder, or in the name column of an XLSForm. +Use the full question name in the URL parameter. If the question is inside one or more groups, the name must include the group name or names as well (e.g., group1/question1). You can find the exact name in the question name field in the Formbuilder, or in the name column of an XLSForm.

### Redirecting users to another webpage after submission @@ -245,7 +245,7 @@ Use the latest version of a modern browser. Chrome is generally recommended for
Web form submission fails -If a web form submission fails, check whether your form uses a reserved XLSForm term as the data column name. Reserved words are terms that cannot be used as variable names because they are used by the underlying XForms engine for structure, logic, or data analysis (e.g., type, label, start, today). Using these words can cause form validation errors, publishing failures, or data export issues.

+If a web form submission fails, check whether your form uses a reserved XLSForm term as a question name. Reserved words are terms that cannot be used as variable names because they are used by the underlying XForms engine for structure, logic, or data analysis (e.g., type, label, start, today). Using these words can cause form validation errors, publishing failures, or data export issues.

To fix the issue, rename the affected question to a different value, then redeploy the form. This issue usually affects web forms even when the form opens normally, while KoboCollect may continue to work as expected. Note that any submissions already saved against the old version of the form may remain unsubmittable, so it is important to update the form as soon as possible if you are collecting data through web forms. Always test form submission before launching data collection so you can catch naming issues early.
diff --git a/source/deploy_form_new_project.md b/source/deploy_form_new_project.md index e68eb8340..d2c809d73 100644 --- a/source/deploy_form_new_project.md +++ b/source/deploy_form_new_project.md @@ -66,13 +66,13 @@ If you make changes to a form after data collection has already started, those c Changes that can affect your data structure include: -- **Changing a question’s [data column name](https://support.kobotoolbox.org/glossary.html#data-column-name)**: KoboToolbox will treat it as a new variable and create a new column in the data table. -- **Changing a question type while keeping the same data column name**: This can create inconsistent data in the same column and lead to errors (e.g., in the **DATA > Reports** view). +- **Changing a [question name](https://support.kobotoolbox.org/glossary.html#question-name)**: KoboToolbox will treat it as a new variable and create a new column in the data table. +- **Changing a question type while keeping the same question name**: This can create inconsistent data in the same column and lead to errors (e.g., in the **DATA > Reports** view). - **Moving questions into or out of groups**: KoboToolbox will treat these questions as new variables and create new columns in the data table. - **Removing choices from a choice list**: Previous submissions may still contain those choice values, but they may no longer have an associated label in the form. -- **Adding new choices to a Select one or Select many question**: Make sure each new choice has a unique [XML value](https://support.kobotoolbox.org/glossary.html#xml-value) within a given choice list. +- **Adding new choices to a Select one or Select many question**: Make sure each new choice has a unique [choice name](https://support.kobotoolbox.org/glossary.html#choice-name) within a given choice list. - **Deleting a question that is used elsewhere in the form**: If the question is referenced in a calculation, relevance condition, constraint, or another expression, you will also need to update those references. -- **Changing question or choice labels**: Does not affect the data structure if the data column name or XML value stays the same, but previously collected data will use the updated label. +- **Changing question or choice labels**: Does not affect the data structure if the question or choice name stays the same, but previously collected data will use the updated label. - **Changing the meaning of existing choice values**: Changing choice names or labels can make data inconsistent across form versions and lead to misinterpretation. For example, this can happen if you reverse the meaning of values such as `1 = Yes` and `0 = No`, or change the direction of a Likert scale.

@@ -90,9 +90,9 @@ Changes to a form can also affect how older submissions behave when you edit the

Error when deploying: Choice names must be unique for each choice list -This error means that two or more choices in the same choice list have the same XML value (or choice name). +This error means that two or more choices in the same choice list have the same choice name.

-If you are using the Formbuilder, check the XML values that you have set manually for each option choice to ensure that each XML value is unique within a given choice list. +If you are using the Formbuilder, check the choice names that you have set manually for each option choice to ensure that each choice name is unique within a given choice list.

If you cannot identify which choice is causing the problem, download the form as an XLSForm and check the choices sheet to find the duplicate value more easily. The error message will usually provide the row number in the choices sheet that is causing the error.
diff --git a/source/dynamic_data_attachment_formbuilder.md b/source/dynamic_data_attachment_formbuilder.md index 7eddeaee4..70ed262fb 100644 --- a/source/dynamic_data_attachment_formbuilder.md +++ b/source/dynamic_data_attachment_formbuilder.md @@ -46,12 +46,12 @@ In the **question label** field of the Calculate question where linked data will For each expression in the table below: - `parent` is the unique name assigned to the **parent form** (in the External XML question of the **child form**). -- `parent_question` refers to the data column name of a question from the **parent form.** -- `child_question` refers to the data column name of a question from the **child form.** +- `parent_question` refers to the question name of a question from the **parent form.** +- `child_question` refers to the question name of a question from the **child form.** - `parent_index_question` is the identifying question from the **parent form** that links it to the **child form** (e.g., unique ID, organization name). - `child_index_question` is the identifying question from the **child form** that links it to the **parent form** (e.g., unique ID, organization name). -- `parent_group` refers to the data column name of the group in the **parent form** in which the `parent_question` is located. -- `parent_index_group` refers to the data column name of the group in the **parent form** in which the `parent_index_question` is located. +- `parent_group` refers to the question name of the group in the **parent form** in which the `parent_question` is located. +- `parent_index_group` refers to the question name of the group in the **parent form** in which the `parent_index_question` is located. | **XPath** | **Description** | | :----------------- | :--------------------------------------------- | diff --git a/source/editing_deleting_data.md b/source/editing_deleting_data.md index b2bc61d7e..f16bdedc1 100644 --- a/source/editing_deleting_data.md +++ b/source/editing_deleting_data.md @@ -57,7 +57,7 @@ To edit raw data in KoboToolbox: 1. Select the submission using the checkbox. 2. Click **Edit** above the data table. 3. In the edit window, click **Edit** next to the field you want to change and enter the new value. - - For select type questions, enter one or more valid [XML values](https://support.kobotoolbox.org/glossary.html#xml-value), separated by spaces. + - For select type questions, enter one or more valid [choice names](https://support.kobotoolbox.org/glossary.html#choice-name), separated by spaces. 4. Click **Save**, then **Confirm & close.** diff --git a/source/export_download.md b/source/export_download.md index 848366bca..d2c71e5c9 100644 --- a/source/export_download.md +++ b/source/export_download.md @@ -46,8 +46,8 @@ When using the standard export formats (XLS, CSV, GeoJSON, and SPSS Labels), you | **Format** | **Description** | | :----------------- | :--------------------------------------------- | -| Labels (default) | The exported file uses question labels (question text) as column headers and choice labels for responses to Select One and Select Many questions. | -| XML values and headers | The exported file uses question names (Data Column Names) as column headers and choice names (XML values) for responses. This export setting is recommended for importing your data into data analysis software. | +| Question & choice labels (default) | The exported file uses the full question labels (i.e., the question text) as column headers and full choice labels for responses to Select One and Select Many questions. | +| Question & choice names | The exported file uses question names as column headers and choice names for responses. These are the internal short names used to refer to questions and choices in your data. This export setting is recommended for importing data into data analysis software. | | Labels in any of the defined languages | The exported file uses question and choice labels in any of the languages set within the form. | ## Advanced options diff --git a/source/external_file.md b/source/external_file.md index 49311cbfd..522c287d8 100644 --- a/source/external_file.md +++ b/source/external_file.md @@ -18,7 +18,7 @@ To learn more about formatting XML or GeoJSON files, see - For more information, see Setting XML values for option choices. + For more information, see Setting choice names for option choices.

-**Related term(s):** [XML value](https://support.kobotoolbox.org/glossary.html#xml-value), [Data column name](https://support.kobotoolbox.org/glossary.html#data-column-name), [Label](https://support.kobotoolbox.org/glossary.html#label) +**Related term(s):** [Question name](https://support.kobotoolbox.org/glossary.html#question-name), [Label](https://support.kobotoolbox.org/glossary.html#label) --- -## Data column name - -Internal short names assigned to questions that are used to store and reference data in a form. These are also called **question names** in XLSForm, and sometimes referred to as **XML values** or **headers** in the user interface. Exporting your data using XML values and headers can facilitate data management and analysis. - -

- For more information, see Question options in the Formbuilder. -

- -**Related term(s):** [Question name](https://support.kobotoolbox.org/glossary.html#question-name), [XML value](https://support.kobotoolbox.org/glossary.html#xml-value), [Label](https://support.kobotoolbox.org/glossary.html#label) - ---- ## Data reports Automated reports in the **DATA > Reports** view that display your project data in graphs and tables. Reports can be customized to adjust which questions are shown and how the results are visualized. @@ -544,13 +533,13 @@ A set of related questions grouped together in a form to improve structure and o ## Question name -Internal short name assigned to questions that is used to store and reference data in a form. These are also called **data column names** in the Formbuilder, and sometimes referred to as **XML values or headers** in the user interface. +Internal short name assigned to questions that is used to store and reference data in a form. These were previously called **data column names** in the Formbuilder, and were sometimes referred to as **XML values or headers** in the user interface.

- For more information, see Question options in the Formbuilder. + For more information, see Question options in the Formbuilder.

-**Related term(s):** [Data column name](https://support.kobotoolbox.org/glossary.html#data-column-name), [XML value](https://support.kobotoolbox.org/glossary.html#xml-value), [Label](https://support.kobotoolbox.org/glossary.html#label) +**Related term(s):** [Choice name](https://support.kobotoolbox.org/glossary.html#choice-name), [Label](https://support.kobotoolbox.org/glossary.html#label) --- @@ -729,15 +718,3 @@ A form design standard that uses Excel spreadsheets to define questions, choices The XML version of a form generated when a project is deployed, used by data collection tools to run the form and apply its structure, logic, and settings. An XML Form is also called an **XForm**. **Related term(s):** [XLSForm](https://support.kobotoolbox.org/glossary.html#xlsform) - ---- - -## XML value - -Internal short names assigned to choices that are used to store and reference data in a form. These are also called **choice names** in XLSForm. In the user interface, XML value is sometimes used to refer to **data column names**. Exporting your data using XML values can facilitate data management and analysis. - -

- For more information, see Setting XML values for option choices. -

- -**Related term(s):** [Choice name](https://support.kobotoolbox.org/glossary.html#choice-name), [Data column name](https://support.kobotoolbox.org/glossary.html#data-column-name), [Label](https://support.kobotoolbox.org/glossary.html#label) diff --git a/source/images/editing_deleting_data/table.png b/source/images/editing_deleting_data/table.png index 76fcbff84..1b60336ab 100644 Binary files a/source/images/editing_deleting_data/table.png and b/source/images/editing_deleting_data/table.png differ diff --git a/source/library_locking.md b/source/library_locking.md index 5f43c63d7..6e8b37375 100644 --- a/source/library_locking.md +++ b/source/library_locking.md @@ -48,7 +48,7 @@ Question-level restrictions apply to individual questions. You can apply the fol |:------------------------------|:---------------------------------------------------------------------------------------------------------------| | choice_add | Prevents adding new choices to a **select** question. | | choice_delete | Prevents deleting existing choices in a **select** question. | -| choice_value_edit | Prevents editing a choice name (or XML value). | +| choice_value_edit | Prevents editing a choice name. | | choice_label_edit | Prevents editing a choice label. | | choice_order_edit | Prevents reordering choices in a **select** question. | | question_delete | Prevents deleting a question. | diff --git a/source/managing_permissions.md b/source/managing_permissions.md index 86344ab70..169d20c6f 100644 --- a/source/managing_permissions.md +++ b/source/managing_permissions.md @@ -80,7 +80,7 @@ Response values must follow a specific format for the condition to work: | **Question type** | **Format** | | :----------------- | :--------------------------------------------- | | Date | YYYY-MM-DD (e.g., 1974-12-31) | -| Select One and Select Many | XML value/choice name (e.g., first_grade rather than First grade) | +| Select One and Select Many | Choice name (e.g., first_grade rather than First grade) | | Number and Decimal | A specific integer or decimal number | ## Copying permissions from another project diff --git a/source/matrix_response.md b/source/matrix_response.md index 54a4581c2..4eff2c9f0 100644 --- a/source/matrix_response.md +++ b/source/matrix_response.md @@ -36,8 +36,8 @@ To configure your question matrix, for each column: - Available types include **Select One**, **Select Many**, **Text**, and **Number.** - You can use different question types within the same matrix. 3. Enter a **Question Label.** -4. Enter a **Data Column Suffix.** This suffix will be appended to the variable names for each item in the rows and must follow the [standard rules for data column names](https://support.kobotoolbox.org/question_options.html#important-considerations-for-data-column-names). -5. If using **Select One** or **Select Many**, add the answer choices and their [XML values](https://support.kobotoolbox.org/question_types.html#setting-xml-values-for-option-choices). +4. Enter a **Question Name Suffix.** This suffix will be appended to the variable names for each item in the rows and must follow the [standard rules for question names](https://support.kobotoolbox.org/question_options.html#important-considerations-for-question-names). +5. If using **Select One** or **Select Many**, add the answer choices and their [choice names](https://support.kobotoolbox.org/question_types.html#setting-choice-names-for-option-choices). 6. Set the question as [required](https://support.kobotoolbox.org/question_options.html#mandatory-response), if needed. 7. To add another column, click the icon to the right of the last column. @@ -49,7 +49,7 @@ To configure each row: 1. Click the **Settings** icon. 2. Enter a **Label** for the item. -3. Enter a **Data Column Prefix.** This prefix will be added to the variable names for all column questions related to this item and must follow the [standard rules for data column names](https://support.kobotoolbox.org/question_options.html#important-considerations-for-data-column-names). +3. Enter a **Question Name Prefix.** This prefix will be added to the variable names for all column questions related to this item and must follow the [standard rules for question names](https://support.kobotoolbox.org/question_options.html#important-considerations-for-question-names). 4. To add another row, click the icon below the last row. ## Collecting data from a question matrix diff --git a/source/option_choices_xls.md b/source/option_choices_xls.md index 404580ccb..372285a74 100644 --- a/source/option_choices_xls.md +++ b/source/option_choices_xls.md @@ -47,7 +47,7 @@ To define a list of option choices in XLSForm: ## Best practices for defining choice names -When data is downloaded in [XML values and headers format](https://support.kobotoolbox.org/export_download.html#value-and-header-format), each question appears as its own variable or column in the dataset. The values inside each column are the **choice names** defined in your `choices` worksheet, rather than the full labels shown to respondents. This format is recommended for analysis, since it provides short, consistent variable names and coded values that are easier to work with than full question or option labels. +When data is downloaded in [Question & choice names format](https://support.kobotoolbox.org/export_download.html#value-and-header-format), each question appears as its own variable or column in the dataset. The values inside each column are the **choice names** defined in your `choices` worksheet, rather than the full labels shown to respondents. This format is recommended for analysis, since it provides short, consistent variable names and coded values that are easier to work with than full question or option labels. When defining choice names: - Use only **letters, numbers, and underscores**. Spaces and special characters are not allowed. diff --git a/source/preparing_for_analysis.md b/source/preparing_for_analysis.md index 17973c437..ebe8572d0 100644 --- a/source/preparing_for_analysis.md +++ b/source/preparing_for_analysis.md @@ -33,7 +33,7 @@ Asking the right questions to the right people improves data quality and reduces ## Anticipating the format of your data exports -The way you define [question names](https://support.kobotoolbox.org/glossary.html#data-column-name) and [choice names](https://support.kobotoolbox.org/glossary.html#xml-value) affects how easy your data is to work with after export. **Question names** become column names in your exported dataset, while **choice names** represent response values for select questions. +The way you define [question names](https://support.kobotoolbox.org/glossary.html#question-name) and [choice names](https://support.kobotoolbox.org/glossary.html#choice-name) affects how easy your data is to work with after export. **Question names** become column names in your exported dataset, while **choice names** represent response values for select questions. For best results, follow the recommendations below. diff --git a/source/question_options.md b/source/question_options.md index 5c7f2a1c8..ee8a01e58 100644 --- a/source/question_options.md +++ b/source/question_options.md @@ -21,7 +21,7 @@ The following options are available for questions added in the Formbuilder: | Options | Description | |:---|:---| | Question Hint | Text displayed below the question label to provide additional instructions or clarification for respondents. | -| Data Column Name | The unique identifier for a question, used in form logic and as the column header in the exported dataset. | +| Question Name | The unique identifier for a question, used in form logic and as the column header in the exported dataset. | | Guidance Hint | Additional notes or instructions intended for enumerators or form developers, not displayed by default during data collection. | | Mandatory Response | A setting that determines whether a question must be answered before the respondent can continue or submit the form. | | Default Response | A predefined answer that automatically populates a question and can be changed during data collection. | @@ -35,30 +35,34 @@ The following options are available for questions added in the Formbuilder: Note: For additional customization and advanced options, download your form as an XLSForm and add question options directly in the spreadsheet.

-## Data Column Name +## Question Name -The **Data Column Name** is the unique identifier for each question in your form. It serves as the variable name used in [form logic](https://support.kobotoolbox.org/form_logic.html#question-referencing) and becomes the column header in your exported dataset. +The **Question Name** is the unique identifier for each question in your form. It serves as the variable name used in [form logic](https://support.kobotoolbox.org/form_logic.html#question-referencing) and becomes the column header in your exported dataset. -Every question must have a unique data column name. In the Formbuilder, it is automatically generated from the question label, but you can customize it as needed. Defining clear and consistent names before deploying your form helps ensure that your dataset follows a logical naming convention. +Every question must have a unique question name. In the Formbuilder, it is automatically generated from the question label, but you can customize it as needed. Defining clear and consistent names before deploying your form helps ensure that your dataset follows a logical naming convention. -![Data column name](images/question_options/data_column_name.png) +![Question name](images/question_options/question_name.png) -### Important considerations for data column names +

+Note: The Question Name was previously referred to as Data Column Name in the Formbuilder. +

+ +### Important considerations for question names -If you keep the **automatically generated data column name**, it will update automatically whenever you change the question label. This can cause problems if you have already set up form logic in XLSForm code using the previous data column name, or if you have started collecting data. +If you keep the **automatically generated question name**, it will update automatically whenever you change the question label. This can cause problems if you have already set up form logic in XLSForm code using the previous question name, or if you have started collecting data. -If a question’s data column name changes after data collection has begun, KoboToolbox will treat it as a new variable. This will result in two separate columns in your dataset. +If a question name changes after data collection has begun, KoboToolbox will treat it as a new variable. This will result in two separate columns in your dataset. -For this reason, it is recommended to **define and finalize the data column name for each question before deploying your form** and collecting data. If you intentionally make substantial changes to a question and want it to function as a new variable, you can update the data column name accordingly. +For this reason, it is recommended to **define and finalize the question name for each question before deploying your form** and collecting data. If you intentionally make substantial changes to a question and want it to function as a new variable, you can update the question name accordingly. -Data column names must follow these rules: +Question names must follow these rules: - Use only letters, numbers, and underscores. - The first character must be a letter. - Each name must be unique within the form.

-Note: Data column names are used when referencing answers in form logic. For example, you can include a previous response in another question’s label using the format ${data_column_name}. This format is used in labels, skip logic, calculations, and validations. Data column names are case-sensitive. +Note: Question names are used when referencing answers in form logic. For example, you can include a previous response in another question’s label using the format ${question_name}. This format is used in labels, skip logic, calculations, and validations. Question names are case-sensitive.

## Question Hint @@ -131,8 +135,8 @@ The format of the default response depends on the question type and the data bei |:---|:---| | Number | Number | | Text | Text (without quotation marks) | -| Select One | Choice XML value | -| Select Many | Choice XML values, separated by a space if there are multiple | +| Select One | Choice name | +| Select Many | Choice names, separated by a space if there are multiple | | Date | Date in the YYYY-MM-DD format. | ## Appearance (Advanced) @@ -149,7 +153,7 @@ HXL, or **Humanitarian Exchange Language**, is a [standardized system](https://h Applying HXL tags to your questions helps make your data more interoperable across systems and organizations. It also supports more efficient data processing and analysis. -In KoboToolbox, you can assign one HXL tag per question and optionally include attributes. When you export your data as an XLS file with XML values and headers selected, an additional row containing the HXL tags will appear directly below the variable names in your dataset. +In KoboToolbox, you can assign one HXL tag per question and optionally include attributes. When you export your data as an XLS file using **Question & choice names**, an additional row containing the HXL tags will appear directly below the variable names in your dataset. Using HXL tags is especially helpful when your data will be shared with partners or integrated into other humanitarian data systems. diff --git a/source/question_types.md b/source/question_types.md index 813a915f6..b31607393 100644 --- a/source/question_types.md +++ b/source/question_types.md @@ -20,14 +20,14 @@ To add a question to your form: Note: Once the question type has been selected, it cannot be changed in the Formbuilder. To change the question type of an existing question, delete the question and create a new question with the same label.

-### Setting data column names +### Setting question names -After adding a question to your form, it is strongly recommended to define a **Data Column Name** in the question **Settings.** The data column name is used to identify the question throughout the form logic and in the exported dataset. +After adding a question to your form, it is strongly recommended to define a **Question Name** in the question **Settings**. The question name is used to identify the question throughout the form logic and in the exported dataset. -By default, KoboToolbox creates the data column name for you by removing spaces and capital letters from the question label. For example, if the question label is “Respondent name”, the data column name will be `respondent_name`. +By default, KoboToolbox creates the question name for you by removing spaces and capital letters from the question label. For example, if the question label is “Respondent name”, the question name will be `respondent_name`.

- To learn more about data column names, see Question options in the Formbuilder. + To learn more about question names, see Question options in the Formbuilder.

## Adding option choices @@ -44,16 +44,16 @@ When adding Select One or Select Many questions to your form, you will be prompt Note: Managing long choice lists in the Formbuilder can be time-consuming. If your form includes many options or the same choice list used in multiple questions, it is often easier to create and manage these lists using XLSForm instead. To learn more, see Managing option choices in XLSForm.

-### Setting XML values for option choices +### Setting choice names for option choices -Next to each choice option, you will see a field labeled **AUTOMATIC.** This field contains the [XML value](https://support.kobotoolbox.org/glossary.html#xml-value) for that option. +Next to each choice option, you will see a field labeled **AUTOMATIC.** This field contains the [choice name](https://support.kobotoolbox.org/glossary.html#choice-name) for that option. -The XML value is a short, internal name that KoboToolbox uses to save and identify the selected option in your data. By default, KoboToolbox creates the XML value for you by removing spaces and capital letters from the option label. For example, if the option label is “Option 1”, the XML value will be `option_1`. +The choice name is a short, internal name that KoboToolbox uses to save and identify the selected option in your data. By default, KoboToolbox creates the choice name for you by removing spaces and capital letters from the option label. For example, if the option label is “Option 1”, the choice name will be `option_1`. -In some cases, you may want to set your own XML value. This can be helpful if the option label is very long or if you want to use a clearer or more consistent name. To do this, click **AUTOMATIC** and replace it with your own custom value. +In some cases, you may want to set your own choice name. This can be helpful if the option label is very long or if you want to use a clearer or more consistent name. To do this, click **AUTOMATIC** and replace it with your own custom value.

-Note: It is strongly recommended to define XML values for all choices when using non-Latin scripts, such as Chinese, Arabic, or Nepali, to ensure your data is stored and exported correctly. +Note: It is strongly recommended to define choice names for all choices when using non-Latin scripts, such as Chinese, Arabic, or Nepali, to ensure your data is stored and exported correctly.

## Question types in the Formbuilder diff --git a/source/select_one_and_select_many.md b/source/select_one_and_select_many.md index a95bc4adf..cf64e5c9b 100644 --- a/source/select_one_and_select_many.md +++ b/source/select_one_and_select_many.md @@ -119,11 +119,11 @@ The **Acknowledge** question type allows respondents to indicate agreement with If you need more flexibility in labeling response options, or if you want to include a clear “No” option, use a **Select One** question instead. -### Defining XML values for choices +### Defining choice names -It is strongly recommended to define XML values for all choices in select questions before deploying your form. XML values ensure consistency in your dataset and prevent issues during export and analysis. +It is strongly recommended to define choice names for all choices in select questions before deploying your form. Choice names ensure consistency in your dataset and prevent issues during export and analysis. -

To learn more about defining XML values, see Adding questions in the Formbuilder. +

To learn more about defining choice names, see Adding questions in the Formbuilder.

### Adding an “Other, specify” response diff --git a/source/skip_logic.md b/source/skip_logic.md index e3c767d68..e54f2eba5 100644 --- a/source/skip_logic.md +++ b/source/skip_logic.md @@ -38,7 +38,7 @@ To manually enter skip logic in XLSForm code, follow these steps: 2. Select **Skip Logic**, and click **Manually enter your skip logic in XLSForm code**. 3. Enter the condition in XLSForm code. -In XLSForm code, questions are referred to by their **question name** (Data Column Name) using the format `${question_name}`. For example, if Q2 should be asked only if the answer to Q1 is "Yes", the skip logic condition for Q2 would be `${Q1} = ‘yes’`. +In XLSForm code, questions are referred to by their [question name](https://support.kobotoolbox.org/question_options.html#question-name) using the format `${question_name}`. For example, if Q2 should be asked only if the answer to Q1 is "Yes", the skip logic condition for Q2 would be `${Q1} = ‘yes’`.

For more information on XLSForm code and operators, see Introduction to form logic in the Formbuilder. diff --git a/source/viewing_validating_data.md b/source/viewing_validating_data.md index 3d25ab2d8..e16db32dc 100644 --- a/source/viewing_validating_data.md +++ b/source/viewing_validating_data.md @@ -37,8 +37,8 @@ Above the data table, you can configure the following settings: | Display option | Description | |:-------------------------------|:---------------------------------------------------------------------------------------------| -| Display labels or XML values? | Choose whether to show XML values or full question and choice labels in any form language in your table. | -| Show group names in table headers | Decide whether column headers in the table include the name of the question group (e.g., `demographics / age`). | +| Column headers | Choose whether to show question and choice names or full question and choice labels in any form language in your table. | +| Show parent group in column headers | Decide whether column headers in the table include the name of the question group (e.g., `demographics / age`). | | Show HXL tags | Display Humanitarian Exchange Language (HXL) tags if they were added to your form. | Within the data table, you can click a column header and select **Hide field** to remove fields you do not need, or **Freeze field** to keep a frequently used field visible while you scroll. @@ -103,7 +103,7 @@ To open a submission, click **View** in the correspo The submission window displays all responses and includes the following options: - View data in [any form language](https://support.kobotoolbox.org/collecting_data_multiple_languages.html). -- Display [XML values](https://support.kobotoolbox.org/glossary.html#xml-value) next to each question. +- Display [question names](https://support.kobotoolbox.org/glossary.html#question-name) next to each question. - **View** and **Edit** the submission as a [web form](https://support.kobotoolbox.org/editing_deleting_data.html). - **Duplicate** the submission. - **Print** the submission.