README

此包可以将您的Laravel/Laravel Backpack平台转变为通过KoboToolBox收集的数据的管理系统。它旨在支持研究或调查数据收集，并提供KoboToolBox或其他ODK服务本身所不能提供的功能。

适用于谁？

使用此包构建的平台可以帮助以下场景

多个团队需要使用由中央团队提供的一套相同的ODK表单，但需要保留数据所有权（即，所有团队的数据不能简单地合并在一起并供所有人访问）
数据收集复杂，某些表单的数据需要经过处理后再以自定义CSV文件的形式与其他表单共享。
1. 包括每个团队需要在其ODK表单中提供不同数据的情况。

重要注意事项

这不是一个现成的数据管理解决方案！它需要您构建自己的Laravel平台，并通过composer引入此包。它不处理通过您的ODK表单收集的数据的处理，但它提供了钩子，以便您编写自己的处理脚本来在从KoboToolBox拉取ODK提交时自动运行。您可以根据自己的喜好提供数据库结构/数据模型来组织处理后的数据。

安装

您可以通过composer安装此包

composer require stephencoduor/laravel-kobo-connect

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --provider="Stats4sd\KoboLink\KoboLinkServiceProvider" --tag="kobo-link-migrations"
php artisan migrate

设置所需的配置变量

为了链接到KoBoToolbox服务器，您必须提供以下环境变量

KOBO_ENDPOINT=
KOBO_OLD_ENDPOINT=
KOBO_USERNAME=
KOBO_PASSWORD=
DATA_PROCESSING_CLASS=

这两个端点变量应该是您使用的服务器的完整URL。例如

## If you use the 'for everyone else' server provided by the team at https://kobotoolbox.org:
KOBO_ENDPOINT=https://kf.kobotoolbox.org,
KOBO_OLD_ENDPOINT=https://kc.kobotoolbox.org

## If you use their humanitarian server, use:
KOBO_ENDPOINT=https://kobo.humanitarianresponse.info
KOBO_OLD_ENDPOINT=https://kc.humanitarianresponse.info

平台需要KoboToolbox服务器上的一个“主”用户帐户来管理ODK表单的部署。此帐户将拥有平台发布的每个表单。我们强烈建议为Laravel平台创建一个专门的用户帐户。如果平台使用其他人也使用的帐户，则您的数据库可能会与KoBoToolbox上现有的表单不同步，并且表单管理功能可能无法正确工作。

设置数据模型

此包假设平台中存在以下模型

\App\Models\User

为了创建此包所需的数据库表，发布并运行提供的迁移文件

php artisan vendor:publish --provider="Stats4sd\KoboLink\KoboLinkServiceProvider" --tag="kobo-link-migrations" 
php artisan migrate

此包提供以下模型

待办事项：添加解释数据映射工作方式的章节，并包括真实示例。

编写数据处理脚本

数据映射模型包含一个process(Submission $submission)方法。此方法连接到数据映射服务类，该类旨在由您覆盖。每个平台都需要一套不同的数据处理脚本，以适应收集的数据，因此我们尽量使这些脚本易于包含在您的平台中。以下是一个简短的版本

创建一个“DatamapService”类，并将此类的完全限定路径添加到您的.env文件中。例如：DATAMAP_SERVICE_CLASS: "\App\Services\DatamapService::class"
编写您想要用于处理提交的方法。该方法应接受单个提交参数，然后可以执行任何您想要对提交进行“处理”的操作。例如。

    public function testForm(Stats4sd\KoboLink\Models\Submission $submission)
    {
        /* PROCESS SUBMISSION DATA */
        
        /* get the submission contents */ 
        $data = $submission->content;

        // the Datamap model includes a helper function to remove the lengthy group names from the submission:        
        $data = $this->removeGroupNames($data);
        
        /** Now $data is a set of key-value pairs that can be processed however you need, including :
         * - creating new database entries via Eloquent, 
         * - manual SQL querying, 
         * - passing the submission to an external process like R or Python running on the server.
         *
         * Repeat groups need to be handled manually - they will be left with the 'value' as a nested json array.  
        **/    
        
        /* At the end, you should update the $submission entry: */
        $submission->processed = 1;
        
        /* If your processing throws errors, e.g. validation errors, you can add those to the "errors" array: */ 
        $submission->errors = [
            'variable_name' => 'Error message',
            'variable_2' => 'Error message',
        ];
        
        /** If your processing has created new Eloquent models, you can add those to the "entries" array.
         * - This allows you to easily identify what records each submission created;
         * - It is used in the 'reprocessSubmissions()' method to delete previously created entries and avoid duplication. 
         **/
          
        // example, if your submission created 1 Household entry and 2 HouseholdMember entries:
        $submission->entries = [
            "App\Models\Household" => [$household->id],
            "App\Models\HouseholdMember" => [$memberOne->id, $memberTwo->id], 
       ];

        $submission->save();       
    }

待办事项：包括真实示例 :)

现在，您应该创建一个ID为方法名的数据映射条目。在上面的示例中，您将添加以下记录到datamaps表
- 向datamaps表中插入数据：SET id = "testForm", title = "Test Form Processing";

匹配datamap ID与方法名称至关重要，因为这决定了datamap在处理过程中选择运行哪个方法。

发布配置

如果您已将所需的ENV变量添加到您的应用程序中，则不需要发布配置文件。

然而，您可能仍然希望这样做。要发布文件，请使用

php artisan vendor:publish --provider="Stats4sd\KoboLink\KoboLinkServiceProvider" --tag="kobo-link-config"

添加前端

此包假设您正在使用Laravel Backpack作为您的管理面板。因此，它附带了一组用于管理您的XLS表格和提交的CrudControllers。它还假设您能够构建自己的前端，以便团队成员可以访问他们的数据，管理表格等。

您可以将这些crud面板的链接添加到侧边栏

TODO：添加示例团队UI，以便团队成员可以管理他们自己的表格、提交以及团队成员/邀请。

<li class='nav-item'><a class='nav-link' href='{{ backpack_url('team') }}'><i class="lab la-wpforms nav-icon"></i> XLSForms</a></li>

<li class='nav-item'><a class='nav-link' href='{{ backpack_url('xlsform') }}'><i class="lab la-wpforms nav-icon"></i> XLSForms</a></li>
<li class='nav-item'><a class='nav-link' href='{{ backpack_url('submissions') }}'><i class="lab la-wpforms nav-icon"></i> Submissions</a></li>

stephencoduor / laravel-kobo-connect

维护者

详情