Feature testing: Offline User Replace

With Allies’ effort of Bulk User Upload being a success (shipping in 3.16!), we’re excited at to solve a problem all CHWs and Supervisors face at some point: when you have zero connectivity, how do you replace a CHW?

In our research, we found that sometimes Supervisor will hand the phone to another CHW. This results in poor data continuity - you can not tell which CHW gave care when and reporting/targets will be inaccurate.

Our solution is for Supervisors to submit a new CHW form protected by a PIN only the Supervisor knows, but will leverage entirely offline validation of the PIN. Filling out the form takes just a few minutes, and the new CHW can start giving care immediately, training aside. They may continue using the phone entirely offline for days, weeks or months.

The magic happens when the new CHW goes to sync next. When they do, the CHT will:

  1. Upload all documents for both old and new CHWs
  2. Note the presence and time stamp of the new CHW form
  3. Create a new user for the new CHW based on the information in the form. They will be in the same place in the hierarchy and have the same role as the old CHW.
  4. For any documents submitted after new CHW form, re-parent them to the new CHW contact to maintain accurate ownership and reporting.
  5. Log out the old CHW and promptly send the new CHW a Magic Link via SMS to immediately log them back in as their new user.

We normally release code in a Feature Release (FR), but we instead have a “Beta 0” to demo today which comes before a traditional Beta 1 FR. For those that like to test the bleeding edge, see this the public GitHub ticket. For the rest of you, here’s a video showing the feature in action below.

Please post any comments or questions here. Next week I’ll update this post with how to test this in a Feature Release - stay tuned!



This is a massively useful feature - and I cannot wait to get a go ahead to share this with our partners. I did not see the execution of the magic link - which i suppose also implies the existence of an SMS gateway (this is not currently set up for the partners I have in mind).

@brian - Yay! I’m so glad to hear this feature is well received - thanks for the validation.

You are correct in assuming an SMS gateway is set up for sending the token login links. With the ease at which something like RapidPro can be setup, we’re hopeful SMS gateways will be more common in current and future deployments. Having an out of band method to log in a CHW is a powerful tool!

You are also correct in that there is currently no other option to log the user in when an SMS gateway. As we get closer to validating the Feature Release as a success and thus merging it to master, we’ll have to account for what happens when Token Login is not an option. Excellent point - thank you!

Hi @mrjones, this is indeed a great step towards simplifying user management. When we retire a CHV in our project, we normally add a flag in their couch doc to indicate that they have retired. In addition, we capture the retirement reason.

  1. Could that be something that could be captured via UI?
  2. Also, will the profile of the replaced CHV be greyed out to indicate that they are inactive?

@iesmail - more yays! Really to happy to hear this feature testing resonates with your project along with Brian’s.

While the old CHW contact will not greyed out, they will no longer be the primary contact. The new, incoming CHW will be the primary contact.

Further, if you want a supervisor to be reminded take further action on a new CHW contact, you should be able to trigger tasks by editing the tasks.js and adding a task object with at least this: { appliesTo: 'reports', appliesToType: 'contact:person:replace' }

Finally, there will be a report in CouchDB ("form": "contact:person:replace",) if you would like to take further action from a programmatic perspective.

1 Like

I’m happy to announce we have an updated demo of the offline user replace feature. While we’re still working on a public Feature Release for easy testing in a production environment, we’re continuing to develop in the open and have updated our testing steps for anyone eager enough to run it in development mode today.

The items that have been improved since our last update are:

  • Better user nomenclature: Before user bob would be replaced by user aziz but the new user would be called bob-replacement. Now, the new user will be called USERNAME-FOURNUMBERS, so Aziz might be aziz3828. This ensures we can safely create a new user and not conflict with an existing user who also might be named Aziz.
  • Token login links: A key feature of Offline Replace is that both supervisors and CHWs do not know, and do not need to know, their password. Token login links facilitates logging in without any help from a central office or an online CHT admin user.
  • Primary Contact - When users are replaced, the supervisor, or anyone else looking at the data, may not know who the current CHW is for a given area. By ensuring the new CHW is the primary contact, this is easy to tell.
  • Simplified Form - Before, a supervisor had to fill out 6 fields about the new CHW. Critically, this including re-entering the phone number and re-entering the role. Given these will not change, they are now filled out for you and are un-editable. This reduces errors and decreases time to fill out the form.
  • Better Warning - The first screen that the supervisor sees makes it very clear that this a special activity which only a supervisor can complete. Given every CHW will be able to view the form, it’s good to have correct and strong messaging here.
  • More Contextual Menu - In the prior version, you would navigate to the CHW area and choose “New Person”. Now you navigate to the specific CHW and choose “Replace User”. This is a less ambiguous and less likely to be chosen by accident by a CHW.

Here’s a ~4 minute demo of the latest build - enjoy!



@mrjones this is such a huge step in the right direction. The feature will definitely ease supervisor CHV management and am here for it! I can already visualize the excitement from the partner once this is ready! :clap: :clap:

