README

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

它是为谁准备的？

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

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

重要注意事项

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

安装

您可以通过composer安装此包

composer require stats4sd/laravel-kobo-link

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

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

此包提供以下模型

待办事项：添加解释数据映射如何工作的部分，并包括真实示例。

发布配置

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

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

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

添加前端

此包假定您正在使用Laravel Backpack作为您的管理面板。因此，它提供了一套用于管理您的XLS表单和提交的CrudControllers。它还假定您能够构建自己的前端，以允许团队成员访问他们的数据，管理表单等。

您可以将这些crud面板的链接添加到位于resourcs\views\vendor\backpack\base\inc\sidebar_content.blade.php的侧边栏文件中

待办事项：添加示例团队UI，以便团队成员可以管理他们自己的表单、提交和团队成员/邀请。

<li class='nav-item'><a class='nav-link' href='{{ backpack_url('team') }}'><i class="lab la-wpforms nav-icon"></i> Teams</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('submission') }}'><i class="lab la-wpforms nav-icon"></i> Submissions</a></li>

编写数据处理脚本

数据映射模型包含一个 process(Submission $submission) 方法。这个方法连接到数据映射服务类，该类设计为可以由您重写。每个平台都需要一组针对收集的数据定制的数据处理脚本，因此我们已尽量使其容易将脚本包含到您的平台中。以下是简要说明：

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

    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();       
    }

TODO：包括真实示例 :)

现在，您应该创建一个具有方法名称 ID 的数据映射条目。对于上面的例子，您应该将以下记录添加到 datamaps 表中
- INSERT INTO datamaps SET id = "testForm", title = "Test Form Processing";

匹配数据映射 ID 和方法名称至关重要，因为这决定了数据映射在处理期间运行哪个方法。

stats4sd / laravel-kobo-link

维护者

详细信息