I would like to know if it is possible to easily integrate ODK entities in a project that has already been running for a while. Several pieces of information about a group or entity are rewritten in multiple follow up forms and a special ID is generated to link form submissions to the entities. Is there a way to generate a specific ID when an entity is created and ensure that the ID does not already exist in the entity list?
Great questions all around.
First I would encourage you to try building out an entities-based workflow in a test project to make sure that it does make your life easier enough to risk disrupting work that's already ongoing. Sometimes a so-so solution that has been battle-tested is better than something shiny and new that introduces new risk!
That said, you can start using entities in existing projects or even published forms at any time. If you update an existing form to register Entities (see documentation, that will create an Entity List with the name you specify in the form and new submissions to the form will create entities in that list.
If submissions that were made before the change have information about entities that will need further follow-up, you can download the submission data and then use the API to create entities from them (related thread, creating entities from a CSV using pyodk). In the first Central release of 2024, you will be able to create an Entity List from Central and create Entities in it by uploading your CSV. For now you must use a registration form to create the Entity List and you must use the API to create new entities from existing submissions.
When you create an Entity, it is assigned a UUID that will identify it uniquely to ODK. That UUID will be available as the name system property of the Entity when the Entity List is attached to forms. That means if you use the Entity List to populate a select (documentation), the value of the select field will be the UUID for the selected entity.
I think what you want to do, though, is use some kind of real-world identifier to make sure that the same real-world thing is not registered multiple times, is that right?
Currently the best way to do this would be:
- attach the entity list to the form that registers entities in that list
- have the registration form generate the id based on form values
- use a constraint and/or relevance to stop users from creating entities with the same real-world id as an existing one
See this sample form.
Some things to note:
- Picking good real-world IDs is an art. Make sure to balance privacy, uniqueness requirements, etc when designing these.
- Entities are currently only created server-side, not locally on the device. You must submit a subject registration and refresh the form before that subject will be available to be flagged as a duplicate.
- As I mentioned above, Entity Lists are only created when the first form that creates Entities in that list is published. This makes things weird when a form like the one I linked to both creates new Entities and accesses existing ones. You'll need to publish the form to create the Entity List. Then when you try to fill out the form, you'll get an error about a missing subjects.csv file because the Entity List didn't exist at publishing time. You can create a new draft with exactly the same form definition and publish it to link the now-existing Entity List back to the form. We'll make this smoother soon!
1 Like