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

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

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

此包提供了以下模型

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

编写数据处理脚本

Datamap 模型包含一个 process(Submission $submission) 方法。这通过 Datamap 服务类进行挂钩，该类旨在由您重写。每个平台都需要针对收集的数据定制一组不同的数据处理脚本，因此我们尽量使其容易将它们包含到您的平台中。以下是简短版本

创建一个 "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 的 Datamap 条目。对于上面的示例，您将向 datamaps 表添加以下记录
- INSERT INTO datamaps SET id = "testForm", title = "Test Form Processing";

匹配数据映射ID与方法名称至关重要，因为这是数据映射在处理过程中选择运行哪个方法的方式。

发布配置

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

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

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

添加前端

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

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

待办事项：为团队成员添加示例团队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>

osenco / laravel-kobo-link

维护者

详细信息