Download the PHP package stephencoduor/laravel-kobo-connect without Composer

Manage KoboToolBox from your Laravel Project

This package turns your Laravel / Laravel Backpack platform into a management system for data collected through KoboToolBox. It is designed to support research or survey data collection, and provides features beyond the scope of what KoboToolBox or other ODK Services can provide on their own.

Who is it for?

Platforms built with this package can help with the following scenarios:

1. Multiple teams need to use the same set of ODK forms provided by a central team, but need to retain ownership of their data (i.e. the data of all teams cannot simply be pooled together and made accessible to everyone)
2. The data collection is complex, where data from some forms needs to be processed and then shared back to other forms as customised CSV files.
   1. Including the possibility that each team requires different data to be made available in their ODK forms.

IMPORTANT NOTE

This is not an off-the-shelf data management solution! It requires you to build your own Laravel platform and pull in this package via composer. It does not handle the processing of the data collected through your ODK forms, but it provides hooks to enable you to write your own processing scripts to run automatically when ODK submissions are pulled in from KoboToolBox. You can provide your own database structures / data models to organise the processed data however you see fit.

Installation

You can install the package via composer:

You can publish and run the migrations with:

Setup Required Configuration Variables

In order to link up to a KoBoToolbox server, you must provide the following environment variables:

The two endpoint variables should be the full url to the server you are using. For example:

The platform requires a 'primary' user account on the KoboToolbox server to manage deployments of ODK forms. This account will own every form published by the platform. We highly recommend creating an account specifically for the Laravel platform. If the platform uses an account also used by others, there is a chance that your database will become out of sync with the forms present on KoBoToolbox, and the form management functions may stop working correctly.

Setup Data Models

This packages assumes that the following models exist in the platform:

• \App\Models\User

To create the database tables required by this package, publish and run the provided migration file:

The package provides the following models:

TODO: add section explaining how the data maps work, and include real examples.

Writing Data Processing Scripts

The Datamap model includes a process(Submission $submission) method. This hooks into a Datamap Service class, which is designed to be overwritten by you. Each platform will require a different set of data processing scripts tailored to the data being collected, so we have tried to make it easy to include these scripts in your platform. Here is the short version:

1. Create a "DatamapService" class, and add the fully qualified path to this class into your .env file. E.g.: DATAMAP_SERVICE_CLASS: "\App\Services\DatamapService::class"
2. Write the methods you want to use to process a submisison. The method should accept a single Submission parameter, and can then do anything you want to 'process' the submission. e.g.:

TODO: include real examples :)

3. Now, you should create a Datamap entry with an ID of the method name. For the example above, you would add the following record to the datamaps table:
   • INSERT INTO datamaps SET id = "testForm", title = "Test Form Processing";

It is vital to match the datamap ID to the method name, as this is how the datamap chooses which method to run during processing.

Publishing The config

If you add the required ENV variables to your application, there should be no need to publish the config file.

However, you may wish to do so anyway. To publish the file, use:

Add the Front-end

This package assumes you are using Laravel Backpack as your admin panel. As such, it comes with a set of CrudControllers for managing your XLS forms and submissions. It also assumes that you are able to build your own front-end to allow team members to access their data, manage forms etc.

You can add links to these crud panels into your sidebar:

TODO: Add example team UI for team members to manage their own forms, submissions and team members/invites.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Dave Mills
• All Contributors

License

The MIT License (MIT). Please see License File for more information.