README

This is a community project and not an official Laravel one

ODK CENTRAL-API is a simple wrapper around the ODK Central API that makes working with its endpoints a breeze! To get more informations about the API see https://odkcentral.docs.apiary.io/

Installation

You can install the package via composer:

composer require niranjannsahoo/odkcentralapi

Configuration

Publish the config of the package.

php artisan vendor:publish --provider="Niranjannsahoo\Odkcentralapi\Providers\OdkCentralApiServiceProvider" --tag=config

The following config will be published to config/odkcentralapi.php.

return [

    /*
    |--------------------------------------------------------------------------
    | ODK Central API url
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default url for the API calls.
    | Example : https://private-anon-cecdde38ec-odkcentral.apiary-mock.com/v1
    |
    */
    
    'api_url' => env('ODK_API_URL'),


    /*
    |--------------------------------------------------------------------------
    | ODK Central Authentification
    |--------------------------------------------------------------------------
    |
    | An administrator user of your ODK Central app.
    |
    */

    'user_email' => env('ODK_USER_EMAIL'),

    'user_password' => env('ODK_USER_PASSWORD'),


];

Set the ODK_API_URL, ODK_USER_EMAIL and ODK_USER_PASSWORD of your ODK Central App in your .env file.

ODK_API_URL="https://your_host.com/v1"
ODK_USER_EMAIL=your_email
ODK_USER_PASSWORD=your_password

Don't forget to run php artisan config:clear

If you change your crendentials later you will also have to run php artisan cache:clear. The authentification token is cached for 3600 seconds.

Usage direct one api call

namespace App\Http\Controllers;

use Niranjannsahoo\Odkcentralapi\OdkCentralApi;

class SomeController
{
    public function testOdk()
    {
      $odk = new OdkCentralApi;
      $data=['parameters'=>['projectId'=>2,'name'=>'members']];
      $project = $odk->request('get','projects/{projectId}',$data);
      dd($project);
    }
}

Usage with methods :

namespace App\Http\Controllers;

use Niranjannsahoo\Odkcentralapi\OdkCentralApi;

class SomeController
{
    public function returnFormFields($projectId, $xmlFormId)
    {
      $fields = OdkCentral::projects($projectId)->forms($xmlFormId)->fields()->get();
      dd($fields);
    }
}

Users

Features
✅ User Management

// List all users
$users = $this->odk->user()->listUsers();

// Create a new user
$data = ['params' => ['email' => 'demo@example.org', 'password' => '********']];
$users = $this->odk->user()->create($data);

// Get user details
$data = ['parameters' => ['actorId' => 106]];
$user = $this->odk->user()->details($data);

// Delete a user
$data = ['parameters' => ['actorId' => 106]];
$result = $this->odk->user()->delete($data);

// Modify user
$data = ['parameters'=>['actorId'=>106],'params'=>['email'=>'new@example.org','displayName'=>'New Name']];
$user = $this->odk->user()->modify($data);

// Get current user
$current = $this->odk->user()->current(true);

// Change password
$data=['parameters'=>['actorId'=>106],'params'=>['old'=>'oldPass','new'=>'newPass']];
$result = $this->odk->user()->password($data);

// Initiate password reset
$data=['params'=>['email'=>'demo@example.org'],'query'=>['invalidate'=>true]];
$result = $this->odk->user()->initiate($data);


✅ App Users

// List app users in a project
$data=['parameters'=>['projectId'=>3]];
$users = $this->odk->user()->appuser()->listAppUsers($data);

// Create app user
$data=['parameters'=>['projectId'=>3],'params'=>['displayName'=>'demoappuser']];
$user = $this->odk->user()->appuser()->createAppUser($data);

// Delete app user
$data=['parameters'=>['projectId'=>3,'id'=>1]];
$result = $this->odk->user()->appuser()->deleteAppUser($data);


✅ Roles & Assignments

// List roles
$roles = $this->odk->user()->role()->listRoles();

// Role details
$data=['parameters'=>['id'=>2]];
$role = $this->odk->user()->role()->getRoleDetails($data);

// List all assignments
$assignments = $this->odk->user()->assignment()->listAssignments([],true);

// Assignments by role
$data=['parameters'=>['roleId'=>2]];
$list = $this->odk->user()->assignment()->assignmentsByRole($data);

