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. 

Generating a Unique ID

Step 1: Create a property in custom user data

• Create https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143958236 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: https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143946181/Calculations+in+Hidden+Values#Incrementing-a-counter

• 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 a hidden value to generate the unique 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 counter created in step 2 using the https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143946181/Calculations+in+Hidden+Values#Join-two-values-(%22concatenate%22)

• Since the counter will generate a number starting at 1 and constantly increment, you'll also want to make sure that you prepend 0's to the counter’s output so that all IDs are the exact same length. See the example below for more information.

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

Example

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 5th child of the day, the ID that CommCare would generate for this child ID would be: 120005.