We've recently added a new page to our docs that serves as a quick reference for XLSForm syntax when working with Entities. This new Entity Cheat Sheet is designed to complement the more in-depth Entity resources we have and help you quickly navigate Entity-related features.
Highlights
How to save submission data as Entity properties when creating or updating Entities
How to manage conditional creating/updating
How to select and filter Entities in Forms
How to pre-fill fields with data from existing Entities
What information about an Entity is available in a Form vs. in an export or via API
Shout-outs
Special thanks to forum members whose existing discussions helped inform this documentation. @ahblake's distillation of conditional creates/updates and @janna and @seewhy's conversation about dynamic defaults provided valuable insights that weren't yet clearly documented elsewhere. We've refined these community discussions into more formal documentation to benefit everyone working with Entities.
Feedback
We are interested in feedback from you both about your experience working with Entities thus far, and about your experience with the documentation resources around entities.
What's your experience with Entities?
Not Applicable: doesn’t apply to my workflow
Entity-curious: interested but haven’t tried it yet
Beginner: basic understanding with little hands-on experience
Intermediate: some practical experience and familiarity
Advanced: deep understanding with significant experience
Hi @ktuite
Thanks for compiling the Cheat Sheet - it works really well (for me) in picking up some of the nuance around Entities - they are, at the same time, really simple but powerfully complex things to work with! Every time I look round there's a helpful new trick to ease the way...
The section around the Label caught my eye (https://docs.getodk.org/entity-cheat-sheet/#label) - is it the case that the Label needs to be unique (and therefore acts like a key) or can the Label be repeated if another field might help to filter duplicates? I have been working on the basis of the former...
For me, this is an important aspect of designing the form (or external process) to get the appropriate Label 'concat' expression - much the way I used to try to come up with an Instance Name that would be easy to identify (and potentially unique) when editing saved (now draft) forms... I saw a helpful post from @LN recently around strategies for Labels, highlighting the need to balance detail and data privacy when thinking of what to include in the Label text. This might be useful as part of the Cheat Sheet to extend the level of guidance (or avoid pitfalls).
Also, in practice, I find that cascading drop-downs can be really helpful for finding the right Entity if you are not using geographic data to (literally) pin-point them. Being presented with a list of potential options that is used as a filter in a subsequent question is often easier to work with than a search function (especially if you don't know the 'rules' of how Entities within a List might have been grouped / categorised). For example if the first question is a select_one for 'What city are you currently in' the second could filter the Entities that are within that city to make a shorter list... And also if the city is not on the first list, maybe the enumerator is in the wrong place
Thanks for the feedback! I see the discussion you're referring to here and I will have to go take a closer look!
To answer your question about Labels, they don't actually need to be unique. That is definitely something we can add to the Entity Cheat Sheet, along with more tips about labeling strategies (detail vs. privacy). The only computation that happens with the label within Central are checks to make sure it is not empty.
At the moment, we don't have a mechanism for indicating that a specific property should be unique or have Central enforce that. It's something we are thinking about, though! Currently, the only enforced unique part of an entity is the UUID, and this can't really be specified by the user.
For your last paragraph, are you suggesting a section of the cheat sheet that could show a small example of this -- of filtering an entity list by several levels of cascaded drop-downs? That could be added! I'm also working on something somewhat related, of making a tutorial of using entities to represent nested levels of geographic information. You've given me the idea to expand upon that and show how to filter entities by properties selected from other entities.
Well, that's me told! I had assumed from everything I'd seen that the label needed to be unique, but hadn't actually tested it. That makes life a little easier if we don't need to enforce uniqueness (and I can scrub that part of the validation tests in QuODK!). Really good to have that explained too.
But, importantly, if you are creating Entities through the API / pyODK the UUID can be specified (so having that KEY in an external dataset can be helpful) - also the point about using a Different Key https://docs.getodk.org/entity-cheat-sheet/#using-a-different-key is also useful.
I think that from the enumerator perspective, the ease of finding the right Entity is fundamental to success - we are perhaps underplaying the importance of these strategies, especially when people are wanting HUGE Entity Lists (with the potential for BIG data being the enemy of GOOD data). I worry, for example, about relying on 'consumer grade' GPS locations to identify an individual tree in a forest... Not always practical (or acceptable) to pin a QR / bar code on a tree (or other living thing!).
In my experience, repeatability is as important and having lots of data points. Otherwise we can't develop time-series or 'trust' that the repeat data is matched correctly. So if you can't be sure you've selected the right entity, it might as well be on a piece of paper in a box in your basement when you are in the mountains (just a story I was once told by someone else...).
So I'm meaning all of this very positively in terms of what entities can do and especially the value of something like a cheat sheet, so that data managers avoid making it too hard for enumerators to do their job efficiently. Bearing in mind that I wear (at least) two hats! Actually I'd like to see the Cheat Sheet have a more positive name, because somehow it feels undervalued.
Thanks for highlighting the importance of making it easy for enumerators to select the correct entity to work with! We've started planning out limiting entity access / entity segmentation within Central, which may be part of a solution but not the full solution. There is everything else you mentioned of how the entity is selected (even if the entity list is smaller) whether it be through tag/barcode, GPS, multi-level cascading select, etc. and ways for the enumerator to verify that they have selected the appropriate entity.
