Web-based codebook generator for ODK / xlsx forms

Hi all! I know I've been spamming the forum the last few weeks, and I promise this is my last one. I've just had a few tools I've put together over the last couple of years for my own workflow. While I recognize that some of these tools may be only useful to me - I thought I'd post them here in the off chance that someone else might find them useful and be able to borrow or copy any example.

It's a codebook generator for ODK.

I create a lot of surveys in ODK, and usually do so by creating the form first in excel, and then uploading to a kobo server or ONA (and now possibly Get ODK). I often, then, later have a need to create a single document with a codebook - especially when handing a dataset over to a different data analyst. I had been using the LINKS Codebook Generator that Nafundi and Task Force created. However, I found that was often insufficient for my needs, and new development seems to have gone dormant since 2013. I wrote ny own R Shiny app for a few reasons:

  • More sophisticated calculations, like pulldata(), broke the LINKS codbook generator (it may have been a function that was added after the generator was supported).
  • Additionally, I wanted a codebook which showed skip patterns and calculations.
  • Finally - it output the codebook into pdf format, which made edits or rearranging more challenging.

Since I always start my XFORMS in Excel, it made sense to simply create an app that would take an xls form and turn it into a single sheet codebook. So, I wrote a few lines of R code and made this!

This is a simple project, but open source. You can find the code for this and other apps here. If you find it useful, you can use the one hosted at figured.io, or copy the code and deploy your own! Currently, this only takes xlsx forms. If you develop your forms in Excel, you can upload it directly here. If you work in kobotoolbox or ONA, you should be able to download your work as an xlsx file and do the same. At some point, I may add support for XForms in XML, but the parser for that will add a considerable level of sophistication that I just don't need or use. If that is of any interest to you, comment on my github or send me a message there.

Known limitations

  • You cannot use a file with multiple languages. Currently, only the label column will be recognized. If you want multiple languages - currently, you'll need to manually upload different versions with just "label".
  • There may be versions of ODK that the current codebook maker will not work for.

Both of these issues should be infrequent, but will be addressed in future versions. Find the source code for this app under a GNU license at https://github.com/jwilliamrozelle/figuredio.


This is a really useful tool that we have sorely missed ever since the LINKS Codebook Generator stopped working for us.

But we always get a 'Failed - Server problem' response from the one hosted at figured.io.

And here is our vote for a multiple language version in the future!

1 Like

yes..same issue on my side. 'Failed - Server problem' response

1 Like

Thanks @marabenta and @aurdipas for reporting the issue!

I appreciate it. I did do some minor upgrades to the server, and it's possible that something could have been affected. I wasn't able to reproduce the problem with my forms, could I bother one or both of you to send me an example of a form you're using to see if I can identify and isolate the issue?


Hi @jwrozelle ,

I think the error is on the instructions on the figured.io website.

"The choices tab must have columns labelled list_type, name, and label."

Normally the first column is list_name and not list_type.
So to test I changed mine to list_type and then it was the error.
I put it back to list_name and now it works.


Oops, thanks for the heads up @aurdipas! I'll update those instructions, and maybe the error handling.

I think in the next week or so, I'll also improve the formatting of the output. Might even make some interactive options for it - but, not sure if it's worth it because excel is already pretty easy to format however you like it.

Anyway - any feedback, feature requests, or criticisms are welcome.

@marabenta, please let me know if this solves your issue, or if there are any other concerns.


That did solve the issue, and now works fine. Many thanks. A really useful tool for those working on external apps and data visualisations.

Now, if you could get multiple languages to work also, then we'd be even happier! :slight_smile:

Thanks for sharing, pretty handy!

Small suggestions for improvement:

  • rows of type note could be removed from the codebook as of no added value (although this can be easily cleaned after the Excel codebook has been generated)
  • when using variables within groups: when exporting submissions from ODK Central, variable names in the database are the concatenation of the name of the group and the name of the variables in the XLSForm. I think it may be helpful to display concatenated names in the codebook since this is what you will use for analysis.

@marabenta and @Thalie, glad you find it useful and thanks for the suggestions! I might add some of your suggestions as optional.

  • I personally have kept notes in because sometimes I use the output for an IRB submission, where notes are included. But can see where their removal might be more efficient for a pure codebook. Would not be too hard to make it optional to include them.
  • I typically also remove group names when exporting data on briefcase or from a platform, but I can absolutely see how that would be useful for some people who export differently.
  • Languages are definitely on the road map.

Thanks again for these suggestions! Keep them coming if anything else comes to mind.

1 Like

@marabenta and @Thalie,

Thanks for your feedback! The next version of the web-app has been released (both on figured.io, and the source code on github if you want to install it on your own shiny-server).

  • option to remove rows of type note
  • option to remove the Question Type column.
  • Multiple language support. I have not tested this with non-latin characters, so not 100% sure it works but I will in the future.

I'll likely add an option for the group name concatenations in the future.


Oh thanks a lot, I will have a look at your new release!