Server-side reconciliation based on Form Submission

[f-odhiambo]

Background
An out-of-catchment health facility refers to a case where a child seeks immunization services at a facility other than the one where they were registered(aka home facility). The old ZEIR app supported a form where the following details would be provided:

1. Child’s ZEIR ID
2. Date of service to capture the date when the vaccinations were given.
3. Checkboxes allowing selection of vaccination given

The “Record out of catchment vaccination” form was attached to the drawer menu, as shown in the screenshot below. The next screenshot shows the details captured on the form.

Once the details were submitted and the app synced, the system would update the vaccinations to the respective child profile on the server side based on the provided ZEIR ID. The vaccination details would show up the next time the child profile was opened at the child's home facility. This would require the home facility device to sync down new details before the additional vaccinations given show. Please reference the constraints on the Out of Area data dictionary here.

Happy Path

1. Details can be captured either online or offline
2. All the details in the form are mandatory
3. Post save, the record will be reconciled on server-side

Assumptions

1. The Child was enrolled in the program using a FHIR Core based EIR app (Or any other applicable app)
2. The Child was issued with an appropriate Identifier that can be used for a search query to retrieve their records
3. A CarePlan with Tasks was also generated from a PlanDefinition describing the Immunization task with a schedule

Current approach to vaccine schedule generation

1. Register a child in the app
2. Post registration, $lite is invoked against the child's ID and the appropriate Immunization PlanDefnition schedule
3. A CarePlan is generated together with a list of Tasks that will be fulfilled to represent the different vaccines their child should receive over time

Proposed solution

Form Submission

1. The Form should have all the vaccines coded using the same nomenclature or codified in the same manner as the current PlanDefinition. On form authoring, this should be factored in
2. The data will be captured and stored in a QuestionnaireResponse
3. On successful data sync, the server will process the QuestionnaireResponse data to reconcile the child record

Sample Questionnaire

