Sentinel needs to support these patient_id use cases

[SCdF]

There are various ways that patient_id gets set, we need to support them all. We currently support:

• from SMS -> new patient id, new contact
• migration -> existing internal[1] patient id onto new contact

We need to also support:

• from SMS -> existing external][1] patient id onto new contact
• from Enketo -> new patient id onto existing contact. This is covered by Ability to add unique patient_id to contacts created using app #3000
• using Enketo -> existing external[1] patient id onto new contact.

This ticket may have code against it, or it may just link to other tickets that take care of this.

[1] internal being a patient id we generate, external being one that we are given. At least for this ticket we are presuming that a) we are given unique patient ids, and b) they fit whatever validation scheme is configured.

[SCdF]

We will need to change sentinel so it processes person documents. We should remove the document restriction, and just update all of the existing transitions to ignore documents appropriately (some may already do so by the nature of their filters)

[abbyad]

If we were to use the same trigger, the person creation forms could be easily modified to result in a doc.form field. The resulting config could use this form value to assign the trigger to the doc:

"registrations": [
    {
      "form": "person_create",
      "events": [
        {
          "name": "on_create",
          "trigger": "add_patient",
          "params": "",
          "bool_expr": ""
        }
      ]
    },

[SCdF]

Step 1: change sentinel so it passes allows transitions to transition all types of documents.

@garethbowen please review and merge medic/medic-sentinel#111 when ready.

I'm keeping this ticket open and working on it, but let's get this chunk out and done with.

[garethbowen]

Nice. Merged. Assigning back to you,

[SCdF]

I think adding patient_id to contacts created in Enketo is a separate transition, @abbyad would you agree? You don't actually expect any kind of registration action to be performed right? You'd just expect that if you created a patient contact in the UI a patient_id would be generated (unless you provided one).

[SCdF]

Actually @abbyad would you expect this to just run on any person that was created? That would generate ids for CHPs as well, right?

[SCdF]

@abbyad for the third bullet point (using Enketo -> existing external[1] patient id onto new contact.) do we need to do anything here? Can enketo forms already be configured to store something at doc.patient_id in those situations?

[abbyad]

I think adding patient_id to contacts created in Enketo is a separate transition, @abbyad would you agree? You don't actually expect any kind of registration action to be performed right? You'd just expect that if you created a patient contact in the UI a patient_id would be generated (unless you provided one).

Correct. Although I don't see harm in it coming from the same transition add_patient, it could be a separate transition add_patient_id (but not that name to avoid confusion with previous trigger of same name).

Actually @abbyad would you expect this to just run on any person that was created? That would generate ids for CHPs as well, right?

Projects that use IDs for CHWs are more likely to use an external ID, such as their "Health Worker Registry" number. Given that, I don't think we would need to create an ID for everyone in every project. If we did we might exhaust possible numbers a bit quicker, and it would mean that app workflow only projects get an unnecessary ID for patients. That may not be a problem, and may make things more consistent that every person and place has a short form ID to refer to it.

@abbyad for the third bullet point (using Enketo -> existing external[1] patient id onto new contact.) do we need to do anything here? Can enketo forms already be configured to store something at doc.patient_id in those situations?

Yes, we can already do this. In this case we couldn't verify that it is unique, but that is likely fine.

[SCdF]

Added a WIP branch to check in code I'm working through that allows support for third party ids: https://github.com/medic/medic-sentinel/tree/3166-external-id-support

[SCdF]

@garethbowen can you please review the code: medic/medic-sentinel#116

I have no idea where to put the following documentation. I started writing out markdown documentation to cover things, and then realised that it's sort of half-covered by kanso.json. Things you can specifically configure are sort of covered, but also sort of not (eg a short phrase is encouraged by the format), and there isn't a way to document things that aren't specifically tied to a static piece of configuration.

Additional documentation

add_patient_id

add_patient_id event has been deprecated in favour of add_patient

add_patient

Can now be passed an externally generated patient id instead of generating one. Can be configured like so:

{
  "name": "on_create",
  "trigger": "add_patient",
  "params": {
    "patient_id": "external_id"
  }
}

The document passed would then be expected to have a patient id in the fields.external_id field.

If params.patient exists but that field cannot be found on the document a sys.no_provided_patient_id error is recorded and SMS sent.
if the given external patient_id is not unique a sys.provided_patient_id_not_unique error is recorded and SMS sent.

[abbyad]

I don't think there is sufficient place to document this in kanso.json. We can explain "triggers", but not each one individually there. Linking to our doc from there would be useful (eg "more info on triggers"), as is being done here for contact summary.

[SCdF]

Also: #3260

Just some message changes, with a note to talk to @abbyad about how we should change the default config (and others??) to support auto-extending ids.

[SCdF]

OK let's get this all clear, because there are lots of fragmented things flying around.

@garethbowen, can you approve (you may have seen this stuff before):

• Sentinel changes: External ID Support medic-sentinel#116
• Fixing some documentation / translation in Medic, including Changes.md documenation: Message changes #3260
• Adding official documentation (and stubs) in the right home: For medic/medic-webapp#3166 medic-docs#10

Once these are cool I'm going to merge medic/medic-sentinel#117 into medic/medic-sentinel#116, then hopefully be able to test properly with a good local environment, and then merge into master.

[garethbowen]

@SCdF Nice one. One small change requested on each of the last two PRs. Merge when fixed!

[SCdF]

OK everything is merged with the exception of the documentation stuff, which Gareth and I will talk about on Monday, and then I'll almost certainly merge it then.

[SCdF]

OK merged documentation. Donnnnnnnnnnnne.

[ngaruko]

Any clue on how to AT this @abbyad ?

[abbyad]

Has this already been released?

[ngaruko]

Looks like it has been release @abbyad....

[SCdF]

Yes this has been released, looks like 2.11.1. However, it hasn't been AT'd ;-)