How to connect KoBo, ODK, REDCap or Google Sheets to AnalyZ Solutions

01Why connect instead of exporting a file

Most survey tools let you download your data as a spreadsheet. That works for a one-off analysis, but it creates a problem as soon as data collection is still running. The file you downloaded on Monday does not include the forms submitted on Tuesday, and after a few rounds of export and re-import it is easy to lose track of which file holds the latest data.

A direct connection removes that step. Instead of moving a file, you give the analysis tool permission to ask the survey platform for the current records. When you want an update, you ask again. This is useful in three situations: monitoring a survey while fieldwork is under way, repeating the same analysis each month on fresh data, and working with a dataset that several people add to.

A connection is not always the better choice. If the data is final, a downloaded file is simpler and gives you a fixed copy you can store alongside your report. A connection always shows what the platform holds right now, so the numbers can change between two runs of the same analysis. Keep a saved copy of the data you used for anything you publish.

02What you need before you start

Every survey platform controls who can read its data, and a connection has to prove it has your permission. That proof is usually a token or a key. Think of it as a password made for programs rather than people.

• An account with access to the data. You can only connect to forms or projects your own account can read.
• An access token or key. For KoBo Toolbox, this is the API token under Account Settings, then Security. REDCap issues an API token for each project. ODK Central and other services accept either a bearer token or an API key.
• The address of the data. For KoBo, this is the link to your form. For other sources it is the address of the project or endpoint that returns the records.

03What can be connected

AnalyZ Solutions has ready-made settings for four sources and a general option for everything else.

• KoBo Toolbox. Both the main server and the humanitarian server are supported.
• ODK Central. Connect with a bearer token or an API key.
• REDCap. Connect with the project API token.
• Google Sheets. Use the Google Sheets setting and the address of your sheet.
• Any other service. Any web address that returns your records as JSON or CSV can be connected through the custom option.

04How to connect a source

The steps are the same for every source. Open the data loading area in the sidebar and choose the API connection option.

1. Choose the source
   Pick KoBo, ODK, REDCap or Google Sheets. The setting fills in what it can for you. Choose the custom option for any other service.
2. Enter the address
   For KoBo, paste the link to your form. You can paste the form page link, the export settings link or the direct data link, and AnalyZ Solutions works out which form you mean. For other sources, enter the address that returns your records.
3. Enter your token or key
   Paste the token. For custom and ODK connections, first choose how it is sent: as a bearer token or as an API key. Choose none only for a service that does not need one.
4. Set the data path if needed
   Some services return the records inside a larger response. If AnalyZ Solutions cannot find the rows on its own, enter the path to them, for example the name of the field that holds the list.
5. Connect and choose variables
   AnalyZ Solutions collects all pages of results, then shows a picker so you can keep only the variables you need. Confirm your choice to load the data.

If data is already loaded, you are warned that connecting will replace it, so you do not overwrite a working dataset by accident.

05What happens to your data on the way in

Survey platforms store data in a form designed for collection, not analysis. Part of what a good connection does is tidy that structure into something you can analyze straight away. For KoBo, AnalyZ Solutions does the following.

• It follows every page of results, so a large form is loaded in full and not just the first batch.
• It removes the platform's internal fields, such as submission times and system identifiers, but keeps your own survey variables.
• It reads value labels from the form, so a coded answer such as 1 appears with its label.
• It uses the question wording from the form as variable labels, including forms written in more than one language.
• It expands multiple-choice questions, where a respondent can select several options, so that the selected options are joined into one readable value separated by semicolons.
• It removes the group prefixes that forms add to column names.

For every source, columns that appear in only some records are kept, so a question answered by only a few respondents is not silently dropped.

After any import, run a data quality audit before analysis. Survey platforms often store answers such as "not applicable" or "refused" as numeric codes like 99 or -1, and these need to be declared as missing values, otherwise they will be treated as real numbers. Exploring the data first will also show you how each variable was read.

06Refreshing and reconnecting

A connection is saved with a name, so you can pull fresh records later without entering the details again. Use the refresh button next to the saved connection and the data is fetched again from the survey platform.

Your token is the one thing that is not kept. It is held for the current browser tab only, so you can refresh as often as you like while you work. If you save your work and come back another day, the connection settings are restored but you are asked for the token again. This is intentional. A saved file can be shared, emailed or backed up by accident, and it should never contain a credential. How saved work is stored is covered in how to save your work and pick it up again later.

07Privacy and the connection

A connection works slightly differently from loading a file. Browsers block most direct requests from one website to another, so requests to survey platforms go through a relay run by AnalyZ Solutions, which passes the response on to your browser. After that, the analysis runs inside your browser, as described in the privacy model.

If your ethics approval or data sharing agreement says that the data may only be downloaded to a device you control, a connection may not fit that wording. In that case, export the file from the survey platform and load it directly.

08Common problems

• The connection is rejected. The token is usually wrong, expired or copied with a trailing space. Generate a new one and paste it again.
• The form loads but has no rows. Your account may have access to the form but not to its submissions. Ask the form owner to share the data with you.
• Rows are found but the columns look wrong. The records may be nested inside the response. Enter the data path described in step 4.
• You see fewer records than expected. Check the form in the survey platform for filters, deleted submissions or a different server than the one you selected.
• A saved connection asks for the token again. This is expected after you close the browser. Paste the token and refresh.