{"resourceType":"Questionnaire","language":"nb-NO","id":"24672","status":"draft","publisher":"NHN","meta":{"versionId":"4","lastUpdated":"2023-06-23T13:06:09.550+00:00","profile":["http://ehelse.no/fhir/StructureDefinition/sdf-Questionnaire"],"security":[{"system":"urn:oid:2.16.578.1.12.4.1.1.7618","code":"3","display":"Helsehjelp"}],"tag":[{"system":"urn:ietf:bcp:47","code":"nb-NO","display":"Bokmål"}]},"contact":[{"name":"http://www.nhn.no"}],"subjectType":["Patient"],"extension":[{"url":"http://helsenorge.no/fhir/StructureDefinition/sdf-sidebar","valueCoding":{"system":"http://helsenorge.no/fhir/ValueSet/sdf-sidebar","code":"1"}},{"url":"http://helsenorge.no/fhir/StructureDefinition/sdf-information-message","valueCoding":{"system":"http://helsenorge.no/fhir/ValueSet/sdf-information-message","code":"1"}},{"url":"http://helsenorge.no/fhir/StructureDefintion/sdf-itemControl-visibility","valueCodeableConcept":{"coding":[{"system":"http://helsenorge.no/fhir/CodeSystem/AttachmentRenderOptions","code":"hide-help","display":"Hide help texts"},{"system":"http://helsenorge.no/fhir/CodeSystem/AttachmentRenderOptions","code":"hide-sublabel","display":"Hide sublabel texts"}]}},{"url":"http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-targetStructureMap","valueCanonical":"https://fhir.zeir.smartregister.org/fhir/StructureMap/24719"}],"item":[{"linkId":"fb910e26-d670-404d-ddce-c457e6814a39","type":"string","text":"Patient's Idenitifier","code":[{"code":"identifier","display":"Patient's Identifier","system":"urn:uuid:92b4f66b-7d49-4f16-869f-4d190cc00882","id":"726fbc83-e655-4b7c-d52d-650e5008283d"}],"required":false,"_text":{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/rendering-markdown","valueMarkdown":"Patient's Idenitifier"}]}},{"linkId":"1edc6968-25f3-4e1c-fd7b-faf125c3469e","type":"string","text":"Patient Age (Yrs)","required":false},{"linkId":"under5-vaccines","text":"Child Vaccines","type":"choice","enableWhen":[{"question":"1edc6968-25f3-4e1c-fd7b-faf125c3469e","operator":"<=","answerString":"16"}],"required":false,"answerOption":[{"valueCoding":{"id":"4240d40f-4b86-41be-b6f4-31a66c36b0e0","system":"http://www.snomed.ct","code":"001","display":"BCG"}},{"valueCoding":{"id":"481a6a6a-6033-4d14-eaa3-f9930a291e92","system":"http://www.snomed.ct","code":"002","display":"OPV 0"}},{"valueCoding":{"id":"a73e8c17-287a-4d4b-bcb4-5adfb4248133","system":"http://www.snomed.ct","code":"003","display":"OPV 1"}},{"valueCoding":{"id":"5bc01095-785f-49ff-87f5-dcd5497b30c7","system":"http://www.snomed.ct","code":"004","display":"PCV 1"}},{"valueCoding":{"id":"4eb41df9-f3a5-4f50-f705-b5d5dcff769d","system":"http://www.snomed.ct","code":"005","display":"Penta 1"}},{"valueCoding":{"id":"0ab08eb0-70a4-4567-f1c5-f96fb30dcf11","system":"http://www.snomed.ct","code":"006","display":"Rota 1"}},{"valueCoding":{"id":"7da4ec27-4776-4f66-856a-b852d7155f96","system":"http://www.snomed.ct","code":"007","display":"OPV 2"}},{"valueCoding":{"id":"03bb452d-b295-4827-e82f-7c0772876542","system":"http://www.snomed.ct","code":"008","display":"PCV 2"}},{"valueCoding":{"id":"bf69c4d0-cab2-4c96-9d18-e083bed3ebf5","system":"http://www.snomed.ct","code":"009","display":"Penta 2"}},{"valueCoding":{"id":"42298c0e-a764-423f-8507-477b5aeddd9a","system":"http://www.snomed.ct","code":"010","display":"Rota 2"}},{"valueCoding":{"id":"349aa178-ea90-4bf9-bfe8-c6f7d6d7f4ab","system":"http://www.snomed.ct","code":"011","display":"OPV 3"}},{"valueCoding":{"id":"f7f99065-ea84-4063-8fc8-3d3929c73e3b","system":"http://www.snomed.ct","code":"012","display":"PCV 3"}},{"valueCoding":{"id":"ca95ec5a-3823-4a0f-ef09-5fbd14a867ea","system":"http://www.snomed.ct","code":"013","display":"Penta 3"}},{"valueCoding":{"id":"17927b8d-4cd9-48ef-8e8d-7cffd842320b","system":"http://www.snomed.ct","code":"014","display":"IPV"}},{"valueCoding":{"id":"51457820-8aae-446e-9953-e7916ddf7c2d","system":"http://www.snomed.ct","code":"015","display":"OPV 4"}},{"valueCoding":{"id":"447c79e8-bf44-41dd-8798-ab07185f45a5","system":"http://www.snomed.ct","code":"016","display":"MR 1"}},{"valueCoding":{"id":"9855dba4-cd40-4799-ec0f-e553ceb92e92","system":"http://www.snomed.ct","code":"017","display":"MR 2"}}],"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl","valueCodeableConcept":{"coding":[{"system":"http://hl7.org/fhir/ValueSet/questionnaire-item-control","code":"check-box"}]}}]},{"linkId":"over5-vaccines","text":"Adult Vaccines","type":"choice","enableWhen":[{"question":"1edc6968-25f3-4e1c-fd7b-faf125c3469e","operator":">","answerString":"16"}],"required":false,"answerOption":[{"valueCoding":{"id":"447c79e8-bf44-41dd-8798-ab07185f45a5","system":"http://www.snomed.ct","code":"9001","display":"AstraZeneca Dose 1"}},{"valueCoding":{"id":"9855dba4-cd40-4799-ec0f-e553ceb92e92","system":"http://www.snomed.ct","code":"9002","display":"Sinopharm Dose 1"}},{"valueCoding":{"id":"66af9425-d8ef-496b-8c08-ec5e4e83be5f","system":"http://www.snomed.ct","code":"9003","display":"Pfizer Dose 1"}},{"valueCoding":{"id":"0adae0b5-6852-402e-a15d-71ec62d86468","system":"http://www.snomed.ct","code":"9004","display":"Moderna Dose 1"}},{"valueCoding":{"id":"5ae086c4-a042-4087-8c9b-8eb194339d21","system":"http://www.snomed.ct","code":"9005","display":"Johnson & Johnson Dose 1"}},{"valueCoding":{"id":"e3b22394-b087-4296-89d2-1d473c6141cd","system":"http://www.snomed.ct","code":"9006","display":"AstraZeneca Dose 2"}},{"valueCoding":{"id":"ddcb9bbc-607d-4de9-fd8c-ce49c27e6f4d","system":"http://www.snomed.ct","code":"9007","display":"Pfizer Dose 2"}},{"valueCoding":{"id":"6dc97495-2c11-4729-9131-def52f968176","system":"http://www.snomed.ct","code":"9008","display":"Moderna Dose 2"}},{"valueCoding":{"id":"646898a8-b689-491b-861d-b04445aa12da","system":"http://www.snomed.ct","code":"9009","display":"Sinopharm Dose 2"}},{"valueCoding":{"id":"6b71dae6-a854-4997-8add-0f562a63ef1e","system":"http://www.snomed.ct","code":"9010","display":"AstraZeneca Booster"}},{"valueCoding":{"id":"8be044e6-7950-4c7b-8839-9bb798a9554f","system":"http://www.snomed.ct","code":"9011","display":"Pfizer Booster"}},{"valueCoding":{"id":"94d6eae1-7796-4e9d-de5c-ef9f09c64def","system":"http://www.snomed.ct","code":"9012","display":"Moderna Booster"}},{"valueCoding":{"id":"8fdfd8db-b1ed-45c4-9e8b-d9c61dcaf4e2","system":"http://www.snomed.ct","code":"9013","display":"Johnson & Johnson Booster"}}],"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl","valueCodeableConcept":{"coding":[{"system":"http://hl7.org/fhir/ValueSet/questionnaire-item-control","code":"check-box"}]}}]},{"linkId":"4f6ad965-e243-406f-8588-9e9abd32deab","type":"date","text":"Date of Immunization","extension":[{"url":"http://ehelse.no/fhir/StructureDefinition/sdf-maxvalue","valueString":"today()"}],"required":false}]}

Sample QR for Child

{"resourceType":"QuestionnaireResponse","status":"in-progress","item":[{"linkId":"49200799-3a0d-4819-aa62-fc9e31638d93","text":"Patient's Idenitifier","answer":[{"valueString":"23123213"}]},{"linkId":"1edc6968-25f3-4e1c-fd7b-faf125c3469e","text":"Patient Age (Yrs)","answer":[{"valueString":"14"}]},{"linkId":"under5-vaccines","text":"Child Vaccines","answer":[{"valueCoding":{"code":"001","display":"BCG","system":"http://www.snomed.ct"}},{"valueCoding":{"code":"002","display":"OPV 0","system":"http://www.snomed.ct"}}]},{"linkId":"over5-vaccines","text":"Adult Vaccines"},{"linkId":"recorded-date","text":"Date of Immunization","answer":[{"valueDate":"2023-08-01"}]}]}

Sample QR for Adult

{"resourceType":"QuestionnaireResponse","status":"in-progress","item":[{"linkId":"49200799-3a0d-4819-aa62-fc9e31638d93","text":"Patient's Idenitifier","answer":[{"valueString":"342333"}]},{"linkId":"1edc6968-25f3-4e1c-fd7b-faf125c3469e","text":"Patient Age (Yrs)","answer":[{"valueString":"21"}]},{"linkId":"under5-vaccines","text":"Child Vaccines"},{"linkId":"over5-vaccines","text":"Adult Vaccines","answer":[{"valueCoding":{"code":"9001","display":"AstraZeneca Dose 1","system":"http://www.snomed.ct"}},{"valueCoding":{"code":"9006","display":"AstraZeneca Dose 2","system":"http://www.snomed.ct"}}]},{"linkId":"recorded-date","text":"Date of Immunization","answer":[{"valueDate":"2023-08-09"}]}]}

Serverside reconciliation

Happy Path

1. The server should be able to consume and interpret the data on the QuestionnaireResponse
2. Get the Patient's details via $everything i.e. https://$hapi_url/Patient/ID/$everything
3. Get all tasks and fetch all tasks that have the matching Immunization codable concept

    "code": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "33879002",
                "display": "Administration of vaccine to produce active immunity (procedure)"
            }
        ]
    },

6. From the matching Task records, query and mark as completed all the tasks that have been fulfilled as matching the submitted QuestionnaireReponse based on the Immunization codes that correspond to Task.reasonCode
7. Create an Encounter to mark this event has occurred based

Reason Code

  "reasonCode": {
       "coding": [
           {
               "system": "http://snomed.info/sct",
               "code": "42284007",
               "display": "BCG vaccination"
           }
       ],
       "text": "BCG"
   },

Status

   "status": "completed",

Completion date

   "lastModified": "2023-08-10T14:46:45+03:00",

Edgecase to think about

1. What happens if a matching identifier is not found on the server?
2. The issued vaccine code is not part of the list in the program offering?
3. A user received a vaccine but was already vaccinated for the same dose or has a duplicate recording of the same event?

[pld]

Cool this looks reasonable. Can we scope this not assume that the linked resources are a Task? Maybe there's a way to include in the Q and QR something that indicates the resource type to search within?

Also, I'm assuming that this would not try to do any business logic beyond the link to tasks, like:
a. if the form submitted shows that the user has completed their 2nd round of vax course but they haven't completed their 1st, it would go ahead and record the task for the 2nd round as complete without worry about the 1st round, which on device would nomally be a precondition
b. if post reconciliation completes all the tasks in the careplan, the careplan status would not change, that would wait for the completed tasks to be synced down and update the local device tasks, then a background job to run to complete that careplan, then the careplan to be synced back up -- basically there would be a period of time during which the careplans on the server are in the incorrect state

Some thoughts on the edge cases you mentioned:

1. one approach, we could add some sort of flag to the QR that makes it visible in a dashboard and the project admin is expected to do a manual review
2. same as 1
3. we could drop the newly server-side created records and treat it as 1

Hah, I guess there's a pattern to my thinking here, if we get into trouble we give up and flag for manual review, which feels like a reasonable approach in all of these scenarios where there is not (that I cant see) a deterministic way to guarantee we make the correct decision

[pld]

I wrote up a scope for the web service portion of this here, onaio/fhir-tooling#67, we do need an example QR for parts of this but it's ready to be worked on now even without that

[f-odhiambo]

Here is a sample Questionnaire and QR for the Out of service

{
  "resourceType": "Questionnaire",
  "language": "nb-NO",
  "status": "draft",
  "publisher": "NHN",
  "meta": {
    "profile": [
      "http://ehelse.no/fhir/StructureDefinition/sdf-Questionnaire"
    ],
    "tag": [
      {
        "system": "urn:ietf:bcp:47",
        "code": "nb-NO",
        "display": "Bokmål"
      }
    ],
    "security": [
      {
        "code": "3",
        "display": "Helsehjelp (Full)",
        "system": "urn:oid:2.16.578.1.12.4.1.1.7618"
      }
    ]
  },
  "contact": [
    {
      "name": "http://www.nhn.no"
    }
  ],
  "subjectType": [
    "Patient"
  ],
  "extension": [
    {
      "url": "http://helsenorge.no/fhir/StructureDefinition/sdf-sidebar",
      "valueCoding": {
        "system": "http://helsenorge.no/fhir/ValueSet/sdf-sidebar",
        "code": "1"
      }
    },
    {
      "url": "http://helsenorge.no/fhir/StructureDefinition/sdf-information-message",
      "valueCoding": {
        "system": "http://helsenorge.no/fhir/ValueSet/sdf-information-message",
        "code": "1"
      }
    },
    {
      "url": "http://helsenorge.no/fhir/StructureDefintion/sdf-itemControl-visibility",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://helsenorge.no/fhir/CodeSystem/AttachmentRenderOptions",
            "code": "hide-help",
            "display": "Hide help texts"
          },
          {
            "system": "http://helsenorge.no/fhir/CodeSystem/AttachmentRenderOptions",
            "code": "hide-sublabel",
            "display": "Hide sublabel texts"
          }
        ]
      }
    }
  ],
  "id": "01dddee0-1c10-47ac-8b75-5fbea790a15a",
  "item": [
    {
      "linkId": "3ec7e49b-b60f-4e67-f5ed-bd7d18cf3943",
      "type": "string",
      "text": "ZEIR ID",
      "required": false
    },
    {
      "linkId": "7a27ab63-6a6f-499d-8a70-a356cf23da38",
      "type": "date",
      "text": "Date of Service",
      "extension": [
        {
          "url": "http://ehelse.no/fhir/StructureDefinition/sdf-maxvalue",
          "valueString": "today()"
        }
      ],
      "required": false
    },
    {
      "linkId": "d9c2e3e3-8415-44bd-8317-f573586a4943",
      "type": "choice",
      "text": "Which vaccinations were provided?",
      "required": false,
      "answerOption": [
        {
          "valueCoding": {
            "id": "3869a41b-6978-4c43-979f-54ef77cfa83e",
            "code": "001",
            "system": "http://snomed.info/sct",
            "display": "OPV"
          }
        },
        {
          "valueCoding": {
            "id": "3e7d846b-b278-4bbf-c4f4-d13f083ebe5d",
            "code": "002",
            "system": "http://snomed.info/sct",
            "display": "BCG"
          }
        },
        {
          "valueCoding": {
            "id": "5746775c-bc71-4e11-85fd-ede99915671f",
            "code": "003",
            "system": "http://snomed.info/sct",
            "display": "OPV 1"
          }
        },
        {
          "valueCoding": {
            "id": "0ef61589-f051-4548-87e9-da54ef0d583d",
            "code": "004",
            "system": "http://snomed.info/sct",
            "display": "Penta 1"
          }
        },
        {
          "valueCoding": {
            "id": "803a834f-9f98-4842-9f02-473df681bb57",
            "code": "005",
            "system": "http://snomed.info/sct",
            "display": "PCV 1"
          }
        },
        {
          "valueCoding": {
            "id": "d8e53818-51ca-4d0c-8f03-a27e47d30271",
            "code": "006",
            "system": "http://snomed.info/sct",
            "display": "Rota 1"
          }
        },
        {
          "valueCoding": {
            "id": "5b2e0a9f-3bcd-4c56-cdf8-89bfa656ecbb",
            "code": "007",
            "system": "http://snomed.info/sct",
            "display": "OPV 2"
          }
        },
        {
          "valueCoding": {
            "id": "e75d4a12-836f-4aad-c46e-bdff4050b4fb",
            "code": "008",
            "system": "http://snomed.info/sct",
            "display": "Penta 2"
          }
        },
        {
          "valueCoding": {
            "id": "22e5c76e-1fee-4055-84d3-7dcce6cdc256",
            "code": "009",
            "system": "http://snomed.info/sct",
            "display": "PCV 2"
          }
        },
        {
          "valueCoding": {
            "id": "04ee6c59-90a2-4f70-b081-b1c7f23f074e",
            "code": "010",
            "system": "http://snomed.info/sct",
            "display": "Rota 2"
          }
        },
        {
          "valueCoding": {
            "id": "60ecaadd-8db1-4518-beb7-36105f9862db",
            "code": "011",
            "system": "http://snomed.info/sct",
            "display": "OPV 3"
          }
        },
        {
          "valueCoding": {
            "id": "d6530433-e4a7-4d72-8aef-8295957fbaeb",
            "code": "012",
            "system": "http://snomed.info/sct",
            "display": "PCV 3"
          }
        },
        {
          "valueCoding": {
            "id": "f4792b9f-f54c-4104-8011-9e3b7d8ad6ac",
            "code": "013",
            "system": "http://snomed.info/sct",
            "display": "Penta 3"
          }
        },
        {
          "valueCoding": {
            "id": "4449a8b2-b523-4326-9d38-7debb176bfe7",
            "code": "014",
            "system": "http://snomed.info/sct",
            "display": "IPV"
          }
        },
        {
          "valueCoding": {
            "id": "1c159f21-7370-4ea1-85f9-bc3bd8486a4f",
            "code": "015",
            "system": "http://snomed.info/sct",
            "display": "MR 1"
          }
        }
      ],
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/ValueSet/questionnaire-item-control",
                "code": "check-box"
              }
            ]
          }
        }
      ]
    }
  ]
}

