Overview

This document should hopefully help you when you need to make changes to the scenarios. I've broken it down into different types of changes and certain steps that need to be taken. 



Keep track of the String IDs you add or make changes to. You can send this list to the translations team so they only have to focus on the content that's changed.


Test changes on the go by using the Health Bot's editors 'Run' button


Keep at least two tabs open: 1 of localization tool to quickly make text changes and 1 for the scenario you are currently editing. 


Types of Changes

  • Purely text changes (often a 'decimal' version, 65.1, etc)
  • Structural changes
    • Adding a new question
  • Adding new symptoms / changing question answer choices


Unique Scenario Blocks

 The following blocks appear at the beginning of a given scenario
  • Version (first block): The first block in the scenarios is a used to set a version number. If you are upgrading to a new version of the algorithm, then set the algorithm version. If you are just making minor changes that don't involve a new algorithm version, then do <major-version>.<minor-version>.  The foreign language bot files are given '<major-version>.<minor-version>-ne'
  • DICT: There is a 'dictionary' object created at the beginning of the scenario to bring in strings from the Localization tool. For any new strings, you should add the relevant entries here. 
  • Index Lookup: Instead of using the Javascript array index, the scenarios have an index lookup table to determine the correct index of an answer choice. The object keys correspond to the keys in the dictionary object. There are entries for all answer choices, even those that have been removed. 
    • Never remove items and indexes from the list, only add. Any additions to this object need to be made in the corresponding Excel sheet and sent to the data team.
  • List Builder: this object defines the current index-based lists (symptoms, comorbidities, ethnicities, etc.) and the correct index to use when passing to the logs. 
  • AGES: this block converts the list of ages that is pulled in from the localization tool to a an array of objects so that can be displayed in a dropdown list. 
  • Custom MSG: this block adds in the custom message (if applicable) to the output blocks.  It will usually be a link to a state health department, or a message about checking with health ministries/departments for International Users.
  • Questions:  This is an artifact from when Clara split out questions between second person (you/yours) and third person (they/their/theirs) situations.  It was deemed too much of a rigmarole to double up the number of messages and has since just stuck to second person. Thus it now simply converts all the "second person questions" from the DICT block into the "scenario.questions" block.  
  • Test/Show Titles:  This block will prefix the questions and messages with the question and message titles if an Environment Variable of "IsNotProd" is defined as "true".  This helps with testing to make sure the right messages/questions are appearing at the right time.

The following blocks appear At the end of a given scenario file.

  • Terminal. In this block
    • The outcome ID is set, matching the documentation (both the language/messages and the visual flow).
    • The message IDs and Test Message IDs are set.  An array of zero to many of the messages that are being shown to the user.
  • Outcome. In this block: 
    • a conversation variable is set with the answers to each question that the user answered and the outcome ID that was reached. There is a property for each question which contains the text of the answer selected and the index from the index table selected. All new questions need to be added to this object. Changes to the object should be sent to the data team.
    • a custom log call happens to send the information in the conversation object to a SQL server.
    • A trace is sent to the log output window so that a user can see what is being set to the logs (and ultimately made available for the data team) for each outcome.



Scenario Breakdown

Wrapper Scenario

The wrapper scenario is the beginning scenario and holds just a few / statements and questions: 

This is the best place to put information that is of interest to US Citizen and/or the CDC, but not necessary for core guidance.  That way the cores can be used by other countries or other departments without much modification.

  • Disclaimer
  • US or outside US
  • State / US Jurisdiction location
  • Zipcode
  • User Experience questions (at the end after the core scenarios execute)

Core Scenario

Pathways

The scenarios / algorithms are broken into five files for adult symptomatic questions, adult asymptomatic questions, questions for adults who are vaccinated against Covid-19, questions for children who are vaccinated against Covid-19, and pediatric unvaccinated questions.  The pathways within the pediatric and vaccinated cores tend to have three major pathways: Asymptomatic, COVID-19 Exposure, and No Exposure. The adult pathway has the asymptomatic pathway broken out into it's own file.  Those pathways are broken down even further depending on symptoms and COVID test results. In the image below (from a much earlier version of the bot), the 3 major paths are labeled. Any questions that come before these questions in the scenario determine which scenario the user will take and which options are show. The documents from the Health Bot team are split in the exact same way so it makes it easy to determine where the changes are made. 


Question and Message IDs

The messages that are presented to the user have now been marked with IDs in the documentation.  This makes it very easy for debugging when a tester finds a certain path is not yielding the correct responses.



Text Changes

If the changes that need to be made a purely text changes to existing text, you can make those changes directly in the localization tool. Open the localization tool and search for the string ID of the content you want to change.

If you are not sure of the string ID you want to change, then open the 'DICT' block and look within there. The string ID should be named appropriately for their purpose. For example, the intro message's string ID is CDC/messages/intro_msg. Another way of finding the string ID of the text you want to change is by figuring out the block it is used in. The names of the scenario blocks describe their content. Open the block for edit and see which scenario variable is being used in it. You can then go to the 'DICT' object and search for that variable. 


