# django-odk
Django data collection tool using [ODK-collect](https://play.google.com/store/apps/details?id=org.odk.collect.android&hl=en_US&gl=US) mobile app.
## Prerequisite
- Django web site up and running
- Smartphone or tablet with [ODK-Collect installed](https://play.google.com/store/apps/details?id=org.odk.collect.android&hl=en_US&gl=US)
- [XLSForm](https://xlsform.org/en/) file with 3 tabs 'survey', 'choices', 'settings'
NEW from version 1.0.2 (xls2xml & create final model)
- Since most of Xforms are using `geopoint`, the database must be set up **with vector geodatabase functionality**: PostGIS, Oracle Spatial, SQLite/SpatiaLite
- **Java Runtime Environment (JRE)** installed `$ sudo apt install default-jre` for XForm validation used by [xlsconv](https://github.com/wq/xlsform-converter)
## Installation
* Run
```bash
$ pip install django-odk
$ python manage.py migrate
$ python manage.py createsuperuser
```
* Add odk and odkdata to your INSTALLED_APPS settings
```py
INSTALLED_APPS = (
...
'odk',
'odkdata',
)
```
* Add LOCALE_PATHS and appropriate language_code in settings
```py
LOCALE_PATHS = [os.path.join(BASE_DIR, 'odk', 'locale')]
LANGUAGE_CODE = 'en'
# translated LANGUAGE_CODE: fr
```
* Add appropriate AUTH_USER_MODEL in settings.py
```py
AUTH_USER_MODEL = 'auth.user'
```
* For a more interactive app, configure **logging** as explained in [Lincoln Loop](https://lincolnloop.com/blog/django-logging-right-way/) and **messages** as explained in [Django](https://docs.djangoproject.com/en/4.0/ref/contrib/messages/)
* For **logging**, add `odk` and `odkdata` entry to `loggers` key of your logging file and adapt `handlers` according to yours.
```py
'loggers': {
...
'odk': {
'handlers': ['console', 'debugger', 'warning', 'error'],
'level': 'DEBUG' if DEBUG else 'INFO',
'propagate': False,
},
'odkdata': {
'handlers': ['console', 'debugger', 'warning', 'error'],
'level': 'DEBUG' if DEBUG else 'INFO',
'propagate': False,
},
}
```
* Add **is_odk_admin** and **is_odk_user** property to your AUTH_USER_MODEL (django.contrib.auth.models file or specific accounts.models)
```py
@property
def is_odk_admin(self):
return self.groups.filter(name='odk-admin').exists()
@property
def is_odk_user(self):
return self.groups.filter(name='odk-user').exists()
```
* Add odk.urls to the main urls.py file:
```py
urlpatterns = [
...
path('odk/', include('odk.urls'), name='odk'),
]
```
* Add menu or buttons to access **Available form**
```py
# bootstrap5 menu item example
<li><a class="dropdown-item" href="{% url 'odk:xform_list' %}">{% trans "ODK available forms" %}</a></li>
```
* Add menu or buttons to access **Submitted form**
```py
# bootstrap5 menu item example
<li><a class="dropdown-item" href="{% url 'odk:xformsubmit_list' %}">{% trans "ODK submitted forms" %}</a></li>
```
## Connect to the Django admin site
* create a group 'odk-admin' with create, read, update access on odk objects
* Associate this group to the appropriate users
## Available form: Build, Upload, Convert, Create
Connect to django-odk => **Available form** => Add and follow 4 steps:
1. **Build** an XLSForm file with 3 tabs 'survey', 'choices', 'settings' [Cfr documentation](https://docs.getodk.org/xlsform/). Do not forget to add 'today' & 'username' fields in Survey tab!
2. **Upload** xlsx file (XForm) by clicking on 'Choose file' and Save
3. **Convert** xlsx file to xml XForm compatible file [Thanks pyxform!](https://github.com/XLSForm/pyxform) If it is not working in production (504 Geteway timeout), xml (previously created from [XLSForm Online](https://getodk.org/xlsform/)) can be uploaded manually from admin site.
From this point, you are ready to go with form encoding on your smartphone!
> Follow [ODK instructions](https://docs.getodk.org/collect-connect/#configure-server-manually) to configure the connexion to the server
> Get, fill-in and submit data [using ODK Collect](https://docs.getodk.org/collect-using/)
4. **Create** Model in odkdata to get submitted data in a model formatted like xlsx form. [Thanks xlsconv!](https://github.com/wq/xlsform-converter)! Model creation is done into App `odkdata` with table name followed by `_orig` suffix when converted by xlsconv.
## Submitted form
Go to **Submitted form** menu of your server to see submitted data in XML format. On record view, click on `Insert` button to insert submitted XML data into `odkdata.models` created on step 4 hereabove.
Several record insert is available through admin interface. Select appropriate records (ie: those without insert date) and choose `Insert in odkdata model` from action dropdown list and click on 'Send' button.
# What next?
Create a new app in you project like `odkdata2` with `templates, views` (importing odkdata.models info) and `urls` to manage display/map/export-xls/update/analyse submitted data from ODK-Collect!
* Do not forget to add `odkdata2` logger specifications in settings.py
Comments/Improvements welcome!
Investigate [WQ Framework](https://wq.io/) but I still don't see how to deploy offline forms on smartphone.
Raw data
{
"_id": null,
"home_page": "https://github.com/openHBP/django-odk",
"name": "django-odk",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Patrick HOUBEN",
"author_email": "p.houben@cra.wallonie.be",
"download_url": "https://files.pythonhosted.org/packages/c1/65/6ab26b69f4e87f37b70391728dc72c01adbd86f52ffc9c3e8358e7b60255/django_odk-1.1.9.tar.gz",
"platform": "Linux",
"description": "# django-odk\nDjango data collection tool using [ODK-collect](https://play.google.com/store/apps/details?id=org.odk.collect.android&hl=en_US&gl=US) mobile app.\n\n\n## Prerequisite\n- Django web site up and running\n- Smartphone or tablet with [ODK-Collect installed](https://play.google.com/store/apps/details?id=org.odk.collect.android&hl=en_US&gl=US)\n- [XLSForm](https://xlsform.org/en/) file with 3 tabs 'survey', 'choices', 'settings'\n\nNEW from version 1.0.2 (xls2xml & create final model)\n- Since most of Xforms are using `geopoint`, the database must be set up **with vector geodatabase functionality**: PostGIS, Oracle Spatial, SQLite/SpatiaLite\n- **Java Runtime Environment (JRE)** installed `$ sudo apt install default-jre` for XForm validation used by [xlsconv](https://github.com/wq/xlsform-converter)\n\n\n## Installation\n* Run\n\n```bash\n$ pip install django-odk\n$ python manage.py migrate\n$ python manage.py createsuperuser\n```\n\n* Add odk and odkdata to your INSTALLED_APPS settings\n```py\nINSTALLED_APPS = (\n ...\n 'odk',\n 'odkdata',\n)\n```\n\n* Add LOCALE_PATHS and appropriate language_code in settings\n\n```py\nLOCALE_PATHS = [os.path.join(BASE_DIR, 'odk', 'locale')]\n\nLANGUAGE_CODE = 'en'\n# translated LANGUAGE_CODE: fr\n```\n\n* Add appropriate AUTH_USER_MODEL in settings.py\n```py\nAUTH_USER_MODEL = 'auth.user'\n```\n\n* For a more interactive app, configure **logging** as explained in [Lincoln Loop](https://lincolnloop.com/blog/django-logging-right-way/) and **messages** as explained in [Django](https://docs.djangoproject.com/en/4.0/ref/contrib/messages/)\n\n* For **logging**, add `odk` and `odkdata` entry to `loggers` key of your logging file and adapt `handlers` according to yours.\n```py\n 'loggers': {\n ...\n 'odk': {\n 'handlers': ['console', 'debugger', 'warning', 'error'],\n 'level': 'DEBUG' if DEBUG else 'INFO',\n 'propagate': False,\n },\n 'odkdata': {\n 'handlers': ['console', 'debugger', 'warning', 'error'],\n 'level': 'DEBUG' if DEBUG else 'INFO',\n 'propagate': False,\n },\n }\n```\n\n* Add **is_odk_admin** and **is_odk_user** property to your AUTH_USER_MODEL (django.contrib.auth.models file or specific accounts.models)\n```py\n @property\n def is_odk_admin(self):\n return self.groups.filter(name='odk-admin').exists()\n @property\n def is_odk_user(self):\n return self.groups.filter(name='odk-user').exists() \n```\n\n\n* Add odk.urls to the main urls.py file:\n```py\nurlpatterns = [\n ...\n path('odk/', include('odk.urls'), name='odk'),\n]\n```\n\n* Add menu or buttons to access **Available form**\n```py\n# bootstrap5 menu item example\n<li><a class=\"dropdown-item\" href=\"{% url 'odk:xform_list' %}\">{% trans \"ODK available forms\" %}</a></li>\n```\n\n* Add menu or buttons to access **Submitted form**\n```py\n# bootstrap5 menu item example\n<li><a class=\"dropdown-item\" href=\"{% url 'odk:xformsubmit_list' %}\">{% trans \"ODK submitted forms\" %}</a></li>\n```\n\n## Connect to the Django admin site\n* create a group 'odk-admin' with create, read, update access on odk objects\n* Associate this group to the appropriate users\n\n## Available form: Build, Upload, Convert, Create\nConnect to django-odk => **Available form** => Add and follow 4 steps:\n\n1. **Build** an XLSForm file with 3 tabs 'survey', 'choices', 'settings' [Cfr documentation](https://docs.getodk.org/xlsform/). Do not forget to add 'today' & 'username' fields in Survey tab!\n\n2. **Upload** xlsx file (XForm) by clicking on 'Choose file' and Save\n\n3. **Convert** xlsx file to xml XForm compatible file [Thanks pyxform!](https://github.com/XLSForm/pyxform) If it is not working in production (504 Geteway timeout), xml (previously created from [XLSForm Online](https://getodk.org/xlsform/)) can be uploaded manually from admin site.\n\nFrom this point, you are ready to go with form encoding on your smartphone!\n\n> Follow [ODK instructions](https://docs.getodk.org/collect-connect/#configure-server-manually) to configure the connexion to the server\n\n> Get, fill-in and submit data [using ODK Collect](https://docs.getodk.org/collect-using/)\n\n4. **Create** Model in odkdata to get submitted data in a model formatted like xlsx form. [Thanks xlsconv!](https://github.com/wq/xlsform-converter)! Model creation is done into App `odkdata` with table name followed by `_orig` suffix when converted by xlsconv.\n\n## Submitted form\nGo to **Submitted form** menu of your server to see submitted data in XML format. On record view, click on `Insert` button to insert submitted XML data into `odkdata.models` created on step 4 hereabove.\n\nSeveral record insert is available through admin interface. Select appropriate records (ie: those without insert date) and choose `Insert in odkdata model` from action dropdown list and click on 'Send' button.\n\n# What next?\nCreate a new app in you project like `odkdata2` with `templates, views` (importing odkdata.models info) and `urls` to manage display/map/export-xls/update/analyse submitted data from ODK-Collect!\n\n* Do not forget to add `odkdata2` logger specifications in settings.py\n\nComments/Improvements welcome!\n\nInvestigate [WQ Framework](https://wq.io/) but I still don't see how to deploy offline forms on smartphone.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Django Data Collection tool using ODK Collect mobile App",
"version": "1.1.9",
"project_urls": {
"Homepage": "https://github.com/openHBP/django-odk"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a46b235565b288ac63c5f284fbf57fe85f4b79a41a7169f719fafb25e33e20c7",
"md5": "9aa1d791a796e877995e5053e2abee23",
"sha256": "9dd21000bc591e71cbcaa48507288e8a4acbbbc42ed17b868644041e26b9be37"
},
"downloads": -1,
"filename": "django_odk-1.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9aa1d791a796e877995e5053e2abee23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 37869,
"upload_time": "2024-08-30T08:57:29",
"upload_time_iso_8601": "2024-08-30T08:57:29.593389Z",
"url": "https://files.pythonhosted.org/packages/a4/6b/235565b288ac63c5f284fbf57fe85f4b79a41a7169f719fafb25e33e20c7/django_odk-1.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c1656ab26b69f4e87f37b70391728dc72c01adbd86f52ffc9c3e8358e7b60255",
"md5": "f6d0a319ceb330230db3fa8e6050c0b5",
"sha256": "39a8033b6409051be76b84536e5b5dbdfa30424c5cc03f53fd7965de23ec833f"
},
"downloads": -1,
"filename": "django_odk-1.1.9.tar.gz",
"has_sig": false,
"md5_digest": "f6d0a319ceb330230db3fa8e6050c0b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33586,
"upload_time": "2024-08-30T08:57:31",
"upload_time_iso_8601": "2024-08-30T08:57:31.005528Z",
"url": "https://files.pythonhosted.org/packages/c1/65/6ab26b69f4e87f37b70391728dc72c01adbd86f52ffc9c3e8358e7b60255/django_odk-1.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-30 08:57:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openHBP",
"github_project": "django-odk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-odk"
}
JSON
