diff --git a/README.md b/README.md index 509b9965..cdd9a168 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Installation & Quick Start 0a\. Install Python and `pip`. This tool is [tested with Python 2.7, 3.6 and 3.7](https://travis-ci.org/dimagi/commcare-export). -0b\. Sign up for CommCareHQ at https://www.commcarehq.org/register/user if you have not already. +0b\. Sign up for [CommCareHQ](https://www.commcarehq.org/) if you have not already. 1\. Install CommCare Export via `pip` @@ -25,13 +25,16 @@ Installation & Quick Start $ pip install commcare-export ``` -2\. Visit the CommCareHQ Exchange and add the [Simple CommCare Demo/Tutorial"](https://www.commcarehq.org/exchange/611422532c7ab89d22cca54d57ae89aa/info/) app to a new project space. +2\. Create a project space and application. 3\. Visit the Release Manager, make a build, click the star to release it. -4\. Visit CloudCare and fill out a bunch of forms. +4\. Use Web Apps and fill out some forms. -5\. Try out the example queries in the `examples/` directory, providing your project name on the command line: +5\. Modify one of example queries in the `examples/` directory, modifying the "Filter Value" column + to match your form XMLNS / case type. + See [this page](https://confluence.dimagi.com/display/commcarepublic/Finding+a+Form%27s+XMLNS) to + determine the XMLNS for your form. ``` $ commcare-export \ @@ -58,7 +61,8 @@ $ commcare-export \ You'll see the tables printed out. Change to `--output-format sql --output URL_TO_YOUR_DB --since DATE` to sync all forms submitted since that date. -All examples are present in Excel and also equivalent JSON. +All examples are present in Excel and also equivalent JSON, however it is recommended +to use the Excel format as the JSON format may change upon future library releases. Command-line Usage ------------------ @@ -332,7 +336,7 @@ Contributing $ mkvirtualenv commcare-export $ git clone git@github.com:dimagi/commcare-export.git $ cd commcare-export -$ pip install -e ".[testing]" +$ pip install -e ".[test]" $ git checkout -b my-super-duper-feature ``` diff --git a/examples/demo-deliveries.json b/examples/demo-deliveries.json index 1a578082..77e15078 100644 --- a/examples/demo-deliveries.json +++ b/examples/demo-deliveries.json @@ -1,75 +1,160 @@ { - "List": [ - { "Emit": { - "table": "Deliveries", - "headings": [ - { "Lit": "id" }, - { "Lit": "Did the mother deliver?" }, - { "Lit": "Delivery Date" }, - { "Lit": "Delivery Type" }, - { "Lit": "Number of children born" } - ], - "source": { - "Map": { - "body": { - "List": [ - { "Ref": "id" }, - { "Ref": "form.mother_deliver" }, - { "Ref": "form.delivery_information.delivery_date" }, - { "Ref": "form.delivery_information.delivery_type" }, - { "Ref": "form.delivery_information.num_children" } + "Bind": { + "name": "checkpoint_manager", + "value": { + "Apply": { + "fn": { + "Ref": "get_checkpoint_manager" + }, + "args": [ + { + "Lit": [ + "Deliveries", + "Children" ] - }, - "source": { - "Apply": { - "fn": { "Ref": "api_data" }, - "args": [ - { "Lit": "form" }, - { "Lit": { - "filter": { "term": { "xmlns.exact": "http://openrosa.org/formdesigner/74CCF2B2-AB85-4F1D-9CD7-5203056BB213" } } - }} - ] - } } - } + ] } - }}, - { "Emit": { - "table": "Children", - "headings": [ - { "Lit": "Form ID" }, - { "Lit": "id" }, - { "Lit": "Gender" }, - { "Lit": "Birth Weight" } - ], - "source": { - "Map": { - "body": { - "List": [ - { "Ref": "$.id" }, - { "Ref": "id" }, - { "Ref": "gender" }, - { "Ref": "birth_weight" } + }, + "body": { + "Filter": { + "predicate": { + "Apply": { + "fn": { + "Ref": "filter_empty" + }, + "args": [ + { + "Ref": "$" + } ] - }, - "source": { - "FlatMap": { - "body": { "Ref": "form.delivery_information.child_questions.[*]" }, - "source": { - "Apply": { - "fn": { "Ref": "api_data" }, - "args": [ - { "Lit": "form" }, - { "Lit": { - "filter": { "term": { "xmlns.exact": "http://openrosa.org/formdesigner/74CCF2B2-AB85-4F1D-9CD7-5203056BB213" } } - }} - ] - } + } + }, + "source": { + "Map": { + "body": { + "List": [ + { + "Emit": { + "table": "Deliveries", + "headings": [ + { + "Lit": "id" + }, + { + "Lit": "Did the mother deliver?" + }, + { + "Lit": "Delivery Date" + }, + { + "Lit": "Delivery Type" + }, + { + "Lit": "Number of children born" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "id" + }, + { + "Ref": "form.mother_deliver" + }, + { + "Ref": "form.delivery_information.delivery_date" + }, + { + "Ref": "form.delivery_information.delivery_type" + }, + { + "Ref": "form.delivery_information.num_children" + } + ] + }, + "source": { + "Ref": "`this`" + }, + "name": null + } + }, + "missing_value": null + } + }, + { + "Emit": { + "table": "Children", + "headings": [ + { + "Lit": "Form ID" + }, + { + "Lit": "id" + }, + { + "Lit": "Gender" + }, + { + "Lit": "Birth Weight" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "$.id" + }, + { + "Ref": "id" + }, + { + "Ref": "gender" + }, + { + "Ref": "birth_weight" + } + ] + }, + "source": { + "Ref": "form.delivery_information.child_questions.[*]" + }, + "name": null + } + }, + "missing_value": null + } + } + ] + }, + "source": { + "Apply": { + "fn": { + "Ref": "api_data" + }, + "args": [ + { + "Lit": "form" + }, + { + "Ref": "checkpoint_manager" + }, + { + "Lit": { + "xmlns.exact": "http://openrosa.org/formdesigner/74CCF2B2-AB85-4F1D-9CD7-5203056BB213" + } + } + ] } - } + }, + "name": null } - } + }, + "name": null } - }} - ] + } + } } diff --git a/examples/demo-pregnancy-cases-with-forms.json b/examples/demo-pregnancy-cases-with-forms.json new file mode 100644 index 00000000..089e0760 --- /dev/null +++ b/examples/demo-pregnancy-cases-with-forms.json @@ -0,0 +1,189 @@ +{ + "List": [ + { + "Bind": { + "name": "checkpoint_manager", + "value": { + "Apply": { + "fn": { + "Ref": "get_checkpoint_manager" + }, + "args": [ + { + "Lit": [ + "Pregnant Mother Cases" + ] + } + ] + } + }, + "body": { + "Emit": { + "table": "Pregnant Mother Cases", + "headings": [ + { + "Lit": "id" + }, + { + "Lit": "Case Opened On" + }, + { + "Lit": "Mother's Name" + }, + { + "Lit": "Age" + }, + { + "Lit": "Estimated Delivery Date" + }, + { + "Lit": "Actual Delivery Date" + }, + { + "Lit": "Submission Dates" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "case_id" + }, + { + "Ref": "properties.date_opened" + }, + { + "Ref": "properties.case_name" + }, + { + "Ref": "properties.age" + }, + { + "Ref": "properties.edd" + }, + { + "Ref": "properties.delivery_date" + }, + { + "Ref": "xforms[*].received_on" + } + ] + }, + "source": { + "Apply": { + "fn": { + "Ref": "api_data" + }, + "args": [ + { + "Lit": "case" + }, + { + "Ref": "checkpoint_manager" + }, + { + "Lit": { + "type": "pregnant_mother" + } + }, + { + "Lit": [ + "xforms" + ] + } + ] + } + }, + "name": null + } + }, + "missing_value": null + } + } + } + }, + { + "Bind": { + "name": "checkpoint_manager", + "value": { + "Apply": { + "fn": { + "Ref": "get_checkpoint_manager" + }, + "args": [ + { + "Lit": [ + "CaseToForm" + ] + } + ] + } + }, + "body": { + "Emit": { + "table": "CaseToForm", + "headings": [ + { + "Lit": "Case ID" + }, + { + "Lit": "Form ID" + }, + { + "Lit": "id" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "$.id" + }, + { + "Ref": "`this`" + }, + { + "Ref": "`this`" + } + ] + }, + "source": { + "FlatMap": { + "body": { + "Ref": "xform_ids.[*]" + }, + "source": { + "Apply": { + "fn": { + "Ref": "api_data" + }, + "args": [ + { + "Lit": "case" + }, + { + "Ref": "checkpoint_manager" + }, + { + "Lit": { + "type": "pregnant_mother" + } + } + ] + } + }, + "name": null + } + }, + "name": null + } + }, + "missing_value": null + } + } + } + } + ] +} diff --git a/examples/demo-pregnancy-cases.json b/examples/demo-pregnancy-cases.json index 3f0e7f27..e65144eb 100644 --- a/examples/demo-pregnancy-cases.json +++ b/examples/demo-pregnancy-cases.json @@ -1,132 +1,160 @@ { - "List": [ - { - "Emit": { - "table": "Pregnant Mother Cases", - "headings": [ + "Bind": { + "name": "checkpoint_manager", + "value": { + "Apply": { + "fn": { + "Ref": "get_checkpoint_manager" + }, + "args": [ { - "Lit": "id" - }, - { - "Lit": "Case Opened On" - }, - { - "Lit": "Mother's Name" - }, - { - "Lit": "Age" - }, - { - "Lit": "Estimated Delivery Date" - }, - { - "Lit": "Actual Delivery Date" + "Lit": [ + "Pregnant Mother Cases", + "CaseToForm" + ] + } + ] + } + }, + "body": { + "Filter": { + "predicate": { + "Apply": { + "fn": { + "Ref": "filter_empty" + }, + "args": [ + { + "Ref": "$" + } + ] } - ], + }, "source": { "Map": { "body": { "List": [ { - "Ref": "case_id" - }, - { - "Ref": "properties.date_opened" - }, - { - "Ref": "properties.case_name" - }, - { - "Ref": "properties.age" - }, - { - "Ref": "properties.edd" - }, + "Emit": { + "table": "Pregnant Mother Cases", + "headings": [ + { + "Lit": "id" + }, + { + "Lit": "Case Opened On" + }, + { + "Lit": "Mother's Name" + }, + { + "Lit": "Age" + }, + { + "Lit": "Estimated Delivery Date" + }, + { + "Lit": "Actual Delivery Date" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "case_id" + }, + { + "Ref": "properties.date_opened" + }, + { + "Ref": "properties.case_name" + }, + { + "Ref": "properties.age" + }, + { + "Ref": "properties.edd" + }, + { + "Ref": "properties.delivery_date" + } + ] + }, + "source": { + "Ref": "`this`" + }, + "name": null + } + }, + "missing_value": null + } + }, { - "Ref": "properties.delivery_date" + "Emit": { + "table": "CaseToForm", + "headings": [ + { + "Lit": "Case ID" + }, + { + "Lit": "Form ID" + }, + { + "Lit": "id" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "$.id" + }, + { + "Ref": "`this`" + }, + { + "Ref": "`this`" + } + ] + }, + "source": { + "Ref": "xform_ids.[*]" + }, + "name": null + } + }, + "missing_value": null + } } ] - }, + }, "source": { "Apply": { + "fn": { + "Ref": "api_data" + }, "args": [ { "Lit": "case" - }, + }, + { + "Ref": "checkpoint_manager" + }, { "Lit": { "type": "pregnant_mother" } } - ], - "fn": { - "Ref": "api_data" - } - } - }, - "name": null - } - } - } - }, - { - "Emit": { - "table": "CaseToForm", - "headings": [ - { - "Lit": "Case ID" - }, - { - "Lit": "Form ID" - }, - { - "Lit": "id" - } - ], - "source": { - "Map": { - "body": { - "List": [ - { - "Ref": "$.id" - }, - { - "Ref": "`this`" - }, - { - "Ref": "`this`" - } - ] - }, - "source": { - "FlatMap": { - "body": { - "Ref": "xform_ids.[*]" - }, - "source": { - "Apply": { - "args": [ - { - "Lit": "case" - }, - { - "Lit": { - "type": "pregnant_mother" - } - } - ], - "fn": { - "Ref": "api_data" - } - } - }, - "name": null + ] } - }, + }, "name": null } - } + }, + "name": null } } - ] + } } diff --git a/examples/demo-registrations.json b/examples/demo-registrations.json index a2b1c6fa..1c9742fb 100644 --- a/examples/demo-registrations.json +++ b/examples/demo-registrations.json @@ -1,34 +1,92 @@ { - "Emit": { - "table": "Registrations", - "headings": [ - {"Lit": "id"}, - {"Lit": "Received On"}, - {"Lit": "Mother's Name"}, - {"Lit": "Age"}, - {"Lit": "Pregnant?"}, - {"Lit": "Estimated Delivery Date"} - ], - "source": {"Map": { - "body": { - "List": [ - {"Ref": "id"}, - {"Ref": "received_on"}, - {"Ref": "form.name"}, - {"Ref": "form.age"}, - {"Ref": "form.ispregnant"}, - {"Ref": "form.edd"} - ] - }, - "source": {"Apply": { - "fn": {"Ref": "api_data"}, + "Bind": { + "name": "checkpoint_manager", + "value": { + "Apply": { + "fn": { + "Ref": "get_checkpoint_manager" + }, "args": [ - {"Lit": "form"}, - {"Lit": {"filter": {"and":[ - {"term": {"xmlns.exact": "http://openrosa.org/formdesigner/dd3190c7dd7e9e7d469a9705709f2f6b4e27f1d8"}} - ]}}} + { + "Lit": [ + "Registrations" + ] + } ] - }} - }} + } + }, + "body": { + "Emit": { + "table": "Registrations", + "headings": [ + { + "Lit": "id" + }, + { + "Lit": "Received On" + }, + { + "Lit": "Mother's Name" + }, + { + "Lit": "Age" + }, + { + "Lit": "Pregnant?" + }, + { + "Lit": "Estimated Delivery Date" + } + ], + "source": { + "Map": { + "body": { + "List": [ + { + "Ref": "id" + }, + { + "Ref": "received_on" + }, + { + "Ref": "form.name" + }, + { + "Ref": "form.age" + }, + { + "Ref": "form.ispregnant" + }, + { + "Ref": "form.edd" + } + ] + }, + "source": { + "Apply": { + "fn": { + "Ref": "api_data" + }, + "args": [ + { + "Lit": "form" + }, + { + "Ref": "checkpoint_manager" + }, + { + "Lit": { + "xmlns.exact": "http://openrosa.org/formdesigner/dd3190c7dd7e9e7d469a9705709f2f6b4e27f1d8" + } + } + ] + } + }, + "name": null + } + }, + "missing_value": null + } + } } }