Manifold's KoBo server dataport connects to free KoBo Toolbox web servers using our KoBo account's API key to automatically authenticate our connection to our KoBo projects on the server, with automatic linking of data from those servers as tables and drawings in our Manifold project. The same dataport can connect to KoBo Toolbox servers our organization may be operating, using the credentials our organizations specifies.
We can link data from KoBo servers into Manifold by creating a new data source of type Web Server: kobo using the File - Create - New Data Source command. Creating a KoBo data source leaves the data on the KoBo server and links a read-only drawing and table into the project. If we like, we can Copy the linked table and drawing from the data source and Paste them into the main part of our project, to create a local copy of the data within our project.
See the Example: Connect to Data Collected in the Field topic for a step by step example creating a KoBo server data source and using the drawing it links into the Manifold project.
Choose File - Create - New Data Source in the main menu, or right-click in the Project pane and choose New Data Source.
In the dropdown menu choose More... to launch the New Data Source dialog.
Enter a Name, if a name other than "Data Source" is desired.
Choose Web Server: kobo in the Type box.
Choose the KoBo server being used.
Enter the API key for your KoBo account in the API key box.
Default settings for other options will usually work. Press Create Data Source.
A new data source appears in the project. Open it to see the data in your KoBo account's projects.
It makes sense to save our KoBo data source as a Favorite Data Source for one-click connections in the future, with no need to look up our API key. Favorite data sources are remembered on that machine even after we close the project and then launch Manifold with new projects in the future.
Drawings and tables that are linked from KoBo servers are neither selectable or editable, and then cannot be styled. However, we can Copy a drawing in the data source and then Paste it into the main part of the drawing. The drawing copy will then be selectable and we can style it.
In the main menu, choose File - Create - New Data Source. The dropdown menu provides a list of favorites to choose from as well as a More... option.
Choose More... to launch the New Data Source dialog. Choose Web Server: kobo in the Type box.
Enter the API key for the KoBo Toolbox account that will be used, and then press Create Data Source.
Name |
Name for the new data source, "Data Source" by default. Specify a more memorable name as desired. If we forget the origin of a data source we can hover the mouse over the data source name in the Project pane and a tool tip will provide connection information. |
Type |
Choose Web Server: kobo in the Type box to connect to a KoBo server over the web. That enables a box which allows choice of the server account type which the KoBoToolbox account uses.
|
Source |
A connection string to the KoBo server. Choosing Web Server: kobo automatically loads the default KoBo Toolbox URL. If we are using a KoBo server hosted on a different machine, we can enter the URL to use. The connection string can also be entered using the Web Login dialog launched by the [...] browse button. |
|
Click to launch the Web Login dialog, to allow use of a login and password plus use of a proxy server if desired. The Web Login dialog is also handy for providing a Test button that can be used to test the connection. |
Open as read-only |
Open the data source read-only. Has no effect with KoBo servers since they are read-only in any event. |
Cache data |
Cache data downloaded from the server while the project is open. Provides better interactive performance and greater flexibility with read-only data sources. Checked by default. Leave this box checked. |
Save cached data between sessions |
Save the cached data for the next time this project is opened, within the .map project itself in a Cache sub-folder in the System Data hierarchy. Caution: checking this box can result in larger .map files when the results of browsing very large data from web servers are all saved. However, having such data cached in the .map is handy for offline browsing of the project. |
API key |
Enter the API key for the KoBo Toolbox account that is to be used. |
Create Data Source |
Create the new data source in the project pane and close the dialog. |
Edit Query |
Launch the Command Window loaded with a query that creates the data source using the given settings. A great way to learn how to use SQL to create data sources. |
Cancel |
Exit the dialog without doing anything. |
Pressing
the browse button next to the Source
box launches the Web
Login dialog, to specify a server
and connection characteristics.
Server |
The connection string for the server. The default URL for KoBo Toolbox is loaded when we choose Web Server: kobo and the account type in the New Data Source dialog. We can change this to whatever URL is right for the KoBo server we are using, for example, if our organization is operating its own KoBo server. |
Use login and password |
Check this box for servers that require logging in with a login name and a password, providing the required name and password in the Login and Password boxes. |
Use proxy server |
Check this box when connecting through a proxy server. The Proxy, Login, and Password boxes allow specifying the connection string to the proxy server as well as the login name and password required to use the proxy server. |
User agent |
Identifies what application (Manifold) is asking for a connection. Some web servers want to know what client software is connecting, for compatibility or for business reasons. The default string optimizes compatibility (Mozilla is very generic) while also identifying Manifold Release 9 as the client. Users can adjust the string as necessary to comply with any special server requirements. |
API key |
When using KoBo Toolbox organization servers, provide the API key for the KoBo Toolbox account we want to use. If we provide the API key we do not need to provide login or password credentials. |
Application key |
A secondary application key or authentication code for those servers that may require it. Not used with KoBo servers. |
Timeout |
Specify a time in milliseconds to wait for connecting to the specified server. Use 0 for the default timeout, or specify whatever is the desired time to wait before giving up on the server. |
Test |
Press the Test button to try the connection using the specified parameters. If successful, a Connection established information dialog will pop open. |
The KoBo dataport automatically refreshes opened KoBoToolbox tables every five minutes. Automatic refreshes capture any change that advances the table version published within KoBoToolbox. Table versions do not advance for absolutely all types of changes to the underlying data, but they do advance for the most common type of changes, such as adding new records, as well as for many of the less common types, such as adding or deleting fields.
What does KoBo mean and how is it pronounced? Kobo means transfer in the Acholi language spoken by the Acholi people in northern Uganda. The "o" is pronounced the same as the "o" in hello. The KoBo Toolbox organization capitalizes the "b" in kobo, so Manifold does that as well when referring to the organization or brand, with lower case "b" used otherwise.
What is Enketo? ODK technology uses the Xform standard, which has been part of the W3C web specification for a long time. However, none of the popular browsers include built-in support for Xform. They rely instead on form engines, like Enketo, to process Xforms that define survey forms. Enketo is hugely popular in both commercial and non-profit apps.
Enketo Core is a library that contains Enketo's form engine. It is not an app by itself but a minimal building block that can be used to create Enketo-powered apps. Enketo Express is one of the apps that is powered by Enketo Core.
Esri uses Enketo Core as the form engine that powers Esri's Survey123 for ArcGIS web application. Esri was a sponsor of Enketo's libraries and paid for some features and improvements in the past. Enketo Express is an integral part of KoBoToolbox and KoBo has historically sponsored a large chunk of Enketo Express' development. It still provides code, feedback, emotional support, and funding for features and bug fixes.
What does Enketo mean and how is it pronounced? According to enketo.org: "Enketo means survey in Esperanto. We are not sure how to properly pronounce it in Esperanto but you could say [\in-ˈke-tō]. The first "e" and second "e" should be pronounced the same because each letter has only one pronounciation in Esperanto." Roger that. Enketo is a cool thing however you pronounce it.
Problems connecting - Check the Log Window to see what is going on behind the scenes if an attempted connection does not work. The problem is usually a wrong connection string or URL, failure to provide required credentials such as an key string that authorizes access, wrong choice of protocol (the server uses WMS and the user picks something else), the server is not a FeatureServer or ImageServer or Mapserver, an incredibly slow server, a server that is offline or a server that is wrongly configured and which is not correctly using the protocol it claims to use.
Visit the Manifold community forum and talk out difficulties with other users. Make sure to post full information on what you are doing, the connection URL you used, all details of how you tried to connect (including all settings in the data source dialog), what happened, and what the Log Window reported. If other users cannot help you, spending a tech support incident will produce an authoritative analysis of the issue.
Try the URL in a browser - Checking the URL by launching it in a browser can reveal many problems with the URL or with the web server. If a URL does not work in a Manifold web server dataport, try exactly the same URL in a browser. If a browser cannot connect to the URL, the Manifold web server dataport will not be able to connect to it either. If a browser cannot connect to that URL, that indicates the problem is the URL or the web server. For example, the web server might be offline. Or, for example, If the browser connects to a page other than the actual web service endpoint, such as, to a web page that lists various options for web servers, that shows the URL is not a URL for a web server but a URL to some other sort of web page.
Connection problems are often caused by incorrect URLs. There might be a typographical error in the URL or the URL might not be an endpoint to a functioning server but instead a URL to some other web page. The server responding to the URL may have geographic restrictions (surprisingly common) that does not respond to connections from IP addresses that are thought to be in a canceled country. Trying the URL in a browser will fail in such cases. Web servers may also have other restrictions, such as only allowing connections from white listed IP addresses, from paying clients, or from those clients that use a special security scheme.
10 Minute Tutorial - Create and Use a Survey Form - The first of two videos showing how to collect data in the field with Manifold Release 9. We create a new survey form using the KoBoToolbox ecosystem, the same ODK/Enketo based technology used by Esri's Survey123. We create a form to collect information and locations for restaurants in Chartres, France. We use the form to capture data for a restaurant, automatically syncing collected data into our Kobo server. The next video shows how to connect Manifold and automatically harvest collected data.
10 Minute Tutorial - Connect to Data Collected in the Field - The second of two videos showing how to collect data in the field with Manifold Release 9. The first video showed how to create a survey form and to use that to acquire data for restaurant locations. This video shows how easy it is to form a live connection to the KoBo server storing our survey data, automatically linking tables and drawings into our Manifold project. We create a map of restaurants surveyd in Chartres, France, using a satellite layer for background. We add labels and see how when we add more data using mobile or other devices, we can refresh to automatically capture those new locations in the Manifold map. Works in the free Manifold Viewer, too!
File - Create - New Data Source
Example: Create and Use a Survey Form - Create a new survey form on the KoBo Toolbox site, and then modify the form to provide a starting view for map widgets used to collect locations. Use the form to collect data in the field, automatically syncing collected data into our KoBo account on the KoBo servers.
Example: Connect to Data Collected in the Field - Use the Web Server: kobo dataport to connect to KoBo servers, using our KoBo account's API key to automatically authenticate our connection to our KoBo projects on the server, with automatic linking of data from those servers as tables and drawings in our Manifold project. Use KoBo data to create a map of restaurants we have surveyed in Chartres, France. Add new data and refresh to see new locations appear in our Manifold map.