Officially support ODK Central for offline stock movements

[jniles]

We released a tag v1.21.3-pcima with support for ODK Central. This was to handle the PCIMA project's need to track stock offline with ODK forms. I propose we formalize this support in BHIMA and merge the functionality into master. It will make support easier going forwards.

We've released a module @ima-worldhealth/odk-central-api that should offload the ODK Central API functionality into its own tested module. This means we can focus on rewriting the import.js functionality to bring stock movements into BHIMA from data collected in the ODK Central Server.

---

One thing to think about - we could migrate the pepkits project to using this version of BHIMA/Central and have another project using this functionality in addition to the PCIMA project.

[jniles]

Similarly, we might be able to improve our aggregate stock consumption by providing telephones for users in the health centers to use to record their stock consumption information. This would ensure that we have more accurate data from the FOSAs in our Health Zone stock tracking project.

Basically, the following projects would greatly benefit from this:

• OFDA Pepkits III
• ASSR Stock Movement Tracking in Tshikaji Health Zone
• UNICEF PCIMA

[jniles]

Design

This describes the rough design of the BHIMA ODK link. It is useful to look over the ODK Central API documentation.

A BHIMA enterprise is an ODK Central project

When you install BHIMA, you'll be allowed to optionally add the configuration for an ODK Central Server. This would be the username, password, and server URL. This user must be an administrative user to create new projects. A project on ODK Central would be created for the enterprise, and the odk_project_id would be stored in some table, probably its own table aside. Currently, we don't model multiple enterprises in BHIMA.

Information we need to store in BHIMA so far:

• odk_central_url
• odk_admin_user
• odk_admin_password
• odk_project_id

A BHIMA user (with access to a depot) is an ODK Central user

When someone creates a user in BHIMA, we should create a user in ODK Central with their email address. It's a 1-1 mapping. But @jniles, you cry, email addresses have to be unique in ODK Central! What happens if I want to have a user account on two BHIMA instances?!

Well... this works:

So, we just append +${enterprise_name} to the email address and you can make one million accounts of the single email address. We save the odk_user_id for each user in BHIMA. Simple.

This user will have access to the forms specified by their user_depot permission mapping in BHIMA. Each time a user's depot permissions are updated, we'll need to update their ODK Central permissions. This might be tricky, but the API makes it seem doable.

For each user, we'll need to store:

• odk_user_id
• odk_user_password ?

A BHIMA depot creates three ODK Central forms - entry, exit, and routine inventory

We need to implement three forms for each depot - entry, exit, and routine inventory. I propose that these be called ${depot.label} - Stock Entry, ${depot.label} - Stock Exit, ${depot.label} - Routine Inventory.

The first page of each form should provide the BHIMA installation name, the depot name, the timestamp the information in the form was updated.

For both entry and exit, we'll want to specify the origin depot or the destination depot. In both cases, the user should have permission to see that depot. Question: For stock entries, should we require that users select from a list of transfer documents destined to the destination depot?

When a BHIMA user is given permission to access a depot in BHIMA, they are also given permission to that depot's forms in ODK Central.

Each of these depot forms will have a list of all BHIMA products in them, that can be looked up via a barcode scan. These will be in an external select for convenience.

When the stock in a depot changes (either via an entry or an exit), this form should be updated with a new version.

For each depot, we'll need to store:

• odk_entry_form_id
• odk_exit_form_id
• odk_inventory_form_id

[mbayopanda]

The design is great, it presents how things have to be done for a real benefit of both BHIMA and ODK.

The doability is a real challenge because we have to go deep inside the ODK API and find all answers that we need.

Here my point of view according points :

A BHIMA enterprise is an ODK Central project

I had a concern with existing project in ODK Central, but if we have to consider the new created one related to a BHIMA instance its okay to me.

A BHIMA user (with access to a depot) is an ODK Central user

It is okay to me.

A BHIMA depot creates three ODK Central forms - entry, exit, and routine inventory

So we have to add 3 forms for each bhima depot,

• 30.000 forms to add in the case of PCIMA
• 30.000 forms to add in the case of PEPKITS
• etc.

Our ODK Central will had to deal with a huge number of forms.

Question: For stock entries, should we require that users select from a list of transfer documents destined to the destination depot?

In the case the exit was made with ODK Collect, I don't know if the user will have the document ID (in case of zone where there is not BHIMA: FOSA). So It can be difficulet to
select from a list of transfer documents since the user don't know the concerned transfer document.

@jniles this is a great feature to add in BHIMA.

The next release with that can be BHIMA 3.X :-)