What the connection allows
Once your account is linked, four things become possible from inside Opti', without leaving the app and without handling a single file:
- Sending a questionnaire designed in Opti' to a Kobo project, new or existing.
- Importing the answers of a project in order to analyse them, including a project created outside Opti'.
- Follow a collection live: new answers arrive on their own.
- Display the photos taken in the field, which cannot be viewed without authentication.
Linking your
In Opti Gemba, open the toolbox then KoboToolbox. The screen asks you two things.
- Where your account is. KoboToolbox does not have a single server: there is the Europe instance (eu.kobotoolbox.org) and the Global instance (kf.kobotoolbox.org), and some organisations host their own. If you pick the wrong one it does not matter: Opti' tries the other server and tells you which was right.
- Your token. Click "Show my token on Kobo": the page that opens shows your token, on your own server. Copy everything on it, curly brackets included, and paste it in. Opti' takes care of extracting the token.
Sending a questionnaire to Kobo
From the KoboToolbox panel, with a questionnaire open, you are offered two destinations: create a new project, or update an existing project. The second time, Opti' remembers the linked project and offers the update, instead of creating a duplicate.
Variable names are checked before upload
Kobo turns every variable name into a form tag, and rejects any that break the XML rules: starting with a digit, containing a space, being duplicated. This happens very often when the questionnaire comes from a document whose questions are numbered ("1_which_items_did_you_receive").
Opti' spots these names before upload and offers the corrections in one click. Your formulas (display conditions, calculations, constraints) are updated at the same time, and you can carry on using your old names when you talk to the AI.
Importing the answers
Next to each project in the list there is an "Import"button. It becomes "Refresh" once the project is linked. You will find the same entry in the Data collectionview, next to the file import.
If the project does not yet exist in Opti', its questionnaire is pulled in first and the assignment is created automatically. This is not a matter of convenience: loading answers into a form whose variables do not match produces a silently empty dataset, where the columns exist but the values never reach them.
The answers land in a collection named "Kobo · project name", reused from one refresh to the next. Repeat groups, multiple choice questions, GPS points and photos are kept in their original form: an imported dataset is analysed exactly like one collected in Opti'.
If the import is interrupted
On a dataset of several thousand answers, a network drop does not force you to start again: Opti' remembers where it was and offers to resume, without downloading again what has already arrived.
What blocks an import
| Situation | Why |
|---|---|
| Encrypted project | The answers can only be read with the form's private key, which Opti' does not hold. That is the whole point of Kobo encryption. |
| Project not deployed | A draft has received no answers: there is nothing to import. |
| No answers | The project is deployed but nobody has submitted a record yet. |
What "Refresh" does, exactly
A collection dataset is alive: an entry gets corrected, a duplicate deleted, a record rejected at quality control. A refresh that merely added what was new would leave Opti' analysing data Kobo has disowned, with no sign of it. The three cases are therefore handled separately.
| Case | What happens |
|---|---|
| New answer | Added to the collection. |
| Answer corrected in Kobo | Replaced by its updated version. Its original collection date is kept, so your time based analyses are not distorted. |
| Answer gone from Kobo | Flagged, never deleted automatically. Opti' shows you the list (date, enumerator, first answer) so you can recognise what is going, and you choose whether to remove them or keep them. |
The validation status
If you use Kobo's quality control (approved, pending, rejected), that status becomes a usable column in Opti': you can filter an analysis to approved answers only, or cross tabulate the rejection rate by enumerator.
Live tracking
This is the feature that changes the nature of the tool. Without it, Opti' analyses whatever somebody remembered to pull in. With it, your dashboard fills up while the teams are in the field, without anybody clicking "Refresh".
In practice, Opti' adds a service named "Opti'" to the REST Services of your Kobo project. Kobo then sends every new answer to Opti' the moment it arrives. You can remove that service from Opti' or from Kobo, at any time.
Tracking is offered once the project has been imported at least once: there has to be an assignment and a collection for the answers to land in, and both are created by the first import.
If your organisation does not allow API tokens
Some security policies forbid handing an API token to a third party service, and that rule is not negotiable from inside an interface. One route stays open, for sending a questionnaire.
- In the Opti' Kobo connection screen, unfold "My organisation does not allow API tokens".
- Click "Get the link". Opti' builds an address valid for two hours.
- In Kobo, click NEW then Import an XLSForm via URL, and paste the address.
No token is asked for and Opti' gets no access to your account. Importing answers and live tracking, on the other hand, do need a linked account: Kobo offers no equivalent without authentication.
Your data, plainly stated
The KoboToolbox connection is the only Opti' feature that reaches into an account you hold elsewhere. Here is what actually happens.
| Item | How it is handled |
|---|---|
| Your API token | Sent once, from the input field to our servers. Encrypted at rest with AES-256-GCM, using a key stored separately from the database. It never comes back to your browser: only the last four characters are shown again. Never passed to an artificial intelligence service. |
| Scope of access | The KoboToolbox token has no limited scope: it gives access to the whole account. Kobo offers no scopes, no expiry and no OAuth. Opti' uses it only for the actions you trigger. |
| One connection per person | Never per organisation, even on the Teams plan. Since a token gives access to the whole account, no team member should be able to act on a colleague's Kobo. |
| Your imported answers | Stored like any Opti' collection: encrypted in the database, hosted in Europe. They are passed to an AI model only if you yourself start an analysis, a report or a question in the mini chat. |
| Your questionnaires | Handled the same way as Opti' questionnaires. Questionnaires created in Opti' are saved in our secure database and travel over HTTPS. |
| Your field photos | They stay on Kobo. Opti' does not pull them in: it relays them for display, for as long as you are looking at them, because their address requires an authentication your browser cannot supply on its own. |
| Live tracking | If you turn it on, Kobo sends every new answer to an address specific to your project, protected by a random secret. You can turn it off at any time, from either side. |
Revoking access
Two ways, and the second is final.
- From Opti'. The "Disconnect" button in the KoboToolbox panel deletes the stored token. The data you have already imported stays in Opti'.
- From Kobo. Account Settings then Security then Regenerate key invalidates the old token for everyone, Opti' included. Do this if you want to block access to your account, or if you think the token has been compromised.
Remember also to remove the "Opti'" service from the REST Services of your projects if you had turned live tracking on.
Frequently asked questions
What does Opti' see of my KoboToolbox account?
The KoboToolbox API token has no limited scope: it gives access to the whole account, and Kobo offers no alternative. Opti' uses it only for the actions you trigger: listing your projects, sending a questionnaire, downloading the answers of a project you name, displaying a photo. The only action that continues without a move from you is live tracking, which you turn on project by project and can turn off.
Is my API token stored in the clear?
No. It is encrypted at rest with AES-256-GCM, using a key stored separately from the database. It never comes back to your browser: only the last four characters are shown again, so you can recognise which of your tokens is stored. It is never passed to an artificial intelligence service, and never written into our technical logs.
Why does Opti' go through its own servers instead of calling Kobo directly?
It is not a choice. KoboToolbox does not allow calls coming from another website (it sends no CORS header for myoptibot.com), so your browser would be technically unable to do it. There is an upside: the token never has to sit in your browser.
Can I link several Kobo accounts, or my organisation's account?
One connection per person, and one account at a time. This is not an arbitrary limit: a token gives access to the whole Kobo account, so sharing a connection between the members of a Teams project would hand everyone the keys to everyone else's Kobo. Each person connects their own.
Kobo rejected my questionnaire, what should I do?
The message shown comes from pyxform, Kobo's validator, and it is passed on as it stands: it is the only place that tells you which variable name or which choice list is the problem. Fix the point it flags in the questionnaire, then upload again. If the message mentions an invalid node name, the Opti' variable name check will offer the correction automatically on the next attempt.
Is the data in my Kobo projects sent to an artificial intelligence?
Not because of the Kobo connection, which uses no credits and calls no model. Your imported answers become an ordinary collection dataset in Opti': they are passed to a model only if you yourself start an analysis, a report or a question in the mini chat, exactly as with any other dataset.
Does live tracking use credits?
No. Receiving an answer uses no credits, however many there are. Only the analyses you run on that data use any, at the usual Opti Gemba rate.