- Note: With this approach, all media files from each selected submission will be deleted; it is not currently possible to choose only files for a given question. -
- - - diff --git a/source/editing_deleting_data.md b/source/editing_deleting_data.md new file mode 100644 index 000000000..d7b21effd --- /dev/null +++ b/source/editing_deleting_data.md @@ -0,0 +1,180 @@ +# Editing and deleting your data + +Editing and deleting data helps **maintain data quality** after submissions are collected. You may need to correct individual responses, update multiple records at once, duplicate a submission, or remove records that are no longer needed. KoboToolbox offers several ways to manage these tasks, including **editing submissions in Enketo, editing raw data directly, and applying bulk updates.** This article explains each method and when to use it. + ++Note: Submissions collected with the KoboCollect app cannot be edited or deleted in KoboCollect after they are submitted. All post-submission changes must be made in KoboToolbox. +
+ +Project owners can control data access by assigning separate permissions to view, edit, validate, and delete submissions. For example, they can allow some team members to edit data while restricting deletion permissions. + ++To learn more about user-level permissions for editing and deleting data, see Sharing projects with user-level permissions. +
+ +## Editing individual submissions + +KoboToolbox offers two editing approaches, each designed for different use cases. Understanding how they differ helps you choose the safest and most appropriate method for updating data. + +The two methods for editing submissions in KoboToolbox are: + +- **Editing submissions in Enketo:** Opens the submission in Enketo so you can correct responses and resubmit the form. This method is recommended when form logic needs to be applied. +- **Editing raw data directly in KoboToolbox:** Opens a data editor that lets you modify specific responses directly. This method is recommended when you need precise control over edits and do not need form logic to apply. + +Each method comes with its advantages and limitations: + +| Editing method | Advantages | Limitations | +|:---------------|:-----------|:------------| +| Editing in Enketo |
+Note: When editing data using either method, the _uuid metadata field is updated each time a change is saved. When editing in Enketo, the end field is also updated. All other metadata fields remain unchanged, including _id, start, today, _submission_time, and _submitted_by.
+
+Note: Because this method reopens and resubmits the form, it can unintentionally change other fields, particularly those affected by skip logic or calculations. It also uses the most up-to-date version of the form. As a result, you may need to provide responses for newly added questions, and any responses to questions that have been removed from the form will be deleted. +
+ +### Editing raw data in KoboToolbox + +This method lets you bypass form logic and edit stored responses directly without reopening the form. It is useful when changes cannot be made in Enketo, for example, if form logic prevents resubmission or newly required questions need responses. + +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. +4. Click **Save**, then **Confirm & close.** + + + + ++Note: It is recommended to track data edits in an external log or a dedicated comments field. Edits cannot be undone, but they can be modified again later. +
+ +## Editing multiple submissions in bulk + +When working with large datasets, you may need to update multiple records at the same time. Bulk editing helps correct systematic errors, fill in missing information, and standardize responses across many submissions. This approach reduces repetitive work and speeds up the data cleaning process. + +You can edit multiple submissions in bulk using the raw data editing method in KoboToolbox: + +1. Select the submissions you want to edit using the checkboxes. +2. Click **Edit** above the table. A window opens showing responses for all selected submissions. +3. Click **Edit** next to the field you want to update. +4. Enter a new value, or click **Select** to apply an existing value across all selected submissions. +5. Click **Save**, then **Confirm & close.** + + + ++Note: You can select all submissions on the current page by clicking the checkbox in the table header. To select all submissions in the project across all pages, click the arrow next to the checkbox and choose Select all results. +
+ +## Duplicating submissions + +You can duplicate a submission using the following steps: + +1. In the submission row, next to the checkbox, click **View.** +2. In the top right corner, click **Duplicate.** +3. The duplicated submission opens in a new window, where you can **Edit** or **Discard** it as needed. + + + +
+Note: When duplicating a submission, the response data is copied, but the validation status is reset. Metadata fields are updated to reflect the new submission, including start, end, today, _id, _uuid, _submission_time, and _submitted_by.
+
+Note: You can use project history logs to track edits and deletions by project users. +
+ +### Deleting the response for a specific field + +In some cases, you may want to remove responses for a single field without deleting the entire submission. This can be useful for data anonymization, for example, when removing personally identifiable information after it has been stored securely. + +There is no dedicated option to delete a single field value. Instead, you can clear or replace the value using the following approach: + +1. Select the submission(s) you want to update. +2. Click **Edit** above the data table. +3. Click **Edit** next to the field you want to clear, then enter a space or a replacement value such as “deleted” or “N/A”. +4. Click **Save**, then **Confirm & close.** + +## Troubleshooting + +latitude longitude altitude accuracy. For example, the coordinates for Paris would be 48.8566 2.3522 0 0. + To learn more about export types, see Exporting GPS data and Downloading media files. +
+ ## Value and header format When using the standard export formats (XLS, CSV, GeoJSON, and SPSS Labels), you can select the format of your data values and headers: diff --git a/source/howto_edit_multiple_submissions.md b/source/howto_edit_multiple_submissions.md deleted file mode 100644 index a7db02e08..000000000 --- a/source/howto_edit_multiple_submissions.md +++ /dev/null @@ -1,161 +0,0 @@ -# Editing Responses in Multiple Submissions -**Last updated:** 22 Sep 2022 - - -Users could always edit submissions as outlined in our support article -[Editing or Deleting a Single Submission](howto_edit_single_submissions.md). -What if a user has to edit repeated typo errors or update missing responses for -all or most of the submissions from a particular survey project? Following the -method outlined earlier should consume much time. Hence, KoboToolbox has -developed a feature that should make editing straightforward, saving editing -time. - -## Limitations when editing responses for multiple submissions - -There are several limitations when performing the bulk-edit actions described in -this article. The same is not the case when editing -[individual submissions](howto_edit_single_submissions.md). When using this -method: - -- Validation logic and calculations within your form are not re-evaluated. -- Editing questions within repeating groups is not currently supported. -- Coordinate points must follow pattern: `latitude longitude altitude accuracy`. - Failure to do so will not cause an error, but may confuse your data analysis. -- Multiple select responses must consist of the correct **choice names**, - separated by a space. Failure to do so will not cause an error, but will - result in labels not being correctly applied when exported. - -## Editing responses for multiple submissions - -The following is a screen generally seen for **DATA>Table**. - - - -The image shared above shows data input variance with the question **Country** -ranging from _America_, _U.S.A_, _US_, _United States of America_, _United -States_, _usa_ to _USA_. This section of the support article will outline _how -to change all these varying **Country** names to **USA**_. - -**Step 1:** - -To start editing responses for multiple submissions, users should either select -a single record (marked **1**) or select multiple records (marked **2**). -Selecting as shown in the image below should activate the edit features along -with other features. - - - -- **1.** Users could select multiple records that require bulk editing. -- **2.** Alternative to approach outlined above (in **1**), users could select - _all records_ or _all visible records_ under **DATA>Table**. _All records_ - refer to the entire records that are present within the survey project while - _all visible records_ refer to 30 records that are by default visible under - **DATA>Table**. Users should clearly distinguish between the two when there - are more than 30 records (submissions) within the survey project. -- **3.** Shows the total number of records selected for _changing/updating the - validation status_, _bulk editing_ or _bulk deletion_. -- **4.** Users could bulk change the validation status as outlined in our - support article [Record Validation](record_validation.md). -- **5.** Users could bulk edit the responses for multiple submissions. -- **6.** Users could bulk delete the records. - -**Step 2:** - -Users will now have to press **Edit** (**5** as shown in the image above) for -bulk editing after selecting all the records that require modifications. The -following dialogue box should then appear. - - - -Users could filter the required question by typing it in the search filter -located just below the **Question** header. - - - -Users should see _Multiple responses_ under the **Response** header (shown in -the above image) if different values entered. Here we have a range of inputs -from _America_, _U.S.A_, _US_, _United States of America_, _United States_, -_usa_ to _USA_. However, if users select a single record and press **Edit**, -they would see the following dialogue box. - - - -Users could now filter the required response by typing it in the search filter -located just below the **Response** header. This approach is useful when a user -wishes to edit a single record. - - - -**Step 3:** - -Users could press the **EDIT** button once it is known _what to edit and where -to edit_. - - - -**Step 4:** - -So now, there are two approaches to make bulk edits. _Approach 1_ is when users -type in the required text (**USA** in our case) in the blank box (marked -**1.1**) and then press **SAVE** (marked **2**). _Approach 2_ is when users -press **SELECT** (marked **1.2**) for an appropriate text and then press -**SAVE** (marked **2**). - - - -**Step 5:** - -A dialogue box now appears. Users will now have to press **CONFIRM & CLOSE** to -save the changes made. - - - -Users could always go back to **DATA>Table** and check if the bulk edits were -successful. - - - -## Editing blank responses for multiple submissions - -Sometimes, there may be a scenario when users have to add a question at the -middle or end of the survey. In such a case, the survey data from the -**DATA>Table** should see, as shown in the image below. - - - -This section of the support article should outline _how to change all these -empty states to **Alabama**_. - -**Step 1:** - -To start editing blank responses for multiple submissions, users should select -multiple records (marked **1**) and then press **Edit** (marked **2**). - - - -**Step 2:** - -Users will now have to press **Edit** (as shown in the image below), which is in -a parallel line straight to _State_ as we are updating the empty states for all -the records. - - - -**Step 3:** - -In this case, users should type in the required text (**Alabama** in our case) -in the blank box (marked **1**) and then press **SAVE** (marked **2**). - - - -**Step 4:** - -A dialogue box appears. Users will now have to press **CONFIRM & CLOSE** to save -the changes made. - - - -Users could always go back to **DATA>Table** and check if the bulk edits were -successful. - - diff --git a/source/howto_edit_single_submissions.md b/source/howto_edit_single_submissions.md deleted file mode 100644 index bb8c8b2dd..000000000 --- a/source/howto_edit_single_submissions.md +++ /dev/null @@ -1,23 +0,0 @@ -# Editing or Deleting a Single Submission -**Last updated:** 24 Sep 2025 - - -To edit or delete a submitted questionnaire, please follow the steps below. - -Please note that if you are collecting data with the [KoboCollect app](https://support.kobotoolbox.org/data_collection_kobocollect.html), once a form has been - submitted to the server it is **not possible** to edit or delete a - submission from KoboCollect. - -1. Open the _DATA_ tab of your project, and then click on _Table_ on the left. - You will see two icon options to either **Open** or **Edit** a record in the - first column of the data table. - -  - -2. You can view, validate, edit, or delete submissions by clicking the **OPEN** - icon to open the _Submission Record_ modal. Or you can click the **EDIT** - icon to go directly to editing the submitted form. - - **NOTE: DELETING IS NOT REVERSIBLE.** - -  diff --git a/source/images/editing_deleting_data/bulk_edit.png b/source/images/editing_deleting_data/bulk_edit.png new file mode 100644 index 000000000..e89f1cf02 Binary files /dev/null and b/source/images/editing_deleting_data/bulk_edit.png differ diff --git a/source/images/editing_deleting_data/delete.png b/source/images/editing_deleting_data/delete.png new file mode 100644 index 000000000..4ef8c6248 Binary files /dev/null and b/source/images/editing_deleting_data/delete.png differ diff --git a/source/images/editing_deleting_data/duplicate.png b/source/images/editing_deleting_data/duplicate.png new file mode 100644 index 000000000..0051e2818 Binary files /dev/null and b/source/images/editing_deleting_data/duplicate.png differ diff --git a/source/images/editing_deleting_data/edit.png b/source/images/editing_deleting_data/edit.png new file mode 100644 index 000000000..58c8e4352 Binary files /dev/null and b/source/images/editing_deleting_data/edit.png differ diff --git a/source/images/editing_deleting_data/resubmit.png b/source/images/editing_deleting_data/resubmit.png new file mode 100644 index 000000000..dedda07ca Binary files /dev/null and b/source/images/editing_deleting_data/resubmit.png differ diff --git a/source/images/kobotoolbox_interface/data.png b/source/images/kobotoolbox_interface/data.png new file mode 100644 index 000000000..ae1c6be52 Binary files /dev/null and b/source/images/kobotoolbox_interface/data.png differ diff --git a/source/images/kobotoolbox_interface/form.png b/source/images/kobotoolbox_interface/form.png new file mode 100644 index 000000000..c5565b976 Binary files /dev/null and b/source/images/kobotoolbox_interface/form.png differ diff --git a/source/images/kobotoolbox_interface/projects.png b/source/images/kobotoolbox_interface/projects.png new file mode 100644 index 000000000..710d0f7ec Binary files /dev/null and b/source/images/kobotoolbox_interface/projects.png differ diff --git a/source/images/kobotoolbox_interface/settings.png b/source/images/kobotoolbox_interface/settings.png new file mode 100644 index 000000000..7ceea56ce Binary files /dev/null and b/source/images/kobotoolbox_interface/settings.png differ diff --git a/source/images/kobotoolbox_interface/summary.png b/source/images/kobotoolbox_interface/summary.png new file mode 100644 index 000000000..d4f1d472b Binary files /dev/null and b/source/images/kobotoolbox_interface/summary.png differ diff --git a/source/images/managing_media_responses/bulk_delete.png b/source/images/managing_media_responses/bulk_delete.png new file mode 100644 index 000000000..b5bd5610b Binary files /dev/null and b/source/images/managing_media_responses/bulk_delete.png differ diff --git a/source/images/managing_media_responses/delete_audio.png b/source/images/managing_media_responses/delete_audio.png new file mode 100644 index 000000000..314ac1c76 Binary files /dev/null and b/source/images/managing_media_responses/delete_audio.png differ diff --git a/source/images/managing_media_responses/delete_from_table.png b/source/images/managing_media_responses/delete_from_table.png new file mode 100644 index 000000000..0ec09b971 Binary files /dev/null and b/source/images/managing_media_responses/delete_from_table.png differ diff --git a/source/images/managing_media_responses/download.png b/source/images/managing_media_responses/download.png new file mode 100644 index 000000000..16c19bb68 Binary files /dev/null and b/source/images/managing_media_responses/download.png differ diff --git a/source/images/managing_media_responses/open_submission_view.png b/source/images/managing_media_responses/open_submission_view.png new file mode 100644 index 000000000..11729cac3 Binary files /dev/null and b/source/images/managing_media_responses/open_submission_view.png differ diff --git a/source/images/managing_media_responses/table.png b/source/images/managing_media_responses/table.png new file mode 100644 index 000000000..0ec09b971 Binary files /dev/null and b/source/images/managing_media_responses/table.png differ diff --git a/source/images/managing_projects/archive_home.png b/source/images/managing_projects/archive_home.png new file mode 100644 index 000000000..1bec50bfe Binary files /dev/null and b/source/images/managing_projects/archive_home.png differ diff --git a/source/images/managing_projects/archive_settings.png b/source/images/managing_projects/archive_settings.png new file mode 100644 index 000000000..f8163ab9b Binary files /dev/null and b/source/images/managing_projects/archive_settings.png differ diff --git a/source/images/managing_projects/create.png b/source/images/managing_projects/create.png new file mode 100644 index 000000000..6399c2672 Binary files /dev/null and b/source/images/managing_projects/create.png differ diff --git a/source/images/managing_projects/delete_home.png b/source/images/managing_projects/delete_home.png new file mode 100644 index 000000000..81e6d0058 Binary files /dev/null and b/source/images/managing_projects/delete_home.png differ diff --git a/source/images/managing_projects/delete_settings.png b/source/images/managing_projects/delete_settings.png new file mode 100644 index 000000000..6fc23b344 Binary files /dev/null and b/source/images/managing_projects/delete_settings.png differ diff --git a/source/images/project_files_media/form.png b/source/images/project_files_media/form.png new file mode 100644 index 000000000..71a3c222c Binary files /dev/null and b/source/images/project_files_media/form.png differ diff --git a/source/images/upload_media/upload_media.png b/source/images/upload_media/upload_media.png new file mode 100644 index 000000000..c6ba28128 Binary files /dev/null and b/source/images/upload_media/upload_media.png differ diff --git a/source/images/upload_media/upload_url.png b/source/images/upload_media/upload_url.png new file mode 100644 index 000000000..e78ad837e Binary files /dev/null and b/source/images/upload_media/upload_url.png differ diff --git a/source/images/viewing_validating_data/open_submission.png b/source/images/viewing_validating_data/open_submission.png new file mode 100644 index 000000000..70d78315f Binary files /dev/null and b/source/images/viewing_validating_data/open_submission.png differ diff --git a/source/images/viewing_validating_data/select.png b/source/images/viewing_validating_data/select.png new file mode 100644 index 000000000..b22ed169d Binary files /dev/null and b/source/images/viewing_validating_data/select.png differ diff --git a/source/images/viewing_validating_data/table_view.png b/source/images/viewing_validating_data/table_view.png new file mode 100644 index 000000000..4c6ead4cf Binary files /dev/null and b/source/images/viewing_validating_data/table_view.png differ diff --git a/source/images/viewing_validating_data/view_submission.png b/source/images/viewing_validating_data/view_submission.png new file mode 100644 index 000000000..9a369c2f1 Binary files /dev/null and b/source/images/viewing_validating_data/view_submission.png differ diff --git a/source/index.rst b/source/index.rst index 721d53700..3883b54ca 100644 --- a/source/index.rst +++ b/source/index.rst @@ -169,22 +169,20 @@ Search the knowledge base, browse our resources, and visit our forum for more de :caption: Managing Projects & Data :name: home-page-toc-managing-projects - project_summary - record_validation - delete_project + kobotoolbox_interface + managing_projects + viewing_validating_data + editing_deleting_data export_download advanced_export managing_repeat_groups - archiving_projects project_sharing_settings managing_permissions - export_gps - howto_edit_single_submissions - howto_edit_multiple_submissions - photo_download - deleting_media - getting_started_organization_feature + project_files_media + upload_media + managing_media_responses activity_logs + getting_started_organization_feature .. raw:: html diff --git a/source/kobotoolbox_interface.md b/source/kobotoolbox_interface.md new file mode 100644 index 000000000..af4be66c6 --- /dev/null +++ b/source/kobotoolbox_interface.md @@ -0,0 +1,80 @@ +# Overview of the KoboToolbox interface + +This article provides an overview of the KoboToolbox interface and explains how to navigate the main pages where you create forms, manage data, and configure project settings. It introduces the **Projects home page** and the four main pages within each project: **SUMMARY**, **FORM**, **DATA**, and **SETTINGS**. + +## Navigating the Projects home page +When you sign in to your KoboToolbox account, you land on the **Projects home page**. The **Projects home page** displays all projects that you own or that have been shared with your account. From there, you can also access key features and account-level settings. + +The **Projects home page** includes the following: +* A list of all projects owned by or shared with your account. +* Access to the **Library** from the left side menu. +* The **NEW** button to create a new project. +* Tabs to view **Deployed**, **Draft**, or **Archived** forms. +* A **Search** bar to find projects in your project list. +* A **profile icon** in the top right corner to access [account settings](https://support.kobotoolbox.org/account_settings.html), change the interface language, or log out of your account. + ++ Note: From any page in your KoboToolbox account, click Help for quick links to the Help Center, Community Forum, KoboToolbox Academy, and to view in-app notifications. Click Source to access the KoboToolbox source code. +
+ + + + +## Working within a project +To open a project, click on its name in the **My Projects** table. Each project contains four main pages: **SUMMARY**, **FORM**, **DATA**, and **SETTINGS**. + +### SUMMARY page +The **SUMMARY** page provides an overview of your project, including: +* **Project information** such as the description, status, owner, and dates last modified and deployed. +* **Submission statistics** for the past seven days, 31 days, three months, 12 months, and the total number of submissions. +* **Quick links** to key project functionalities (e.g., edit or preview form). +* **Sharing permissions** and users the project is shared with. + + + +### FORM page +The **FORM** page contains tools for building, updating, and deploying your project. It is divided into sections. + +In the **Current version** section, you can: +* **Preview** the current form version. +* **Edit** the form in the [Formbuilder](https://support.kobotoolbox.org/formbuilder.html). +* **Replace** the form with an [XLSForm](https://support.kobotoolbox.org/getting_started_xlsform.html) or [template](https://support.kobotoolbox.org/question_library.html). +* Open the **More actions** menu to download the XLSForm or XML file, [share the project](https://support.kobotoolbox.org/managing_permissions.html), clone the project, or create a template. +* **Manage translations** for forms with [multiple languages](https://support.kobotoolbox.org/language_dashboard.html). +* **DEPLOY** or **REDEPLOY** the form. + +In the **Form history** section, you can: +* View past versions of the form and their deployment dates. +* Clone previous form versions. + +In the **Collect data** section, you can: +* Choose a [data collection method](https://support.kobotoolbox.org/data_through_webforms.html). +* Click **Copy** to copy the link or **Open** to open the form in your browser. +* Allow submissions [without requiring a username and password](https://support.kobotoolbox.org/project_sharing_settings.html#allowing-submissions-without-authentication). + + + +### DATA page +The **DATA** page provides access to all collected data and includes a data **Table**, custom **Reports**, a photo **Gallery**, a **Download** tab to export data, and a **Map** view for GPS data. + ++ To learn more about managing your data in KoboToolbox, see Viewing and validating your data and Editing and deleting your data. +
+ + + + +### SETTINGS page +The **SETTINGS** page contains configuration options for your project. It is divided into multiple tabs: +* **General:** Update the project name and description, [archive](https://support.kobotoolbox.org/glossary.html#archived-projects) or delete the project. +* **Media:** Upload media files and [manage uploaded files](https://support.kobotoolbox.org/managing_files_media.html). +* **Sharing:** Update [sharing permissions](https://support.kobotoolbox.org/managing_permissions.html) for other users. +* **Connect Projects:** Set up connections for [dynamic data attachments](https://support.kobotoolbox.org/dynamic_data_attachment.html). +* **REST Services:** Configure [REST services](https://support.kobotoolbox.org/rest_services.html) to automatically send submissions to third-party applications. +* **Activity:** View and export the [project history logs](https://support.kobotoolbox.org/activity_logs.html#project-history-logs), including changes made by other users. + + + ++ To learn more about managing projects, see Managing projects in KoboToolbox. +
diff --git a/source/managing_media_responses.md b/source/managing_media_responses.md new file mode 100644 index 000000000..66c450a1f --- /dev/null +++ b/source/managing_media_responses.md @@ -0,0 +1,128 @@ +# Managing respondent-submitted media + +Media files collected from respondents often contain important contextual information, such as photos, recordings, or documents that support and enrich survey data. After data collection begins, **these files become part of your project data** and need to be managed carefully. + +This article explains how to view, download, and delete media files submitted by respondents, including images, audio recordings, videos, and other file types. + +## Viewing media files + +All media files submitted by respondents can be viewed from your project’s data table. To open media files in individual submissions: + +1. Open your project and go to the **DATA** page. +2. In the data table, locate the cell containing the file. +3. Click the **image**, **video**, or **file** icon. For audio recordings, click **Open**. + + + +Images can also be viewed in the **Gallery** view of your project. To view all images collected within a single project: + +1. Open your project and go to the **DATA** page. +2. Open the **Gallery** tab from the left-side menu. +3. The **Gallery** view displays all images collected in the project. You can filter images by question or by date range. + +## Downloading media files + +You can download media files either individually from the data table, or in bulk from the **Downloads** page. + +### Downloading individual media files + +To download a single file: + +1. Go to the **DATA** page. +2. In the data table, locate the cell containing the file. +3. Click the **image**, **video**, or **file** icon. For audio recordings, click **Open.** +4. Click the three dots at the top of the preview. +5. Click **Download.** + + + +### Downloading media files in bulk + +To download media files in bulk: + +1. Go to the **DATA** page. +2. Open the **Downloads** tab from the left-side menu. +3. Under **Select export type**, choose **Media Attachments (ZIP)**. +4. Click **New Export** and wait for the export to complete. +5. Download the generated `.zip` file from the table. + +In the downloaded folder, attachments are grouped by submission. Each folder name corresponds to the submission’s `_uuid`, which also appears as a column in the dataset. + ++Note: Media exports include only questions that are present in the most recent version of the form. +
+ +When you export your data in CSV or XLS format, the exported file also includes hyperlinks that open the associated media files in a web browser, as long as the default option to **Include media URLs** is selected. + ++ To learn more about exporting your data, see Exporting and downloading your data. +
+ +## Deleting media files + + + +You may need to delete media files from your KoboToolbox project for various reasons, such as maintaining confidentiality, managing storage space, or correcting submission errors. You can delete media files individually, or delete multiple files in bulk. + +### Deleting individual media files + +There are two ways to delete individual media files: directly from the data table or by opening the submission. Once a file is deleted, it is marked as _Deleted_ in the data table and cannot be recovered. + +**Deleting individual media files from the data table** + +You can delete individual images, videos, and files directly from the data table, with the following steps: + +1. In the data table, locate the cell with the media file you want to delete. +2. Click the **image**, **video**, or **file** icon. +3. Click the **three dots** at the top of the file preview. +4. Click **Delete**, then **Delete** again to confirm. + + + +**Deleting individual media files in the submission view** + +You can also delete media files by opening the submission view: + +1. In the data table, locate the submission with the media files you want to delete. +2. On the left side of the submission, click **Open**. +3. Scroll down to the media file you want to delete. +4. Click the **three dots** to the right of the media file. +5. Click **Delete**, then **Delete** again to confirm. + + + +**Deleting audio files in the audio question view** + +You can delete audio files by opening the audio question view for transcription, translation, and analysis of audio questions: + +1. In the data table, click on **Open** to open the audio question view. +2. In the **TRANSCRIPT**, **TRANSLATIONS**, or **ANALYSIS** tab, locate the audio file in the top right corner. +3. Click the **three dots** to the right of the audio file. +4. Click **Delete**, then **Delete** again to confirm. + + + +### Deleting media files in bulk + +You may need to delete media files in bulk, for example, to manage storage space after they have been exported. You can delete all media files for selected submissions using the following steps: + +1. Select the submissions for which you want to delete media files. +2. Click **Delete media files only** above the data table. + * This action opens a modal showing the number and types of media files to be deleted with this selection. +3. Check the box that says "You are about to permanently remove the following media files from the selected submissions:". + * This step acknowledges that the files will be permanently deleted and are not recoverable. +4. Click **Delete**. + ++ Note: With this approach, all media files from each selected submission will be deleted; it is not currently possible to choose only files for a given question. +
+ + + +## Troubleshooting + ++ To learn more about managing your data in KoboToolbox, see Viewing and validating your data and Editing and deleting your data. +
+ + +## Archiving and deleting projects +As projects become outdated or no longer needed, you can remove them from active use by **archiving** or **deleting** them. Archiving stops new submissions while keeping the form and existing data available. Deleting permanently removes the project and all of its data from your account. + ++ Note: Because deleted projects cannot be recovered, delete a project only when you are certain that neither the form nor its data will be needed. Before deleting a project, we recommend downloading the form as an XLSForm and exporting all project data. +
+ +### Archiving projects +Archiving is recommended for forms that should no longer accept submissions but need to remain available for reference. + +There are two ways to archive a project. To archive a project from the **Projects home page**: +1. In the **Projects home page**, select the project checkbox. +2. Click **Archive project** in the top right corner. +3. You will be asked to confirm that your form will not accept submissions while it is archived. Click **ARCHIVE** to confirm. + + + +To archive a project from the project **SETTINGS**: +1. Open the project and go to the **SETTINGS** page. +2. In the **General** tab, click **Archive Project**. +3. You will be asked to confirm that your form will not accept submissions while it is archived. Click **ARCHIVE** to confirm. + + + +To unarchive a project, follow the same steps and click **Unarchive Project**. + +### Deleting projects +Deleting a project permanently removes the form and all associated data. This action cannot be reversed. + +There are two ways to delete a project. To delete a project from the **Projects home page**: +1. In the **Projects home page**, select the checkbox next to the project. +2. Click **Delete 1 project** in the top right corner. +3. A confirmation dialog will require you to acknowledge the following: + * You are about to permanently delete this form. + * All data gathered for this form will be deleted. + * The form associated with this project will be deleted. + + + +To delete a project from the project **SETTINGS**: +1. Open the project and go to the **SETTINGS** page. +2. In the **General** tab, click **Delete Project and Data**. +3. A confirmation dialog will require you to acknowledge the following: + * You are about to permanently delete this form. + * All data gathered for this form will be deleted. + * The form associated with this project will be deleted. + + + + diff --git a/source/managing_repeat_groups.md b/source/managing_repeat_groups.md index 014cd1d49..25db950f9 100644 --- a/source/managing_repeat_groups.md +++ b/source/managing_repeat_groups.md @@ -15,7 +15,7 @@ You can view repeated data in the data table, which you can find in the **Table* You can also view the complete data for any given submission, including each repetition of repeat groups, by clicking the **Open** button to the left of each submission. -To edit repeat group data, click the **Edit** button. This will open up the form and allow you to [edit the form data](https://support.kobotoolbox.org/howto_edit_single_submissions.html) before resubmitting. [Bulk editing](https://support.kobotoolbox.org/howto_edit_multiple_submissions.html) repeat group data is not currently supported. +To edit repeat group data, click the **Edit** button. This will open up the form and allow you to [edit the form data](https://support.kobotoolbox.org/editing_deleting_data.html) before resubmitting. [Bulk editing](https://support.kobotoolbox.org/editing_deleting_data.html#editing-multiple-submissions-in-bulk) repeat group data is not currently supported.Note: Repeat group data cannot be displayed in the Reports or Map views due to the data structure of repeat groups. diff --git a/source/media.md b/source/media.md index a071872bd..b867c893f 100644 --- a/source/media.md +++ b/source/media.md @@ -57,6 +57,10 @@ To upload the media files to KoboToolbox:  +
+ To learn more about uploading media files, see Uploading media files to a project. +
+ ## Adding media to choices in XLSForm To add media files to option choices in your XLSForm: @@ -126,7 +130,7 @@ To upload the translated media files to KoboToolbox: 4. Deploy or redeploy your form to see media changes.- Note: To learn more about managing translations in XLSForm, see Adding translations in XLSForm. + To learn more about managing translations in XLSForm, see Adding translations in XLSForm.
## Troubleshooting diff --git a/source/photo_download.md b/source/photo_download.md deleted file mode 100644 index 59ecaa039..000000000 --- a/source/photo_download.md +++ /dev/null @@ -1,82 +0,0 @@ -# Downloading Photos and Other Media -**Last updated:** 29 Jul 2025 - - -If your form [includes](question_types.md) a photo, video, or audio recording -question, these files will be uploaded to the server along with your other data. -When exporting your dataset to XLS or CSV these files will include references to -the filenames of the media attachments, but not the files themselves. To -download all your media files in bulk, choose the **Media Attachments (ZIP)** -option under **DATA>Downloads>Select export type**. - -The following explains other options for downloading and accessing your -collected media files. - -The ZIP export may fail for very large projects due to a server -time-out limit of 30 minutes being reached. If that is the case, please follow -the methods below to extract your media files from the -KoboToolbox server.
- -## Including direct hyperlinks to collected media in XLS export - -1. Navigate to **DATA>Downloads** and expand the **Advanced options** section -2. Ensure that the option _Include media URLs_ is checked (enabled by default) - - - -3. Click **EXPORT** - -If your survey had the following question: - -**survey sheet** - -| type | name | label | -| :---- | :------ | :-------------- | -| image | image_1 | Submit an image | -| survey | - -And a submission to that question with the filename of "image.jpg", the export -will have the following result: - -| image_1 | image_1_URL | -| :-------- | :------------------------ | -| image.jpg | https://link/to/image.jpg | - -## For slow connections or very large projects: Using DownThemAll - -The ZIP download method will always include all of your project's media files. -This can take a long time to download in case of a large number of collected -images or videos or in case of a slow connection. Here is a workaround to -download all (or a selection of) media using the popular **DownThemAll** -download manager (only supported by the Firefox browser): - -1. Save your Excel file with the added hyperlinks (see instructions above) as an - HTML file to your Desktop, using the File > Save as... option (choose 'Web - page') - -2. Log in to your KoboToolbox account where your photos are hosted using the - Firefox browser - -3. In Firefox install the - [DownThemAll extension](https://addons.mozilla.org/en-CA/firefox/addon/downthemall) - -4. Still in Firefox, open the HTML web page saved from **Step 1** - -5. Right-click somewhere on that page and choose _DownThemAll!_, or click the - extension button in the Firefox Toolbox - -6. In the extension window that opens click **Download**. By default, Firefox - will save all files in your computer's Download folder (which can be changed) - -7. Optional: In the window that opens, set a download speed limit to avoid using - all available bandwidth. The settings also allow you to set the number of - attempts that should be made for each file in case of connection issues. - -If you have a lot of media files this will take a while to download. But the -**DownThemAll** download manager will make sure you have downloaded all the -images and let you know in case any of them were not downloaded so you can try -again. - - - - diff --git a/source/project_files_media.md b/source/project_files_media.md new file mode 100644 index 000000000..e82bf2e7e --- /dev/null +++ b/source/project_files_media.md @@ -0,0 +1,135 @@ +# Project files and media overview + +A KoboToolbox project may include files and media added at different stages of the data collection process. + +During form development, you can: + +- **Attach media files** to enhance your form with images, audio, or video. +- **Attach external data files** to manage large choice lists or pull data into your form. + +During data collection, respondents can **submit their own files and media** as part of their responses. + +These two categories are handled differently within a project. + ++Note: Only media and files submitted by respondents count toward your plan’s storage limits. +
+ +This article provides an overview the following topics: +- Adding media attachments and data files to your form +- Uploading files and media to KoboToolbox +- Collecting files and media from respondents +- Viewing, downloading, and deleting media from respondents + +## Attaching external files and media to your form + +KoboToolbox allows you to **upload media files** to your form, such as images, audio recordings, and videos, to help respondents better understand questions and reduce the need for follow-up clarification. + +KoboToolbox also allows you to **attach external CSV files** to your form to manage large choice lists or support form logic. Using external files makes it easier to reuse and update datasets without editing the form itself, therefore reducing ongoing form maintenance and supporting consistent, high-quality data. + +The sections below provide an overview of these features and link to the relevant support articles. + +### Adding media to your form + +Including images, videos, or audio recordings in your form’s notes, questions, and choices can help make forms **more engaging and accessible.** This can especially be useful for users with visual impairments or literacy barriers. + + + +To include media in your form, you must use XLSForm and then [upload the XLSForm](https://support.kobotoolbox.org/xlsform_with_kobotoolbox.html) to KoboToolbox. The KoboToolbox Formbuilder does not currently support adding media files directly within the form editor. + ++ To learn how to include images, videos, or audio recordings in XLSForm, see Adding media to an XLSForm. +
+ +### Attaching external data files to your form + +In addition to uploading media files, KoboToolbox supports attaching external data files to your forms to retrieve or reference external data during data collection. + +There are two main ways to connect your form to external files: + +- The `pulldata()` function **pulls information from an external data file** while a form is being completed. This is useful for referencing existing datasets and reducing repeated data entry by enumerators. + +
+Note: The pulldata() function uses external files as its data source. If you want to reference data from another KoboToolbox project instead of a CSV file, you can use dynamic data attachments.
+
+ To learn how to attach external datasets to your form, see Pulling data from an external CSV and Selecting options from an external file. +
+ +### Uploading files and media to KoboToolbox + +After adding media references or external files to your form, you must upload those files to your project. This is done in your project’s **SETTINGS > Media** page. + ++ To learn how to upload files and media to KoboToolbox, see Uploading media files to a project. +
+ +The following types of files are currently supported for upload to KoboToolbox: + +| Media | Types | +|:-----|:------| +| Image | .jpeg, .png, .svg | +| Audio | .aac, .aacp, .flac, .mp3, .mp4, .mpeg, .ogg, .wav, .webm, .x-m4a, .x-wav | +| Video | .3gpp, .avi, .flv, .mov, .mp4, .ogg, .qtff, .webm, .wmv | +| File | .csv, .xml, .zip, .geojson | + ++Note: The maximum file size for uploads is 100 MB. Files larger than this must be reduced in size before uploading. +
+ +## Collecting files and media from respondents + +In addition to including media in your form, you can collect files and media directly from respondents during data collection. This includes **images, audio recordings, videos, and other file types.** Collecting media allows you to capture qualitative information that adds visual or audio context to your data. + ++Note: Each file uploaded by a respondent can be up to 10 MB in size, with a maximum total of 100 MB per submission. +
+ +The following media question types are available in KoboToolbox: + +| Formbuilder question type | XLSForm question type | Description | +|:--------------------------|:----------------------|:------------| +| Photo | `image` | Capture or upload an image. Can also be used to collect [drawings, annotated images, and signatures](https://support.kobotoolbox.org/photo_audio_video_file.html#advanced-appearances). | +| Audio | `audio` | Record or upload an audio file. | +| Video | `video` | Record or upload a video file. | +| File | `file` | Attach a file (e.g., .pdf, .docx). | + +KoboToolbox also supports background audio recording for entire interviews +or focus group discussions. + ++ To learn more about collecting media from respondents, see Media question types. To learn more about background audio recording, see Recording interviews with background audio recording. +
+ +### Viewing media files + +All media files submitted by respondents can be viewed from the data table. Images can also be viewed in the **Gallery** view of your project. + ++ To learn more about viewing media from respondents, see Viewing media files. +
+ +### Downloading media files + +You can download media files either individually from the data table, or in bulk from the **Downloads** page. + +When you export your data in CSV or XLS format, the exported file also includes hyperlinks that open the associated media files in a web browser, as long as the default option to **Include media URLs** is selected. + ++ To learn more about exporting your media files, see Downloading media files. +
+ +### Deleting media files + +Finally, you may need to delete media files to **manage storage, protect confidentiality, or correct submission errors.** Media files can be deleted individually or in bulk. + +Once a file is deleted, it is marked as *Deleted* in the data table and cannot be recovered. + ++ To learn about different methods for deleting media files, see Deleting media files. +
diff --git a/source/project_summary.md b/source/project_summary.md deleted file mode 100644 index 12f65301c..000000000 --- a/source/project_summary.md +++ /dev/null @@ -1,14 +0,0 @@ -# Project Summary -**Last updated:** 28 May 2020 - - -The Project Summary tab gives you a visual display of all the high-level information related to your project. Depending on whether you're the project owner or a user with restricted permissions, different information will be shown to you. The Project Summary includes: - - 1. **Description**: Includes all project metadata. - 2. **Submissions**: A tally and graph of the submissions (up to the past 31 days). - 3. **Form details**: Includes last modified, last submission, and number of questions. - 4. **Quick links**: Useful links related to data collection for the project. - 5. **Data**: Useful links to information related to submitted data. - 6. **Team members**: List of users that have access to the project. - - diff --git a/source/pull_data_kobotoolbox.md b/source/pull_data_kobotoolbox.md index 6bb6ebde1..988c9f0b7 100644 --- a/source/pull_data_kobotoolbox.md +++ b/source/pull_data_kobotoolbox.md @@ -70,6 +70,10 @@ The final step in linking your external CSV file to your form is uploading the f  ++ To learn more about uploading media files, see Uploading media files to a project. +
+ ## Troubleshooting+ To learn more about uploading media files, see Uploading media files to a project. +
+ ## Troubleshooting+ To learn more about project files and media, see Project files and media overview. +
+ +## Supported file types + +KoboToolbox allows you to upload the following files: +- **Media files**, such as images, audio recordings, and videos, to help respondents better understand questions and enhance your form. + ++ To learn how to include images, videos, or audio recordings in XLSForm, see Adding media to an XLSForm. +
+ +- **External data files**, such as CSV or XML files, to manage large choice lists or support form logic. Using external files makes it easier to reuse and update datasets without editing the form itself, therefore reducing ongoing form maintenance and supporting consistent, high-quality data. + ++To learn how to attach external datasets to your form, see Pulling data from an external CSV and Selecting options from an external file. +
+ +The following files are currently supported for upload to KoboToolbox: +| Type | File extensions | +|:-----|:----------------| +| Image | .jpeg, .png, .svg | +| Audio | .aac, .aacp, .flac, .mp3, .mp4, .mpeg, .ogg, .wav, .webm, .x-m4a, .x-wav | +| Video | .3gpp, .avi, .flv, .mov, .mp4, .ogg, .qtff, .webm, .wmv | +| File | .csv, .xml, .zip, .geojson | + +## Uploading files from your local device + +After adding media references or external files to your form, you must upload those files to your project. This is done in your project’s **SETTINGS > Media** page. + +To upload files and media from your local device: +1. Sign in to your [KoboToolbox account](https://www.kobotoolbox.org/sign-up/). +2. Open your project and go to the **SETTINGS** page. +3. Open the **Media** tab. +4. Upload the files used by your form. File names must exactly match the names referenced in the form. +5. Deploy or redeploy the form to apply the changes. + + + ++Note: The maximum file size for uploads is 100 MB. Files larger than this must be reduced in size before uploading. +
+ +## Uploading files via URL + + + +You can also upload a file to KoboToolbox by providing a direct URL to the file. This can be useful if your file is hosted online, such as a CSV file stored in a GitHub repository. + +To upload files and media via URL: +1. Sign in to your [KoboToolbox account](https://www.kobotoolbox.org/sign-up/). +2. Open your project and go to the **SETTINGS** page. +3. Open the **Media** tab. +4. Paste a valid URL under “You can also add files using a URL” (see requirements below). Click **Add.** +5. Deploy or redeploy the form to apply the changes. + + + ++Note: The file name at the end of the URL must match exactly the file name referenced in the form. +
+ +### URL requirements + +The URL must meet both of the following requirements: + +- The URL must end with a supported file extension (for example, `.png`, `.jpg`, or `.csv`). +- The URL must open the file directly in your browser, not a web page that contains the file. The URL will not work if it points to a page on a service like Google Drive, GitHub, or Dropbox. + ++Note: If the file is later unpublished or deleted, the file will stop working in KoboToolbox. +
+ +### Obtaining a direct URL for images + +For images, use the image’s direct address from the source website. + +To get a usable image URL: +1. Open the webpage that contains the image. +2. Right-click the image and select **Copy image address** (or the equivalent option in your browser). + - Confirm the URL ends with an image extension (for example, `.png` or `.jpg`). +3. Paste the URL into your browser to confirm it opens the image directly. + +### Obtaining a direct URL for CSV files + +For `.csv` files, the URL must open the raw CSV content directly in your browser. A common approach is to host the CSV on GitHub and use the Raw link: + +1. Upload or commit your `.csv` file to a GitHub repository. +2. Open the CSV file in GitHub. +3. Click **Raw**. The CSV content should be displayed directly in your browser. +4. Copy the URL from your browser address bar. + ++Note: Google Sheets published as a CSV is not supported for this workflow, because KoboToolbox does not accept the format produced by that approach. +
+ +If you update the CSV file at the same URL, KoboToolbox will **reflect the updated file after a short delay.** To retrieve updates more consistently, we recommend regularly redeploying the form. + +### Referencing uploaded files in your form + +Once the file is available in KoboToolbox, reference it the same way you would for other uploaded media or choice files: + +- In `select_one_from_file` or `select_multiple_from_file` questions +- Inside the `pulldata()` function +- In media columns of your XLSForm (`image`, `audio`, `video`) + +When referring to the uploaded files, use **only the file name and extension** at the end of the URL (for example, `choices.csv` or `photo.jpg`). Do not include the full URL in these fields. diff --git a/source/viewing_validating_data.md b/source/viewing_validating_data.md new file mode 100644 index 000000000..0961dccf4 --- /dev/null +++ b/source/viewing_validating_data.md @@ -0,0 +1,145 @@ +# Viewing and validating your data + + + +The **Table** view in the **DATA** section of your KoboToolbox project provides a complete and customizable overview of all project submissions. By default, all records are shown, with the most recent submissions listed first. This view is the primary workspace for exploring data, monitoring data quality, validating submissions, and making edits. + +This article explains how to: + +- Configure the data table in the **Table** view +- Filter and sort your data +- View and validate submissions + ++To learn more about making changes to your data, see Editing and deleting your data. +
+ +Project owners can control data access by assigning separate permissions to view, edit, validate, and delete submissions. For example, they can allow some team members to view and validate data while restricting editing and deletion permissions. + ++To learn more about user-level permissions for viewing, validating, and editing data, see Sharing projects with user-level permissions. +
+ +## Configuring the data table + +The data table in the **Table** view displays all submissions and data fields by default. In many projects, a more focused view is needed. Adjusting what appears in the table helps you work more efficiently, especially for forms with many questions or nested groups. You can choose which fields to display and how data is shown to better match your workflow. + + + +### Customizing the data table + +Above the data table, you can configure the following settings: + +- **Hide fields:** Click **hide fields** to view a list of all questions and fields in your form. All fields are selected by default. Clear the checkbox for any field you want to hide, then click Apply to save your changes. +- **Toggle fullscreen:** Click **Toggle fullscreen** to expand the data table to fill the browser window. +- **Display options:** Click **Display options** to control how labels, groups, and HXL tags are shown in the table. The following display options can be configured: + +| 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`). | +| 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 frequently used fields visible while you scroll. + ++Note: These settings affect the Table view for all project users. +
+ +### Navigating the data table + +You can change how many rows are shown per page using the dropdown at the bottom of the table. By default, the table displays 30 rows. + ++Note: Displaying many rows at once can slow down your browser. +
+ +Use the **PREV** and **NEXT** arrows, or enter a page number, to move through the data table. + +## Filtering and sorting your data + +By default, submissions in KoboToolbox appear in the data table in submission order, with the most recent entries at the top. In large projects, filtering and sorting are essential for exploring, reviewing, and cleaning data. They help you quickly find specific respondents, examine patterns, and identify records that need attention. + ++Note: The Table view in KoboToolbox provides basic filtering and sorting for data monitoring and editing. For more advanced data analysis, including filtering with multiple conditions, we recommend exporting your dataset and using spreadsheet or analysis software. +
+ +For each column in the data table, you can use the following features: + +- **Search:** Use the search bar above text, number, and date fields to filter results. For example, you can search for a unique ID or filter by a specific age. +- **Filter:** For fields based on select type questions, click **Show all** in the column header to open a list of answer options. Select an option to filter the responses. +- **Sort:** Click a column header and choose Sort **A → Z** or **Sort Z → A** to change the order of submissions. + ++Note: Sorting the table applies to all users and persists after you leave the Table view. Searching and filtering applies only to you while you are in the Table view and automatically resets when you leave it. +
+ +## Viewing individual submissions + +Opening an individual submission lets you review all data from a single respondent. The single submission view includes tools for examining and managing an individual record. + +To open a submission, click **View** in the corresponding row. + + + +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. +- **View** and **Edit** the submission [in Enketo](https://support.kobotoolbox.org/editing_deleting_data.html). +- **Duplicate** the submission. +- **Print** the submission. +- **Delete** the submission. +- Assign a **validation status.** + + + +Within the single submission view, navigate through submissions using **< Previous** and **Next >**. + +## Validating your data + +Record validation helps project teams maintain data quality, track review status, and flag issues that require follow-up. Validation status appears as a dedicated column in the **Table** view, and users with appropriate permissions can update them for individual or multiple submissions. + +The available statuses are: + +- **Approved:** The submission has been reviewed and confirmed to be complete, accurate, and suitable for use in analysis. +- **Not approved:** The submission does not meet data quality requirements and should be excluded from analysis or removed from the dataset. +- **On hold:** The submission requires review. Additional verification or follow-up is needed before the data can be accepted or rejected. + +Validation supports structured data review in collaborative teams. For example, reviewers can filter the table to show only submissions that require review. + ++Note: A project owner can grant Validate submissions permission to other users separately from the Edit submissions permission. +
+ +### Updating validation status in bulk + +Validation status can be applied to multiple submissions at once, which is useful for large-scale reviews or quality checks. + +To validate submissions in bulk: + +1. Select the submissions using the checkboxes. +2. Click **Change status.** +3. Choose a validation status. + ++Note: You can select all submissions on the current page by clicking the checkbox in the table header. To select all submissions in the project across all pages, click the arrow next to the checkbox and choose Select all results. +
+ + + +## Troubleshooting + +