Here is a sample QR for the Out of service

{
   "resourceType": "QuestionnaireResponse",
   "id": "6fbf1a75-0220-4ca4-9fd4-d9ea7c570b64",
   "questionnaire": "Questionnaire/OutOfService",
   "status": "completed",
   "subject": {
      "reference": "Patient/b298f30a-5434-4ab6-a88e-10a15d3e74e7"
   },
   "authored": "2023-09-14T10:32:58+03:00",
   "item": [
      {
         "linkId": "3ec7e49b-b60f-4e67-f5ed-bd7d18cf3943",
         "text": "ZEIR ID",
         "answer": [
            {
               "valueString": "987239487"
            }
         ]
      },
      {
         "linkId": "7a27ab63-6a6f-499d-8a70-a356cf23da38",
         "text": "Date of Service",
         "answer": [
            {
               "valueDate": "2023-10-13"
            }
         ]
      },
      {
         "linkId": "d9c2e3e3-8415-44bd-8317-f573586a4943",
         "text": "Which vaccinations were provided?",
         "answer": [
            {
               "valueCoding": {
                  "code": "001",
                  "display": "OPV",
                  "system": "http://snomed.info/sct"
               }
            },
            {
               "valueCoding": {
                  "code": "002",
                  "display": "BCG",
                  "system": "http://snomed.info/sct"
               }
            }
         ]
      }
   ]
}

