mchev/laravel-odk

Laravel-ODK is a simple wrapper around the ODK Central API that makes working with its endpoints a breeze!

Laravel ODK

This is a community project and not an official Laravel one

Laravel-ODK 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 mchev/laravel-odk

Configuration

Publish the config of the package.

php artisan vendor:publish --provider="Mchev\LaravelOdk\Providers\OdkCentralServiceProvider" --tag=config

The following config will be published to config/odkcentral.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

namespace App\Http\Controllers;

use Mchev\LaravelOdk\OdkCentral;

class SomeController
{
    public function testOdk()
    {
      $odk = new OdkCentral;
      $project = $odk->projects(1)->get();
      dd($project);
    }
}

Usage with Facade :

namespace App\Http\Controllers;

use Mchev\LaravelOdk\Facades\OdkCentral;

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

Users

// Get all users.
$users = $odk->users()->get();

// Searching users
$users = $odk->users('Jane')->get();

// You can also use eloquent 💥
$users = $odk->users()->get()->sortBy('displayName');

// Creating a new user.
$user = $odk->users()->create([
  'email' => '[email protected]',
  'password' => 'password' // Optional (That email address will receive a message instructing the new user on how to claim their new account and set a password.)
]);

// Getting User details
$user = $odk->users($userId)->get();

// Getting authenticated User details
$user = $odk->users()->current();

// Modifying a User
$user = $odk->users($userId)->update([
  'displayName' => 'New name', // string
  'email' => '[email protected]' // string
]);

// Directly updating a user password
$user = $odk->users($userId)->updatePassword([
  'old' => 'old.password', // string
  'new' => 'new.password' // string
]);

// Initiating a password reset
$user = $odk->users()->passwordReset($userEmail);

// Deleting a User
$user = $odk->users($userId)->delete();

App Users

// Listing all App Users.
$appUsers = $odk->projects($projectId)->appUsers()->get();

// Creating a new App User.
$appUser = $odk->projects($projectId)->appUsers()->create([
  'displayName' => 'Jane Doe'
]);

// Deleting a App User
$appUser = $odk->projects($projectId)->appUsers($appUserId)->delete();

Projects

// Get a list of projects.
$projects = $odk->projects()->get();

// Creating a Project.
$project = $odk->projects()->create([
  'name' => 'My new project'
]);

// Getting Project details
$project = $odk->projects($projectId)->get();

// Updating Project Details
$project = $odk->projects($projectId)->update([
  'name' => 'New name', // string | required
  'archived' => false // boolean | optional
]);

// Deep Updating Project and Form Details
$project = $odk->projects($projectId)->deepUpdate([
  'name' => 'New name', // string | required
  'archived' => false, // boolean | optional
  'forms' => [
    {
      "xmlFormId": "simple",
      "state": "open",
      "assignments": [
        {
          "roleId": 2,
          "actorId": 14
        }
      ]
    }
  ], // array | infos : https://odkcentral.docs.apiary.io/#reference/project-management/projects/deep-updating-project-and-form-details
]);

// Enabling Project Managed Encryption
$project = $odk->projects($projectId)->encrypt([
  'passphrase' => 'Super duper secret', // string | required
  'hint' => 'My reminder' // string | optional
]);

// Deleting a Project
$project = $odk->projects($projectId)->delete();

Forms

// List all forms of a project.
$forms = $odk->projects($projectId)->forms()->get();

// Creating new form (sending XForms XML or XLSForm file)
// If the second parameter is set to false, the form will be stored as draft.
$form = $odk->projects($projectId)->forms()->create($request->file('your_input_file'), true);

// Getting form details
$form = $odk->projects($projectId)->forms($xmlFormId)->get();

// Getting form schema fields
$form = $odk->projects($projectId)->forms($xmlFormId)->fields()->get();
// You may optionally add the 'true' parameter to the fields() method to sanitize the field names and paths to match the way they will be outputted for OData

// Listing form attachments
$form = $odk->projects($projectId)->forms($xmlFormId)->attachments()->get();

// Downloading a form attachment
return $odk->projects($projectId)->forms($xmlFormId)->downloadAttachment($filename);

// Modifying a form
$form = $odk->projects($projectId)->forms($xmlFormId)->update([
  'state' => 'open'
]);

// Deleting a form
$form = $odk->projects($projectId)->forms($xmlFormId)->delete();

// Download form file (xml, xls, xlsx)
return $odk->projects($projectId)->forms($xmlFormId)->xlsx()->download(); // xml(), xls(), xlsx()

Draft

// Let's say we already have our form
$form = $odk->projects($projectId)->forms($xmlFormId);

// Create a new draft
$form->draft()->create($request->file('your_input_file'));

// Getting Draft Form Details
$form->draft()->get();

// Getting Draft Form Fields
$form->draft()->fields();

// Publish the draft
$form->draft()->publish('v1.2.0'); // string | optional

// Deleting the draft
$form->draft()->delete();

Submissions

// Listing all submissions on a form
$submissions = $odk->projects($projectId)->forms($xmlFormId)->submissions()->get();

// Getting Submission metadata
$submissions = $odk->projects($projectId)->forms($xmlFormId)->submissions($instanceId)->get();

// Updating Submission metadata
$submissions = $odk->projects($projectId)->forms($xmlFormId)->submissions($instanceId)->update([
  'reviewState' => 'approved' // null, edited, hasIssues, rejected, approved | enum
]);

// Retrieving Submission XML
$submissions = $odk->projects($projectId)->forms($xmlFormId)->submissions($instanceId)->xml();

