Entities - returning equivalent of 'name' in a form that selects from an entity list

Support
1

1. What is the issue? Please be detailed.
(I couldn't find this topic addressed directly, this is partially a question and partially documenting how to move from a CSV to an entity list and still return desired name values in the submissions)

When creating an entity list, the entity property name is prohibited. Likely as this used to be used for the UUID before it changed to __id as seen in the quick start video at 6:00.

In many cases, the name value in a choice list / CSV is different to the label value (select a name, return an email / include more description in the label or emoji status indicators / multilanguage labels / spaces allowed in label but not name...)

If I want to replace an existing choice list / CSV with an entity list, and am expecting particular values returned when selecting an item from it (as before, select my name but return value my@email.com or select ❗🔴 Item Natural Name and return item_system_code), currently, the select will return the UUID.

It would be possible to add a calculate, so the first field would be the select ${selected_item} and then the calculate field ${item} would get the desired value from the entity list with a property like name_value via an instance lookup, but this adds a field eg;

type name label calculation
select_one_from_file my_item_list.csv selected_item Please select the item
calculate item The lookup instance('my_item_list')/root/item[name=${selected_item}]/name_value

From some searching, @LN previously suggested specifying a value column in the parameters, eg;

type name label parameters
select_one_from_file my_item_list.csv selected_item Please select the item value=name_value

The second option appears to be the simplest, but is there a better approach to this that I've missed? Will name be forever prohibited as an entity property?

2

What column name to use for the system-provided Entity id in the Entity List CSV served to Collect/Enketo was a difficult design decision. We ended up using name to make it relatively easy to build a select on an Entity List. By using the name column, we ensured selects would "just work" for most cases. Because the system-provided Entity id is guaranteed to be unique, it's generally a good choice for referencing a specific Entity, even if you do some initial lookup using another property.

It's true that it creates confusion because Central uses __id or even sometimes uuid for the same concept. We'll try to make that clearer.

It's also true that sometimes there's another unique "natural id" that we want to use for something. In that case, either option you've listed is fine and which you pick is a matter of preference. You may want to consider saving the Entity id in your submissions even if you don't plan to use it at first because it's guaranteed to be unique and unchanging over the lifetime of an Entity.

Yes. We will likely eventually introduce a more formal concept of a natural id -- something like making it possible to specify that a certain column is intended to be unique and to represent the identity of the Entity. At that point, we may even consider making it possible to use the name column for that value. But we won't let you directly use name in a save_to.

This is a total side note but I've noticed that XYZ_list is a common name for Entity Lists (e.g. my_item_list in your examples). This is not a problem but we did expect XYZs to be more common. I think I'll add a little note about this in the docs! In the future, we expect to show that name in more places. We'll probably eventually make it possible to specify a label that can be translated for it but that's likely a ways away!