QR

{
   "resourceType": "QuestionnaireResponse",
   "id": "6fbf1a75-0220-4ca4-9fd4-d9ea7c570b64",
   "questionnaire": "Questionnaire/OutOfService",
   "status": "completed",
   "subject": {
      "reference": "Patient/b298f30a-5434-4ab6-a88e-10a15d3e74e7"
   },
   "authored": "2023-09-14T10:32:58+03:00",
   "item": [
      {
         "linkId": "3ec7e49b-b60f-4e67-f5ed-bd7d18cf3943",
         "text": "ZEIR ID",
         "answer": [
            {
               "valueString": "987239487"
            }
         ]
      },
      {
         "linkId": "7a27ab63-6a6f-499d-8a70-a356cf23da38",
         "text": "Date of Service",
         "answer": [
            {
               "valueDate": "2023-10-13"
            }
         ]
      },
      {
         "linkId": "d9c2e3e3-8415-44bd-8317-f573586a4943",
         "text": "Which vaccinations were provided?",
         "answer": [
            {
               "valueCoding": {
                  "code": "001",
                  "display": "OPV",
                  "system": "http://snomed.info/sct"
               }
            },
            {
               "valueCoding": {
                  "code": "002",
                  "display": "BCG",
                  "system": "http://snomed.info/sct"
               }
            }
         ]
      }
   ]
}