// Assign role
$data=['parameters'=>['roleId'=>2,'actorId'=>14]];
$result = $this->odk->user()->assignment()->assignRole($data);

// Unassign role
$data=['parameters'=>['roleId'=>2,'actorId'=>14]];
$result = $this->odk->user()->assignment()->unassignRole($data);


✅ Projects

// List projects
$data=['params'=>['forms'=>'true','datasets'=>'true']];
$projects = $this->odk->project()->listProjects($data,true);

// Create project
$data=['params'=>['name'=>'Test Project']];
$project = $this->odk->project()->createProject($data);

// Project details
$data=['parameters'=>['id'=>22],'headers'=>['X-Extended-Metadata'=>'true']];
$project = $this->odk->project()->getProjectDetails($data);

// Update project
$data=['parameters'=>['id'=>22],'params'=>['name'=>'New Project','description'=>'Desc']];
$result = $this->odk->project()->updateProject($data);

// Update with forms + assignments
$data=['parameters'=>['id'=>22],'params'=>['name'=>'New Project Name','forms'=>[/*...*/]]];
$result = $this->odk->project()->updateProjectDetails($data);

// Delete project
$data=['parameters'=>['id'=>22]];
$result = $this->odk->project()->deleteProject($data);

// Enable encryption
$data=['parameters'=>['id'=>22],'params'=>['passphrase'=>'secret','hint'=>'my key']];
$result = $this->odk->project()->enableEncryption($data);

// List project assignments
$data=['parameters'=>['projectId'=>3]];
$assignments = $this->odk->project()->assignment()->listAssignments($data);

// Assign actor to form
$data=['parameters'=>['projectId'=>3,'xmlFormId'=>'formId','actorId'=>14]];
$result = $this->odk->project()->assignment()->assignActor($data);


✅ Forms

// List forms
$data=['parameters'=>['projectId'=>2],'params'=>['deleted'=>'true']];
$forms = $this->odk->form()->listForms($data,true);

// Upload new form
$data=['parameters'=>['projectId'=>2],'query'=>['ignoreWarnings'=>'false','publish'=>'false']];
$file = public_path('form.xlsx');
$form = $this->odk->form()->createForm($data, $file);

// Form details
$data=['parameters'=>['projectId'=>2,'xmlFormId'=>'household']];
$form = $this->odk->form()->details($data);


✅ OData

// Form OData service
$data=['parameters'=>['projectId'=>3,'xmlFormId'=>'fieldvisit_wassan']];
$service = $this->odk->odata()->formservice($data);

// Form submissions
$data=['parameters'=>['projectId'=>3,'xmlFormId'=>'fieldvisit_wassan','table'=>'Submissions'],'params'=>['$top'=>2]];
$data = $this->odk->odata()->formdata($data);

// Form metadata
$data=['parameters'=>['projectId'=>3,'xmlFormId'=>'fieldvisit_wassan']];
$meta = $this->odk->odata()->formmetadata($data);

// Download submission file
$data=['parameters'=>['projectId'=>3,'xmlFormId'=>'form','instanceId'=>'uuid:123','filename'=>'photo.jpg']];
$file = $this->odk->odata()->download($data);

// Dataset service
$data=['parameters'=>['projectId'=>3,'datasetName'=>'blocks']];
$ds = $this->odk->odata()->datasetservice($data);

// Dataset metadata
$data=['parameters'=>['projectId'=>3,'datasetName'=>'blocks']];
$meta = $this->odk->odata()->datasetmetadata($data);

// Dataset data
$data=['parameters'=>['projectId'=>3,'datasetName'=>'blocks'],'params'=>['$top'=>2]];
$data = $this->odk->odata()->datasetdata($data);

// Draft service
$data=['parameters'=>['projectId'=>2,'xmlFormId'=>'fieldvisit']];
$draft = $this->odk->odata()->draftservice($data);

// Draft metadata
$data=['parameters'=>['projectId'=>2,'xmlFormId'=>'fieldvisit']];
$draft = $this->odk->odata()->draftmetadata($data);

// Draft submissions
$data=['parameters'=>['projectId'=>2,'xmlFormId'=>'fieldvisit','table'=>'Submissions'],'params'=>['$top'=>2]];
$draft = $this->odk->odata()->draftdata($data);


### Testing

```bash
composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Niranjan Sahoo
• All Contributors

License

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

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.