Generating a Unique ID for beneficiaries

Many programs assign their beneficiaries externally-facing IDs. Using a combination of custom user data and a counter you can assign unique IDs to your beneficiaries. Since CommCare works offline you must create a portion of the ID that is based on the user case, since each user can be working offline simultaneously. 

 

Note on Case IDs versus Unique IDs

NOTE: CommCare assigns every case a globally unique caseid that is a 36-character long alphanumeric string. You should always use the caseid to link your data on the backend. These instructions detail how to create an easily readily, user-facing ID for beneficiaries. This should not be used to link data on the backend or for any data analysis.

STEP 1: Create custom user data prefix

  • Create a custom user property for each mobile user called "prefix"

  • Assign each user a prefix value, for example, 10, 11, 12, 13, 14 and so on. In order to determine your prefixes, you need to think about how many beneficiaries you expect each mobile user to register. In this example, we do not expect the user to register more than 10,000 beneficiaries, ever, and our prefixes and suffixes match that. 

    • You can assign this prefix when you add the mobile users individually, or in bulk. 

    • Notably, this prefix can also be a letter or a code, it does not have to be numeric.



STEP 2: Create a counter in your registration form

  • In your registration form, implement a counter as explained here. 

  • Save this property to the user case. This will increment one time every time the user opens the form. In our example, we've saved this user case property as child_count.

 

STEP 3: Create hidden value for beneficiary ID

  • Finally, in your registration form, create a hidden value called beneficiary_id that joins together the custom user property created in step 1 with the incrementer in count two using the concatenate function.

  • Since the counter will generate a number starting at 1 and constantly incrementing, you'll also want to make sure that you add 0's to the end other beneficiary ID so that all IDs are the exact same length. 

  • Save this hidden value as a case property to the case you're tracking (not to the user case)

Let's look at an example of how this would work in an app.

  • In step 1, my user case property is called prefix.

  • In step 2, the counter that I made is saved as the property child_count.

  • So finally, in step 3, the calculation that I would put into my beneficiary_id calculate condition box would be:

if(#form/child_count < 10, concat(#user/prefix, '000', #form/child_count), if(#form/child_count < 100, concat(#user/prefix, '00', #form/child_count), if(#form/child_count < 1000, concat(#user/prefix, '0', #form/child_count), "")))

If my user prefix was 12, and I registered my fifth child of the day, the ID that CommCare would generate for this child ID would be: 120005.