Add support for entities

[kelvin-muchiri]

Suggested Feature / Enhancement

The is a new feature on ODK Collect called entities where you can link two forms and perform specific calculation from the data collected in the linked form.
currently, we have Linking a form as media file which works well with only Pulldata function.

Benefits of implementing the feature/enhancement

Ability to perform more calculations e.g max or min of data, or totals of certain column

Suggested implementation plan(Steps to be taken to implement feature)

Models

EntityList Model

The list where each entity will be saved to. Entities of the same type are organized in entity lists.

Field	Type	Required	Description
pk	IntegerField	Yes	Primary Key. Auto-generated
name	CharField	Yes	This is the name that the follow-up form will reference
project	ForeignKey	Yes	The Project the EntityList belongs to
created_at	DateTimeField	Yes	Auto-filled when object is created
updated_at	DateTimeField	Yes	Auto-filled when object is modified

name and project are unique together

RegistrationForm Model

This is the form (registration form) that creates entities in an entity list.

Field	Type	Required	Description
pk	IntegerField	Yes	Primary Key. Auto-generated
entity_list	ForeignKeyField	Yes	EntityList object that the form saves entities to. The same EntityList can be used in many different forms
xform	ForeignKeyField	Yes	XForm object that creates entities
is_active	BooleanField	No	If True the Registration is contributing entities to the EntityList. Default is True
created_at	DateTimeField	Yes	Auto-filled when object is created
updated_at	DateTimeField	Yes	Auto-filled when object is modified

entity_list and xform are unique together

Once a XForm that defines entities is created, an EntityList will be created. If an EntityList with the name you specify already exists, then that XForm will use that EntityList.

FollowUpForm Model

This is the form (follow-up form) that consumes entities from an entity list.

Field	Type	Required	Description
pk	IntegerField	Yes	Primary Key. Auto-generated
entity_list	ForeignKeyField	Yes	EntityList object that the form consumes entities from
xform	ForeignKeyField	Yes	XForm object that consumes entities
created_at	DateTimeField	Yes	Auto-filled when object is created
updated_at	DateTimeField	Yes	Auto-filled when object is modified

entity_list and xform are unique together

Entity
An entity created by a registration form

Field	Type	Required	Description
pk	IntegerField	Yes	Primary Key. Auto-generated
registration_form	ForeignKeyField	Yes	RegistrationForm object that created the entity
xml	TextField	Yes	Submission's XML
json	JSONField	Yes	Submission's XML to JSON
version	CharField	No	The XForm version used when the submission was made
created_at	DateTimeField	Yes	Auto-filled when object is created
updated_at	DateTimeField	Yes	Auto-filled when object is modified

Endpoints

Get EntityLists: GET /api/v1/entity-lists

Example

curl -X GET https://api.ona.io/api/v1/entity-lists

Response

[
  {
      "url": "https://api.ona.io/api/v1/entity-lists/1",
      "id": 1,
      "name": "trees",
      "project": "https://api.ona.io/api/v1/projects/1",
      "num_registration_forms": 2,
      "num_followup_forms": 1
  },
  {
      "url": "https://api.ona.io/api/v1/entity-lists/2",
      "id": 2,
      "name": "immunization",
      "project": "https://api.ona.io/api/v1/projects/2",
      "num_registration_forms": 1,
      "num_followup_forms": 1
  }
]

Get EntityLists for a specific project: GET /api/v1/entity-lists?project=<project_id>

Example

curl -X GET https://api.ona.io/api/v1/entity-lists?project=1

Response

[
  {
      "id": 1,
      "name": "trees",
      "project": "https://api.ona.io/api/v1/projects/1",
      "num_registration_forms": 2,
      "num_followup_forms": 1
  }
]

Get a single EntityList: GET /api/v1/entity-lists/<entity_list_id>

Example

curl -X GET https://api.ona.io/api/v1/entity-lists/1

Response

{
   "id":1,
   "name":"trees",
   "project":"https://api.ona.io/api/v1/projects/1",
   "created_at":"2013-07-24T13:59:10Z",
   "updated_at":"2013-07-24T13:59:10Z",
   "num_registration_forms": 2,
   "num_followup_forms": 1,
   "registration_forms":[
      {
         "name":"Trees Registration",
         "formid":1,
         "id_string":"trees_registration",
         "save_to":  ["geometry", "species", "circumference"]
      },
      {
         "name":"Trees Height Registration",
         "formid":2,
         "id_string":"trees_height_registration",
         "save_to": ["geometry", "species", "height"]
      }
   ],
   "follow_up_forms":[
      {
         "name":"Trees Follow Up",
         "formid":3,
         "id_string":"trees_follow_up"
      }
   ]
}

Get Entities: GET /api/v1/entity-lists/<entity_list_id>/entities

Example

curl -X GET https://api.ona.io/api/v1/entity-lists/1/entities

The properties returned for Entities should be the properties defined in the forms save_to

Response

[
    {
                "formhub/uuid": "d156a2dce4c34751af57f21ef5c4e6cc",
                "geometry": "-1.286905 36.772845 0 0",
                "species": "purpleheart",
                "circumference_cm": 300,
                "meta/instanceID": "uuid:9d3f042e-cfec-4d2a-8b5b-212e3b04802b",
                "meta/instanceName": "300cm purpleheart",
                "meta/entity/label": "300cm purpleheart",
                "_xform_id_string": "trees_registration",
                "_version": "2022110901",
     }
 ]

Download EntityList dataset: Use endpoint Get a specific metadata or GET <username>/xformsMedia/<form_id>/<metadata_id>.csv