This document defines the process for automatically generating plans and tasks when an index case comes in from the BIOPHICS system. This document will remain as the source for sample templates as they are developed by the consortium. (Reference)
Scoping Details | |
|---|---|
| Responsible Person: | Christina Riley |
| Other parties to review/input: | |
| FYI: | |
| Targeted release date: | date |
| Jira Status: | ticket link |
The responsible person owns this feature from scoping to tracking development by Ona and providing clarifications if needed, to testing and sign off. Status
Status
# | Step | Status |
|---|---|---|
| 1 | Responsible prepares rough business analysis/reqs doc | COMPLETE: Christina Riley |
| 2 | Get CHAI review | *Need several verifications from CHAI team |
| 3 | Get Akros/VW Review | FYI: Pierre Dane |
| 4 | Get Ona feedback | FYI: Craig Appl |
| 5 | Responsible - 1 iteration for feedback | |
| 6 | Ona sign off | |
| 7 | Ona tech spec scoping | |
| 8 | Ona LOE | Small |
| 9 | Ona scheduling |
High Level Steps
- Index Case arrives in BIOPHICS
- Nifi queries the BIOPHICS system on a regular schedule and identifies that a new index case has arrived
- Nifi creates the event in the server as defined in the Index Case Confirmation workflow
- Nifi creates a plan based on the details of the case classification
- Nifi POSTs this plan to Reveal
- Nifi creates tasks for each plan action (up to 10 actions), performing business logic based on the code and Intervention Unit (Person, Residential Structure, Mosquito Collection Point, etc.)
Assumptions
We assume the following with this process:
We will create 1 plan for each index case classification that arrives- BIOPHICS is the first customer for this automated feature and we will tailor the workflow for this system. We will make it more generic in the future
- We will work within the constraints of Reveal 2 when generating tasks. For example, the IRS tasks are hardcoded in the Android client when a family is created, so we will not create them in the server if a family isn't registered at a structure.
- All plans described below are to be generated as drafts within the Planning Module and only made active by a human user - this has been covered under the NiFI Business Logic to be Developed section.
New Scope
NEW Assumptions for Review
Craig Appl Annie Martin - the new assumptions below have been added based on recent conversations around missing scope pertaining to more than one FI plan being created when a case is linked to more than one foci (i.e. focus of infection and focus of residence).
Automation for case-triggered FIs when the Focus of Infection and the Focus of Residence are NOT THE SAME
**Section in progress**
If the BIOPHICS variables Focus_case_residence_classification_id and Focus_Source_of_Infection_classification_id are NOT the same, then the index case resides in a focus other than the focus in which they acquired the malaria infection. This means that two plans need to be generated - one plan for each focus. By definition, the case classification will be considered local for the focus of infection and imported for the focus of residence. The case classification variable that is imported from BIOPHICS is classified in relation to the focus of residence.
For the purposes of Thailand, local cases are defined as being from within the same focus (i.e. sub-village), as confirmed by Pedro.
- **The assumption that one plan is created for each index case that arrives is broken; a plan should be generated for each focus associated with the index case
- A unique plan should be created for each focus. The plan generated for each focus is based on the given focus's focus classification and the case classification as defined by how the index case is associated with each focus.
- New assumptions:
- Focus classification defined - we have two focus types which each have their own variable for focus classification. These variables are the focus-type-specific equivalent of fiStatus variable.
- Focus of Infection: focus_Source_of_Infection_classification_code (BIOPHICS); responses (A1, A2, B1, B2)
- Focus of Residence: Focus_case_residence_classification_code (BIOPHICS); responses (A1, A2, B1, B2)
- Case classification defined - cases can be classified as either local (indigenous) or imported. The caseClassification variable is imported from BIOPHICS and is classified in relation to the focus of diagnosis.
- Focus of Infection: there is no source of infection-specific variable for the focus of infection; by definition this is considered 'Local' and should be hard-coded as 'Local'
- Focus of Residence: caseClassification (BIOPHICS); responses (Local, Imported)
- Plan generation criteria defined - each plan should be generated according to the following variables/criteria:
- Focus of Infection: focus_Source_of_Infection_classification_code + hard-coded classification as 'Local'
- Focus of Residence: Focus_case_residence_classification_code + caseClassification
- Focus classification defined - we have two focus types which each have their own variable for focus classification. These variables are the focus-type-specific equivalent of fiStatus variable.
- Additional items needed in detail view Craig Appl - I've added these in the Active_FI_Detail_View tab of the Reveal Web UI & Reporting Data Dictionary
- Focus type - defined as either the Focus of Infection or the Focus of Residence
- Focus of Infection name: Focus_Source_of_Infection_name (BIOPHICS); show if focusType== 'Focus of Residence'
- Focus of Residence name: Focus_case_residence_name (BIOPHICS); show if focusType== 'Focus of Infection'
Notes on Software Development required (Created by Craig on 23 July)
- This change is small because we need to update a Nifi processor to create an additional plan for the original operational area.
- Software to be developed is to create a Nifi processor that splits this request to two different jurisdictions and creates the same plan in both.
Sample Index Case Classification Form from BIOPHICS
This section contains the sample Index Case Classification form that's currently in BIOPHICS. This will be the original source for which business logic is defined.
{
"case_id" : "141410007601031181107101758977",
"p_site_id" : "2301110301",
"p_site_name" : "ท่ากุ่มบน(ชายเขา)",
"p_site_area" : "B1",
"source_site_id" : "8800000000",
"source_site_name" : null,
"source_site_area" : null,
"case_classification" : "Bz",
"household_id" : "",
"blood_draw_date" : "20181106",
"investigation_date" : "20181106",
"ep1_create_date" : "2018-11-07 14:43:50.857",
"ep3_create_date" : "2018-11-07 14:50:34.877",
"house_number" : 161,
"patient_name" : "แล้",
"patient_surname" : "สมัครสุนทร",
"patient_age" : 22,
"species" : "V"
}
p_site_id
Below is the index case above converted to an OpenSRP event:
"clients": [],
"no_of_events": 0,
"events": [
{
"identifiers": {},
"baseEntityId": "2301110301",
"eventDate": "2018-11-06T00:00:00.000+0000",
"eventType": "Case Details",
"formSubmissionId": "81604cb9-1911-4b05-b92f-c4a7ee310b25",
"providerId": "nifi-user",
"duration": 0,
"entityType": "Case Details",
"details": {
"family_name": "สมัครสุนทร",
"focus_id": "2301110301",
"focus_name": "ท่ากุ่มบน(ชายเขา)",
"surname": "สมัครสุนทร",
"first_name": "แล้",
"age": "22",
"case_number": "141410007601031181107101758977",
"case_classification": "Bz",
"focus_status": "B1",
"focus_reason": "Investigation",
"species": "V",
"investigtion_date": "2018-11-06T00:00:00.000+0000",
"ep1_create_date" : "2018-11-07T10:10:27.673+0000",
"ep3_create_date" : "2018-11-07T10:17:58.977+0000",
"house_number" : "161"
},
"version": 1557860282617,
"teamId": "",
"dateCreated": "2018-11-07T10:17:58.977+0000",
"type": "Event"
}
]
}
Case Classification Business Logic
This section defines the business logic and relationship to the templates below.
| Case | Pseudocode Logic | Template Number |
|---|---|---|
| 1 | If (focus_status == A1 OR focus_status == A2) then (choose Template 1) | 1 |
| 2 | If (focus_status == B1 ) then (choose Template 2) | 2 |
| 3 | If ((focus_status == B1 OR focus_status == B2) AND (case_classification == local) AND (historical_interventions == IRS)) then (choose template 3) | 3 |
| 4 | If ((focus_status == B1 OR focus_status == B2) AND (case_classification == local) AND (historical_interventions == Blood Screening)) then (choose template 4) | 4 |
| 5 | If (focus_status == NULL) then (figure out based on case classification) |
Unaccounted for Case Classification Scenarios
There are a number of unaccounted for case classification scenarios that we need to add to this document. (This section should be deleted when this document is finalized.)
- How do we trigger routine interventions? The BIOPHICS system only has case-triggered interventions. What will be the input before we have a user interface in FI planning?
- @Janette - These will be triggered via a button on the WebUI. There will need to be some discussion with Craig Appl, Matt Berg and @Kelvin about how this will integrate with your current NiFi process.
- Is there such a thing as an imported case classification for a B2 focus_status? (This doesn't appear to be covered in the templates)
- The answer is that an imported case could not transmit in a B2 focus_status, so no plan should be generated.
- Where will we get the historical intervention information IRS or Blood Screening? This information does not come in on the case classification form.
- We do NOT need to get the historical intervention information, Reveal will build up a history of interventions as these are carried out using the tool, but we don't need to import any from Biophics.
Case Classification Options
The case_classification field can have the following options. We need to map these against 'local' and 'imported' as defined above.
| Value | Type (Local/Imported) | Local/Imported |
|---|---|---|
A | Indigenous (same village) | Local |
| Bx | Imported - from different village within same sub-district | Imported |
| By | Imported - from different sub-district within same district | Imported |
| Bz | Imported - from different district within same province | Imported |
| Bo | Imported - from a different province | Imported |
| Bf | Imported - from a different country | Imported |
| C | Relapse case (Same infection - only for Pv & Po) | Imported |
| D | Induced case (received parasites from blood transfusion) | Imported |
| E | Introduced case (local infection but associated with imported case) | Imported |
| F | Unclassified - staff unable to classify as A, B, C, D, or E | Local |
Plan Action Time Periods
This section defines time periods for all plans:
- Plan Execution Period
- Start: Today
- End: Today + 20 days
- Actions
- Index Case Confirmation
- Start: Plan Start
- End: Plan Start + 10 days
- Family Registration
- Start: Plan Start
- End: Plan Start + 20 days
- Bednet Distribution
- Start: Plan Start
- End: Plan Start + 20 days
- RACD Blood screening
- Start: Plan Start
- End: Plan Start + 20 days
- Larval Dipping
- Start: Plan Start
- End: Plan Start + 20 days
- Mosquito Collection
- Start: Plan Start
- End: Plan Start + 20 days
- Behavior Change Communication
- Start: Plan Start
- End: Plan Start + 20 days
- Index Case Confirmation
Nifi Business Logic to be Developed
This section defines the business logic that needs to be implemented in Nifi given the variables above.
Steps:
- Receive the case classification event
- Perform the logic defined in the Case Classification Business Logic section above which will determine which template to use
- Query the system to see if the house number defined in the case classification is already registered in the system as a location within the jurisdiction
- If the house number IS registered in the system we need to create a case classification with Action.code: Residential Structure
- If the house number IS NOT registered in the system we need to create a case classification with Action.code: Operational Area
- Load in the template in a replaceText processor
- Save the converted template to an attribute (the replaceText processor defines UUIDs and we need to reference these later)
- POST the draft plan to /rest/plans (Example)
- (BREAK) A human needs to convert the plan from draft to active
- Monitor the /rest/plans endpoint to see if a plan was converted from draft to active
- Load the plan into the flowfile
- Extract up to 10 plan actions into individual values (This is done in this processor)
- Process each plan action and route them to the appropriate flows based on the Action.subjectCodableConcept
- Codes that need to be evaluated on each location within the jurisdiction: Residential Structure (i.e. Bednet Distribution, IRS and RACD Register Family), Larval Breeding Site and Mosquito Collection Point
- Extract the jurisdiction so we can query the API and get all of the locations within that jurisdiction
- Clear the flowfile
- GET all of the locations within a jurisdiction at /rest/location/sync
- Split the results so you can act on each location within the jurisdiction
- Save the location properties as attributes for future reference
- Filter out locations that are "Inactive"
- Create duplicate flow files for each action, so each location is evaluated against each action. (i.e. only mosquito collection points are meant for mosquito collection actions or residential structures are only evaluated against register family events)
- Perform the following logic based on the Action.subjectCodableConcept
- Residential Structure
- Query to see if there is a family registered at this location. (ENDPOINT TBD)
- Action.code: Bednet Distribution
- If a family IS NOT registered at this location
- Do nothing because the RACD Register Family task will automatically create a bednet distribution task in the Android client when the family is registered
- If a family IS registered at this location
Create a bednet distribution task at this location
- If a family IS NOT registered at this location
- Action.code: RACD Register Family
- If a family IS NOT registered at this location
Create a RACD Register Family task
- If a family IS registered at this location
- Do nothing
- If a family IS NOT registered at this location
- Action.code: Bednet Distribution
- Action.code: Case Confirmation (Only if the house number from the case classification was found in the system)
Create a case confirmation task
- Query to see if there is a family registered at this location. (ENDPOINT TBD)
- Larval Breeding Site
- Criteria: ${location.properties.type:equals('Larval Breeding Site')}
- Action.code: Larval Dipping
Create a larval dipping task
- Mosquito Collection Point
- Criteria: ${location.properties.type:equals('Mosquito Collection Point')}
- Action.code: Mosquito Collection
Create a mosquito collection task
- Residential Structure
- Codes that need to be evaluated on each person registered in that jurisdiction: Person (i.e. Blood Screening)
- Query all people in that jurisdiction
- Action.code: RACD Blood Screening
Create a blood screening task for each person
- Action.code: RACD Blood Screening
- Query all people in that jurisdiction
- Codes that need to be evaluated on the jurisdiction: Operational Area (i.e. BCC and Case Confirmation)
- Action.code: BCC
Create a BCC task in the system
- Action.code: Case Confirmation (If the house number from the case classification event was not found in the system)
Create a case confirmation task for the operational area
- Action.code: BCC
- Codes that need to be evaluated on each location within the jurisdiction: Residential Structure (i.e. Bednet Distribution, IRS and RACD Register Family), Larval Breeding Site and Mosquito Collection Point
- Post all tasks to the server ${opensrpBaseUrl}/rest/task
Plan Templates
This section includes the plan templates using the Nifi expression language.
For the purposes of plan automation, there are a total of six discrete, comprehensive protocols which have been translated into templates for the Thailand pilot. There are four protocols for case-triggered focus investigations (where fiReason==case-triggered); these protocols are dependent on the focus status (if fiStatus==A1 OR fiStatus==A2 OR fiStatus==B1 OR fiStatus==B2), the case classification (if case_classification==imported OR case_classification==local), and MAY be dependent on the historical vector control intervention employed (available in MIS). There are two protocols for routine focus interventions (where fiReason==routine); these protocols are dependent on the routine focus intervention selected (if actionCode==Bednet Distribution OR actionCode==Blood Screening).
Template 1: Local & Imported Case Triggered A1 & A2 - 7 Actions
Logic:
- Case Triggered
- There are 7 actions and goals
- Case Classification Form Mapping
Plan type 1: Automation for case-triggered FIs in A1 & A2 areas for both local and imported case classifications.
This plan type is initiated when a case is passively detected and entered into the MIS and the focus status is an A1 or A2 area (fiStatus==A1 OR fiStatus==A2) and the case is classified as either local or imported (if case_classification==imported OR case_classification==local). All focus investigation activities/actions, with the exception of IRS, should be available to be completed by the user for this protocol. The type of blood screening done for this area is RACD within 1km with a goal to screen the first 50 people or 10 households; we will use the goal of 'the first 50 people' for plan automation. Operationally, more individuals (both within and outside the 1km area) may be tested, so the hard-coding of blood screening to each family member registered is appropriate here.
If a structure already has a household registered during a previous plan, the user should not have a family registration task assigned to this structure, but the user should always be able to add additional family members.
This plan should close 20 days after the plan is initiated as per Pedro/Thailand.
- 1: actionTitle - Index case confirmation
- goalTargetMeasure: Case confirmation complete
- 2: actionTitle - Family Registration
- goalTargetMeasure: Percent of residential structures with families registered
- 3: actionTitle - Blood Screening
- goalTargetMeasure: Percent of registered people tested
- assumption: the protocol specifies RACD to be done within 1km; either the first 50 people or 10 households is the goal target; we will use the goal of 'the first 50 people' for plan automation. Operationally, more individuals (both within and outside the 1km area) may be tested.
- 4: actionTitle - Bednet Distribution
- goalTargetMeasure: Percent of residential structures received nets
- 5: actionTitle - Larval Dipping
- goalTargetMeasure: Number of larval dipping activities
- 6: actionTitle - Mosquito Collection
- goalTargetMeasure: Number of mosquito collection traps
- 7: actionTitle - Behaviour Change Communication
- goalTargetMeasure: BCC activity complete
Template 2: Imported Case Triggered B1 - 4 actions
Logic:
- Case Triggered
- There are 4 actions and goals
Plan type 2: Automation for case-triggered FIs in B1 areas for imported cases.
This plan type is initiated when a case is passively detected and entered into the MIS and the focus status is a B1 area (fiStatus==B1) and the case is classified as imported (if case_classification==imported). Only the following focus investigation activities/actions are specified for this protocol: index case confirmation, family registration, blood screening, and behavior change communication. The type of blood screening done for this area is RACD within 1km with a goal to screen the first 50 people or 10 households; we will use the goal of 'the first 50 people' for plan automation. Operationally, more individuals (both within and outside the 1km area) may be tested, so the hard-coding of blood screening to each family member registered is appropriate here. For the July 1 release, it is ok if bednet distribution is still hard-coded to family registration.
If a structure already has a household registered during a previous plan, the user should not have a family registration task assigned to this structure, but the user should always be able to add additional family members.
This plan should close 20 days after the plan is initiated as per Pedro/Thailand.
- 1: actionTitle - Index case confirmation
- goalTargetMeasure: Case confirmation complete
- 2: actionTitle - Family Registration
- goalTargetMeasure: Percent of residential structures with families registered
- 3: actionTitle - Blood Screening
- goalTargetMeasure: Percent of registered people tested
- assumption: the protocol specifies RACD to be done within 1km; either the first 50 people or 10 households is the goal target; we will use the goal of 'the first 50 people' for plan automation. Operationally, more individuals (both within and outside the 1km area) may be tested.
- 4: actionTitle - Behaviour Change Communication
- goalTargetMeasure: BCC activity complete
Template 3: Local Case Triggered B1 & B2 - 7 Actions | History = Bednet Distribution or Bednet Re-Dipping
Logic:
- Case Triggered
- There are 7 actions and goals
Plan type 3: Automation for case-triggered FIs in B1 & B2 areas for local cases if historic vector control was bednet distribution/bednet re-dipping.
This plan type is initiated when a case is passively detected and entered into the MIS and the focus status is a B1 or B2 area (fiStatus==B1 OR fiStatus==B2) and the case is classified as local (if case_classification==local). This plan is specifically for B1 and B2 areas that have historically employed bednet distribution (or bednet re-dipping) as the vector control measure of choice - this information is available in the MIS. All focus investigation activities/actions, with the exception of IRS, should be available to be completed by the user for this protocol. The entomological activities (larval dipping & mosquito collection should be prioritized following index case confirmation as they will determine whether or not the user should complete bednet distribution; this is dependent on confirmation of transmission. The type of blood screening done for this area is mass blood screening across the entire focus.
If a structure already has a household registered during a previous plan, the user should not have a family registration task assigned to this structure, but the user should always be able to add additional family members.
This plan should close 20 days after the plan is initiated as per Pedro/Thailand.
- 1: actionTitle - Index case confirmation
- goalTargetMeasure: Case confirmation complete
- 2: actionTitle - Family Registration
- goalTargetMeasure: Percent of residential structures with families registered
- 3: actionTitle - Larval Dipping
- goalTargetMeasure: Number of larval dipping activities
- 4: actionTitle - Mosquito Collection
- goalTargetMeasure: Number of mosquito collection traps
- 5: actionTitle - Blood Screening
- goalTargetMeasure: Percent of registered people tested
- assumption: the protocol specifies mass blood screening across the entire focus
- 6: actionTitle - Bednet Distribution
- goalTargetMeasure: Percent of residential structures received nets
- 7: actionTitle - Behaviour Change Communication
- goalTargetMeasure: BCC activity complete
Template 4: Local Case Triggered B1 & B2 - 7 Actions | History = IRS
Logic:
- Case Triggered
- There are 7 actions and goals
Plan type 4: Automation for case-triggered FIs in B1 & B2 areas for local cases if historic vector control was indoor residual spraying.
This plan type is initiated when a case is passively detected and entered into the MIS and the focus status is an B1 or B2 area (fiStatus==B1 OR fiStatus==B2) and the case is classified as local (if case_classification==local). This plan is specifically for B1 and B2 areas that have historically employed indoor residual spraying as the vector control measure of choice - this information is available in the MIS. All focus investigation activities/actions should be available to be completed by the user for this protocol (we assume that bednet distribution is hardcoded). The entomological activities (larval dipping & mosquito collection should be prioritized following index case confirmation as they will determine whether or not the user should complete indoor residual spraying; this is dependent on confirmation of transmission. The type of blood screening done for this area is mass blood screening across the entire focus.
If a structure already has a household registered during a previous plan, the user should not have a family registration task assigned to this structure, but the user should always be able to add additional family members.
This plan should close 20 days after the plan is initiated as per Pedro/Thailand.
- 1: actionTitle - Index case confirmation
- goalTargetMeasure: Case confirmation complete
- 2: actionTitle - Family Registration
- goalTargetMeasure: Percent of residential structures with families registered
- 3: actionTitle - Larval Dipping
- goalTargetMeasure: Number of larval dipping activities
- 4: actionTitle - Mosquito Collection
- goalTargetMeasure: Number of mosquito collection traps
- 5: actionTitle - Blood Screening
- goalTargetMeasure: Percent of registered people tested
- assumption: the protocol specifies mass blood screening across the entire focus
- 6: actionTitle - Indoor Residual Spraying
- goalTargetMeasure: Percent of residential structures sprayed
- 7: actionTitle - Behaviour Change Communication
- goalTargetMeasure: BCC activity complete
Template 5: Routine - Bednet Distribution - 2 Actions
Logic:
- Routine
- There are 2 actions and goals
Plan type 5: Automation for routine focus intervention for bednet distribution.
This plan type is initiated when the government wants to conduct a routine intervention (if fiReason==routine). Routine interventions are conducted in A1 and A2 areas according to Thailand protocol; however, there should not be a restriction to these areas given that focus status can change during the year. This plan is dependent on bednet distribution being selected as the routine focus intervention (if actionCode==Bednet Distribution). Craig Appl - I'm not sure if 'actionCode' is the correct variable to be selected to automate the plan - I think this needs to be selected on your end.
If a structure already has a household registered during a previous plan, the user should not have a Family registration task assigned to this structure, but the user should always be able to add additional family members.
This plan should close 20 days after the plan is initiated as per Pedro/Thailand.
- 1: actionTitle - Family Registration
- goalTargetMeasure: Percent of residential structures with families registered
- 2: actionTitle - Bednet Distribution
- goalTargetMeasure: Percent of residential structures received nets
Template 6: Routine - Blood Screening - 2 Actions
Logic:
- Routine
- There are 2 actions and goals
Plan type 6: Automation for routine focus intervention for mass blood screening.
This plan type is initiated when the government wants to conduct a routine intervention (if fiReason==routine). Routine interventions are conducted in A1 and A2 areas according to Thailand protocol; however, there should not be a restriction to these areas given that focus status can change during the year. This plan is dependent on mass blood screening being selected as the routine focus intervention (if actionCode==Blood Screening). Craig Appl - I'm not sure if 'actionCode' is the correct variable to be selected to automate the plan - I think this needs to be selected on your end.
If a structure already has a household registered during a previous plan, the user should not have a Family registration task assigned to this structure, but the user should always be able to add additional family members.
- 1: actionTitle - Family Registration
- goalTargetMeasure: Percent of residential structures with families registered
- 2: actionTitle - Blood Screening
- goalTargetMeasure: Percent of registered people tested
- assumption: the protocol specifies mass blood screening across the entire focus