KoBoToolBox MRZ-Scanner

A bespoke solution for scanning MRZ-coded documents to extract data!

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • Build
3. Usage
4. Example
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

At the DIMA in the UNHCR Asia and Pacific Regional Bureau, we have developed a bespoke KoBo integration that allows data to be extracted from an MRZ-enabled document and imported into KoBo. This automated approach was created to limit the risk of mistakes during a Rapid Assessment conducted in AFG. The objective is to collect the POCs' Name, Family Name, Age, and Gender by automatically reading the data from their national ID cards and saving it in KoBo.

This application configures an Android intent. Intents are messaging objects used to request an action from another app component. Learn more in the Android docs.

Key Features:

• Integrates with KoBoCollect and ODKCollect
• Works 100% offline
• Pulls data from MRZ documents with capability to read other document types as well 😄

This is a template solution, no one KoBo form will serve all projects since your needs may be different (See usage for information on how to adapt this code for a different KoBo form). You may suggest changes by forking this repo and creating a pull request or opening an issue.

Built With

List of all major frameworks/libraries used to develop this project.

• IONIC
• MicroBlink SDK
• Capacitorjs
• Angular
• Node.js

(back to top)

Getting Started

To get a local copy up and running follow these steps.

Prerequisites

Required resources and how to install and build them.

• Download the installer for Node LTS.
• Install the ionic CLI globally

  npm install -g ionic

Installation

Below is the instructions on installing and setting up the scanner app.

1. Get a 30-day MicroBlink SDK trial Key at https://microblink.com/
2. Clone the repo

   git clone https://github.com/nawaaugustine/kobo-mrz.git

3. Install NPM packages from your project root

   npm install

4. Enter your MicroBlink SDK key in ./src/app/scanner/scanner.page.ts

   android: '<your_android_license>';

Build

See the instructions on the usage below before building.

• Run ionic build --prod
• Run npx cap copy
• Run npx cap sync
• Run npx cap open android ensure you already have android studio installed
• Goto your android studio and build the APK
• Enjoy! 🎉

(back to top)

Usage

The below code change is required in other to adabt this template to your KoBo form.

1. Change values in ./src/app/plugins/LauncherActivity.ts. The new values should match exactly your KoBo data name labels

2. Change values assignment in ./src/app/scanner/scanner.page.ts

3. Pass assigned values to main andriod activity in ./android/app/src/main/java/io/nawa/kobo/mrz/LauncherActivity.java

4. Recieve and push values to KoBo in ./android/app/src/main/java/io/nawa/kobo/mrz/MainActivity.java

(back to top)

Example

Example of an external app to populate multiple fields in KoBo

KoBo field-list group can have an intent attribute that allows an external application to populate it.

XLSForm

type	name	label	appearance	body::intent
begin_group	mygroup	Fields to populate	field-list	io.nawa.kobo.mrz
text	Tazkira_no_001	ID Number
text	name	First Name
text	father_name	Family Name
integer	hhh_age	Age
text	hhh_gender	Gender
end_group

Signed APK

Download the signed example APK here. Tested successfully on android version 8+

(back to top)

Roadmap

• Add Changelog
• Make value addition dynamic based on the value passed to the method
• Add a modal to preview scanned data before sending to KoBo?
• Support for data extraction from QRCode/BarCode
• Support for data extraction from other document types
• Remove scanning capability if scanner app is not launched from KoBo
• Multi-language Support?
  • French
  • Spanish
  • Arabic

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Added some Amazing Feature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Augustine Nawa - @nawaaugustine - nawaaugustine@gmail.com

Project Link: https://github.com/nawaaugustine/kobo-mrz

(back to top)

Acknowledgments

Some useful resources

• Launching External Apps
• Intents and Intent Filters

(back to top)