// Geting Submission comments
$submissions = $odk->projects($projectId)->forms($xmlFormId)->submissions($instanceId)->comments()->get();

// Posting Submission comments
$submission = $odk->projects($projectId)->forms($xmlFormId)->submissions($instanceId)->comments()->create([
  'body' => 'this is the text of my comment',
]);

Answers/Responses

// Our form
$form = $odk->projects($projectId)->forms($xmlFormId);

// You can get answers directly :
$answers = $form()->answers();
// OR
$anwserWithRepeats = $form()->answersWithRepeats();

// If you need to get only answers associated to a submission :
$answers = $form()->submissions($submissionId)->answers();
// OR
$anwserWithRepeats = $form()->submissions($submissionId)->answersWithRepeats();

// answersWithRepeats() method accept a boolean parameter to only get the questions and responses (no meta, ids, etc)
$onlyAnswers = $form()->submissions($submissionId)->answersWithRepeats(true);

Odata

// Our form
$form = $odk->projects($projectId)->forms($xmlFormId);

/**
 * OData request.
 *
 * @param string $url
 * @param boolean $top
 * @param boolean $skip
 * @param boolean $count
 * @param boolean $wkt
 * @param string $filter
 * @param boolean $expand
 */
$data = $form->odata($url= '', $top = false, $skip = false, $count = false, $wkt = false, $filter = '', $expand = false)->get();

// Example : 
$submissions = $form->odata('Submissions')->get();

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Martin Chevignard
• 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.

laravel-odk's Issues

Fields schema

I tired to get fields definitions like this :
$form = $odk->projects($projectId)->forms($xmlFormId)->fields()->get();
but its gives this error : 'Too few arguments to function Illuminate\Support\Collection::get(), 0 passed in'

API login successful even with wrong account credentials

Hi,

I configured the package and called Central API for test queries successfully. Just for testing, I changed the username/password in .env file to a wrong combination (not present on central), but somehow the API is still picking up data from Central and bringing to Laravel. I assume perhaps it is holding the API authentication token for some longer time? Or is it some bug?

Thanks,
Saad

error while using odata function

Trying to use the odata function

// Our form
$form = OdkCentral::projects($projectId)->forms($xmlFormId);

/**
 * OData request.
 *
 * @param string $url
 * @param boolean $top
 * @param boolean $skip
 * @param boolean $count
 * @param boolean $wkt
 * @param string $filter
 * @param boolean $expand
 */
$data = $form->odata($url= '', $top = false, $skip = false, $count = false, $wkt = false, $filter = '', $expand = false)->get();

// Example : 
$submissions = $form->odata('Submission')->get();

The following error message is being displayed

Error
Call to undefined method Mchev\LaravelOdk\OdkCentral::odata()

Installation failing

Hi,

I am trying to install the package on Laravel v9.10, but failing in the first step, with following error:

Using version ^1.2 for mchev/laravel-odk
./composer.json has been updated
Running composer update mchev/laravel-odk
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires mchev/laravel-odk ^1.2 -> satisfiable by mchev/laravel-odk[v1.2.0, v1.2.1, v1.2.2, v1.2.3].
    - mchev/laravel-odk[v1.2.0, ..., v1.2.3] require illuminate/support ^8.0 ->found illuminate/support[v8.0.0, ..., 8.x-dev] but these were not loaded, likely because it conflicts with another require.

You can also try re-running composer require with an explicit version constraint, e.g. "composer require mchev/laravel-odk:*" to figure out if any version is installable, or "composer require mchev/laravel-odk:^2.1" if you know which you need.

Installation failed, reverting ./composer.json and ./composer.lock to their original content.

Can you please suggest the workaround? Thanks!
Saad

unable to view and edit submissions using the APIs

I have tried using $submissions = OdkCentral::projects($projectId)->forms($formId)->submissions()->get();

but this just returns the metadata. Unable to retrieve the submission to view on the blade/laravel view.

Also, tried using the $submissionsmeta = OdkCentral::projects($projectId)->forms($xmlFormId)->submissions($instanceId)->xml();
This only returns a token.

Mchev\LaravelOdk\OdkCentralRequest {#1459 ▼
  +api_url: "https://my-odk-central-domain.odk/v1"
  -response: null
  -token: "e275L5b!A7aaaaaaaaaaaaj5GPXcQV9Dpww"

}
But unable to download or edit the submissions/ responses.

Please help & guide.

Error exception while using OdkCentral::projects

While trying "$submissions = OdkCentral::projects($projectId)->forms($xmlFormId)->submissions()->get();"

Receiving the below error message:

ErrorException
Non-static method Mchev\LaravelOdk\OdkCentral::projects() should not be called statically (View: D:\xampp\htdocs\laravel\resources\views\pages\dashboard.blade.php)

However, $projects = $odk->projects()->get(); this works fine.

Error while using the $submissions = $odk->projects($projectId)->forms($xmlFormId)->submissions()->get();

ErrorException
htmlspecialchars() expects parameter 1 to be string, object given (View: D:\xampp\htdocs\laravel\resources\views\pages\dashboard.blade.php)

I'm trying to display or view submissions data on the screen.

Error in Update Answers

Trying to update the answers using the following

$answers = OdkCentral::projects($projectId)->forms($xmlFormId)->submissions($submissionId)->answers()->update([
  'HeadOfHouseholdName' => 'Test Update'  // this is as per my demo ODK form
]);

But, this work like a charm for the status

// Updating Submission metadata
$submissions = OdkCentral::projects($projectId)->forms($xmlFormId)->submissions($instanceId)->update([
  'reviewState' => 'approved' // null, edited, hasIssues, rejected, approved | enum
]);