Structural Changes

Structural changes happen when content is added, removed, and/or moved around. These types of changes typically only happen when there's a new algorithm version from the Health Bot team. 

Adding a new question

If you need to add a new question, first figure out which scenario it should go in and where in the scenario. The way I do that is by determining if the question falls within a  'pathway', or if it's a beginning question (like Age) before there are any algorithm pathways. Use the information in the Scenario Breakdown section of this page to determine in which scenario to make the change. Further determine in which pathway the question should go or if it's a beginning question (like age or gender). 

  1. Add all text content to the Localization tool.
  2. Import the text string in the DICT block and set that to an appropriately named variable. If it's a question that needs both 3rd person and 2nd person then make sure to add it to both questions objects. 
  3. Add the question to the scenario in the appropriate place. 
  4. Test that the question is reachable and the answer choices are displayed and function correctly.
  5. Add the question property and answer to the Outcome block. 
  6. Test that the Outcome log data looks correctly in PowerBI. (I usually wait until I've finished all visual changes and then do full end-to-end tests with the data Team). More information about this can be found here.
  7. Copy the new Outcome block code to all Outcome blocks in the scenario you are changing. (You will send this new block to Ravi & the Data Team eventually). There are a lot of Outcome blocks. I usually wait until I'm sure the new block is working with the data team before I update all of them. If you have to make a change to it, then you'd have to make a change to all of them again. 


Adding a new symptom to an existing question

Because the symptoms list changes often, there are special steps you have to take to make sure the bot displays information correctly and the information from bot sessions comes out correctly. 

  1. First figure out which question you want to change and determine the name of the symptoms variable you want to change.
  2. Add the new symptom to localization tool. Since it's an existing question, find search for the question in the tool and add the new string in the same format. For ex. if the question we are working on is the COVID symptoms question. The new string ID would be CDC/covid_symptoms/new_symptom, where new_symptom is a string that is unique enough to know what answer choice / symptom it's referring to. 
  3. Import the new symptom in the DICT block in the appropriate object.
  4. Add the new symptom and it's index to the Index Lookup block. The index is typically just the last index number + 1.
  5. Add the new symptom to the Symptoms block in the position it should appear in the bot UI.
  6. Go through texts and make sure that the symptom appears in the correct position in the list. 
  7. Follow the steps in adding and new question for making sure that the data looks correct.



Changing non-symptoms type question answer options

Changing non-symptoms type answer options can sometimes just mean updating the string in the Localization tool. If the string is used for more than one question, however, you may need to create a new variable. 

  1. First figure out the string ID you want to change in the Localization tool. 
    1. Figure out which question you want to change and determine the name of the variable you want to change.
      1. You can do that by finding the prompt scenario block and looking at the 'Choices Array' field. It will say something like scenario.dictionary.responses.<something>
      2. Go to the DICT block and look for the variable. Next to it, it will say customLocalizedString["<stringID>"]. That string ID is what you will search for in the Localization tool
  2. Search for that string ID in the localization tool. If this variable is used for another question that doesn't need the new option, then you need to create a new string.
  3. If you don't need to create a new string, then the string is most likely an array.
    1. Add the new option in the correct position to the variable array
    2. Test to make sure the option appears in the correct position in the scenario
  4. If you need to create a new string,
    1. Choose an appropriate string ID label and add an array with all of the options needed
    2. Import the new string in the DICT block in the scenario, most likely in the "responses" object
    3. Update the question block to use the new variable you just defined in the DICT block
    4. Test to make sure the option appears in the correct position in the scenario

Changing comorbidities

Because the comorbidities list changes often, there are special steps you have to take to make sure the bot displays information correctly and the information from bot sessions comes out correctly.  Extra care needs to be taken if comorbidites are added or the order is changed because there is some special handling of the "Pregnancy" comorbidity based on age and sex.

  1. For comorbidities that just need a text change, figure out which comorbidity you want to change and determine the name of the comorbidity variable you want to change, and change as needed
  2. If you need to add comorbidities, add the new comorbidity to localization tool. Since it's an existing question, find search for a comorbidty in the tool and add the new string in the same format. The new string ID would be CDC/comorbidity/new_comorbidity, where new_comorbidity is a string that is unique enough to know what answer choice / symptom it's referring to. 
  3. Import the new symptom in the DICT block in the comorbidity object.
  4. Add the new symptom and it's index to the Index Lookup block. The index is typically just the last index number + 1.
  5. Add the new symptom to the Symptoms block in the position it should appear in the bot UI.
  6. If the order of the comorbidities was adjusted, you'll need to adjust some question logic
    1. Make a note of the index at which the "pregnancy" string exists in the Symptoms code, starting count with 0.
    2. find the "Risk List" block and adjust the index in the if-statement to the new index of the "pregnancy" string.
  7. Go through texts and make sure that the symptom appears in the correct position in the list.
  8. Go through the texts and make sure that "Pregnancy" comorbidity option is not shown for males or women older than 60