Skip to content

Commit

Permalink
Merge pull request #1225 Flow Results Packages endpoint.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ukanga
ukanga authored Feb 1, 2018
2 parents 9992eba + 4144ab2 commit f84c59d
Show file tree
Hide file tree
Showing 18 changed files with 846 additions and 91 deletions.
38 changes: 38 additions & 0 deletions docs/flow-results.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@

Flow Results Packages (Experimental)
************************************

Overview
--------

The ``/api/v1/flow-results/packages`` implements the flow results API specifications. See the documentation at `FLOW Results Specification <https://github.com/FLOIP/flow-results/blob/api-spec/api-specification.md>`_. This is the only endpoint that also uses the `JSON API specification <http://jsonapi.org/format/>`_. The Flow Results Package is processed by the library `floip-py <https://github.com/onaio/floip-py>`_.

The Flow Results package is still in its early stages and this implementation is more of a proof of concept. Not all types are supported, some field types not yet supported may be ignored and hence not appear in the resulting Flow Results Package. The transformations also attempt to fit the data as the existing underlying structure of XForms and XForm submissions.

When pushing in a Flow Results Responses Package, the ``row_id``, ``question_id`` and the ``response_id`` columns are the main fields that data is extracted from the rest are ignored.

It is expected that the ``row_id`` should be the same for records that represent one submission or interaction throw a full Flow. For example where a Flow captures the name, age and place of birth of persions in attendance, the ``row_id`` of a single persion should be the same.

::

...
# first submission
["2018-01-23T11:42:16", 110, "enumerator_x", "name", "Rudy Rue", {}],
["2018-01-23T11:42:16", 110, "enumerator_x", "age", 30, {}],
["2018-01-23T11:42:16", 110, "enumerator_x", "place_of_birth", "Elburgon", {}],
# second submission
["2018-01-23T11:42:16", 111, "enumerator_x", "name", "Elma Louie", {}],
["2018-01-23T11:42:16", 111, "enumerator_x", "age", 23, {}],
["2018-01-23T11:42:16", 111, "enumerator_x", "place_of_birth", "Turbo", {}],
...

Numeric ``question_id`` fields will fail to publish because they do not form valid XML tags.

The Flow Results Package profile, ``flow-results-package``, is not yet supported by `Datapackage <https://frictionlessdata.io/schemas/registry.json>`_ as such you may have to replace the default profile with ``data-package`` to validate with `Data Package <https://github.com/frictionlessdata/datapackage-py>`_.


Authentication
--------------

Authentication methods supported is as documented `here <authenticationi.html>`_.

17 changes: 13 additions & 4 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,13 +64,13 @@ Users and Organizations
user
users

Modules
-----------
Flow Results Packages
---------------------

.. toctree::
:maxdepth: 2
:maxdepth: 2

modules
flow-results

Ona Tagging API
~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -98,6 +98,15 @@ Running your own server
install


Modules
-----------

.. toctree::
:maxdepth: 2

modules


Indices and tables
==================

Expand Down
22 changes: 22 additions & 0 deletions docs/onadata.apps.api.tests.permissions.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
onadata\.apps\.api\.tests\.permissions package
==============================================

Submodules
----------

onadata\.apps\.api\.tests\.permissions\.test\_permissions module
----------------------------------------------------------------

.. automodule:: onadata.apps.api.tests.permissions.test_permissions
:members:
:undoc-members:
:show-inheritance:


Module contents
---------------

.. automodule:: onadata.apps.api.tests.permissions
:members:
:undoc-members:
:show-inheritance:
22 changes: 22 additions & 0 deletions docs/onadata.apps.restservice.management.commands.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
onadata\.apps\.restservice\.management\.commands package
========================================================

Submodules
----------

onadata\.apps\.restservice\.management\.commands\.textit\_v1\_to\_v2 module
---------------------------------------------------------------------------

.. automodule:: onadata.apps.restservice.management.commands.textit_v1_to_v2
:members:
:undoc-members:
:show-inheritance:


Module contents
---------------

.. automodule:: onadata.apps.restservice.management.commands
:members:
:undoc-members:
:show-inheritance:
17 changes: 17 additions & 0 deletions docs/onadata.apps.restservice.management.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
onadata\.apps\.restservice\.management package
==============================================

Subpackages
-----------

.. toctree::

onadata.apps.restservice.management.commands

Module contents
---------------