Exciting feature indeed @mrjones. I am concerned about locking the phone number data field of the CHW. I have seen some contexts were CHWs prefer and use their own phone numbers for the CHW service delivery work and hence once they leave; they leave with the SIM card and its associated number. Is this context an outlier or is it common in other deployments done by community members?


@sue - I very much welcome your enthusiasm! Let me know if you have any questions. As well, any partners/MoH’s you know that might be interested in this feature, should be ready to upgrade to the FR. This will effectively be upgrading to 3.16.

@Jane_Katanu - so great to hear about different use cases that may not be compatible with our current proposed workflow! It’s good to appreciate differences so we can maybe add revisions in the future to accommodate them. While far from exhaustive, my research didn’t uncover the use case you described. I’d love to hear from others though! Do you know how common the personal SIM use in the deployment you’re thinking of?

While we’re here, so I understand the situation correctly, the CHW’s personal SIM flow might be:

  1. CHW A inserts their SIM into MoH provided phone, they commence work as a CHW
  2. CHW A needs to leave work, but there is no connectivity. The supervisor opts to use the offline replace feature
  3. CHW A removes SIM and gives MoH provided phone to supervisor
  4. Supervisor finds CHW B as a replacement for CHW A
  5. The replace user form is filled out by the supervisor, specifying the new number on CHW B’s SIM
  6. CHW B inserts their SIM into the MoH provided phone
  7. At some point in the future CHW B synchronizes all of the documents and gets logged out.
  8. The token login link is sent to to CHW B’s new phone number, they receive and click it

An alternate step might be that the supervisor provides an MoH SIM in step 6, but the work flow would remain unchanged.

I’d love to hear about any other restrictions you’re facing, as well as any non-restrictions! Maybe, for example, you’re only interested in the “CHW Replace” aspect and the “offline” part is not interesting?


@Jane_Katanu I will agree with you on this. Most projects actually prefer that CHVs use their own sim cards to avoid multiple devices in the hands of 1 CHV. It is prudent not to lock the phone number field to allow a supervisor to input new CHV number.

@mrjones Good news! We socialized MoH Uganda with this feature and am happy to report that they are interested and are open to discussing on an upgrade. The initial design proposal was to have a muting workflow for CHVs by the supervisors, this would be a temporary measure as they planned on replacements. This feature will support the supervisor to do immediate replacements without worrying about moving HHs or HH missing out on services. cc. @brian

@sue - that is such great news about MoH Uganda’s interest in this feature release!

Also - thanks very much for the feedback about the ability to change the phone number during the replace process. I’m working with Allies engineers, but the Replace User form (see replace_user.xlsx in the FR branch) is of course editable, so I’m hoping we can just opt to make the phone fields not have read_only as true() and have it all work as expected! This way deployments can choose to have it read only or editable, which ever is most helpful for their workflow.

1 Like

@sue and @Jane_Katanu - Hi again! I’m back with a quick update that I spoke to @jkuester and @mokhtar (Allies engineers) and they confirmed that the phone number can easily be made editable and it will be done in the replace_user.xlsx form as I suspected.


Hi all! This week Allies made some improvements to the Offline User Replace FR. While we don’t have a new beta just yet (Beta 4 next week!), I did want to give give a demo showing the ability to change the supervisor authentication code as well as change the phone number from read only to be editable.

Allies decided to use the native Enketo forms that powers all user input on the CHT so that each deployment can customize how user replace form should work based of their needs.

Here’s video walking through (<4 min) how these customization will be done in practice:


Hey again!

In one of our recent presentations of this feature to a partner, they expressed concern about the need to synchronize twice. There was a reasonable concern about the following scenario:

  1. CHW A leaves and is replaced by CHW B
  2. CHW B does patient visits, does of 1 of 2 synchronizations
  3. CHW B forgets they must synchronization a 2nd time
  4. CHW B does more patient visits and synchronizes at the end of the month
  5. CHW B gets forcibly logged out, likely loosing the reports from the prior step
  6. CHW B receives the token login link over SMS

To protect against this we have update the Feature Release to have a client side logout feature, in which the client knows to log itself out as soon as it is done sending all the reports. This means the steps now look like this:

  1. CHW A leaves and is replaced by CHW B
  2. CHW B does patient visits, and then does the first and only required synchronization
  3. CHW B gets forcibly logged out, ensuring no data is lost
  4. CHW B receives the token login link over SMS

Here’s a video showing off the updated flow:


We don’t have this built into Beta 5, but expect to have this next week - stay tuned!

1 Like

For those following along hoping for an up to date beta 5 of this release, sorry for the very long silence! There was an internal push to get CHT 4.0.0 released and this feature ended up getting pushed out to be after 4.0.0.

We’re very much still working on this feature and have 112 commits, 110 files updated and over 200 comments on the PR. It is currently slated to be released in 4.1.0!