.. automodule:: onadata.apps.restservice.management
:members:
:undoc-members:
:show-inheritance:
101 changes: 101 additions & 0 deletions onadata/apps/api/tests/fixtures/flow-results-example-1-api.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
{
"data": {
"type": "packages",
"attributes": {
"profile": "tabular-data-resource",
"name": "flow-results-example-1",
"created": "2017-06-30 15:35:27+00:00",
"title": "A nice title",
"modified": "2017-06-30 15:38:05+00:00",
"flow_results_specification_version": "1.0.0-rc1",
"id": "b03ec84-77fd-4270-813b-0c698943f7ce",
"resources": [
{
"path": "data/flow-results-example-1-data.json",
"schema": {
"fields": [
{
"type": "datetime",
"name": "timestamp",
"title": "Timestamp"
},
{
"type": "string",
"name": "row_id",
"title": "Row ID"
},
{
"type": "string",
"name": "contact_id",
"title": "Contact ID"
},
{
"type": "string",
"name": "question_id",
"title": "Question ID"
},
{
"type": "any",
"name": "response",
"title": "Response"
},
{
"type": "object",
"name": "response_metadata",
"title": "Response Metadata"
}
],
"questions": {
"ae54d3": {
"type_options": {
"choices": [
"male",
"female",
"not identified"
]
},
"type": "select_one",
"label": "Are you male or female?"
},
"ae54db": {
"type_options": {},
"type": "geo_point",
"label": "Where are you?"
},
"ae54da": {
"type_options": {},
"type": "text",
"label": "How are you feeling today?"
},
"ae54d8": {
"type_options": {
"range": [
1,
250
]
},
"type": "numeric",
"label": "How much do you weigh, in lbs?"
},
"ae54d7": {
"type_options": {
"choices": [
"chocolate",
"vanilla",
"strawberry"
]
},
"type": "select_many",
"label": "Favorite ice cream flavor?"
}
},
"language": "eng"
},
"encoding": "utf-8",
"name": "flow-results-example-1-data",
"mediatype": "application/json"
}
]
}
}
}
54 changes: 54 additions & 0 deletions onadata/apps/api/tests/fixtures/flow-results-example-2-api-data.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@

{
"data":{
"type":"responses",
"id":"0c364ee1-0305-42ad-9fc9-2ec5a80c55fa",
"attributes":{
"responses":[
[
"2015-11-26 04:33:26",
"11393115",
"10825354",
"f1448506769745_42",
"Man",
{}
],
[
"2015-11-26 04:33:31",
"11393115",
"10825354",
"f1448506773018_89",
"30.0000",
{}
],
[
"2015-11-26 04:33:35",
"11393115",
"10825354",
"f1448506774930_30",
"https://go.votomobile.org/audiofiles/download//original",
{
"type":"audio",
"format":"audio/wav"
}
],
[
"2015-11-26 04:34:07",
"11393169",
"10825354",
"f1448506769745_42",
"Woman",
{}
],
[
"2015-11-26 04:34:13",
"11393169",
"10825354",
"f1448506773018_89",
"40.0000",
{}
]
]
}
}
}
88 changes: 88 additions & 0 deletions onadata/apps/api/tests/fixtures/flow-results-example-2-api.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
{
"data":{
"type":"packages",
"attributes":{
"profile":"flow-results-package",
"name":"standard_test_survey",
"flow-results-specification":"1.0.0-rc1",
"created":"2015-11-26 02:59:24+00:00",
"modified":"2017-12-04 15:54:44+00:00",
"id":null,
"title":"Standard Test Survey",
"resources":[
{
"path":null,
"api-data-url":null,
"mediatype":"application/json",
"name": "standard_test_survey-data",
"encoding":"utf-8",
"schema":{
"language":"eng",
"fields":[
{
"name":"timestamp",
"title":"Timestamp",
"type":"datetime"
},
{
"name":"row_id",
"title":"Row ID",
"type":"string"
},
{
"name":"contact_id",
"title":"Contact ID",
"type":"string"
},
{
"name":"question_id",
"title":"Question ID",
"type":"string"
},
{
"name":"response_id",
"title":"Response ID",
"type":"any"
},
{
"name":"response_metadata",
"title":"Response Metadata",
"type":"object"
}
],
"questions":{
"f1448506769745_42":{
"type":"select_one",
"label":"Are you a woman or a man?",
"type_options":{
"choices":[
"Woman",
"Man",
"Other"
]
}
},
"f1448506773018_89":{
"type":"numeric",
"label":"How old are you? Please enter your age in years.",
"type_options":{
"range":[
-99,
99
]
}
},
"f1448506774930_30":{
"type":"text",
"label":"What was the best thing that happened to you today?",
"type_options":{

}
}
}
}
}
]
}
}
}
Loading

0 comments on commit f84c59d

Please sign in to comment.