File Name - exceptions.json

The exceptions file contains multiple scenarios where specific family planning methods are removed from the final response options. Some exemptions are informed by global guidance and apply in all cases/all countries for some of the algorithm questions (age, breastfeeding, further pregnancies). Other exemptions apply to specific countries; the exceptions by country ensure that methods not available for a given country will not be returned as part of the response; and the exceptions by answer allow for adding, removing, or replacing a method.

The file is written using JSON notation. To learn more about the basic notation used in JSON, click here.

Country-based exceptions

The main elements to configure these restrictions are country and methods.

Country

The country must be specified using the ISO 2-letters code within double quotes, inc capitals.

{
    "methodsToExclude":{
        "GT": 
    },
    "questionsToExclude":{

    }
}

Methods

The methods to exclude must be in the list of available methods of the questions.json file. These exceptions must be written within square brackets and separated by commas.

{
    "methodsToExclude":{
        "GT" : ["IUD"]
    },
}

The example above excludes the method IUD from the recommended methods to a user in Guatemala.

Answer based exceptions

To configure this type of exclusion, use the following elements:

Question/option

The question must be specified as it is on the questions.json file and the answer or option must be placed between square brackets. The following example shows when question age is answered with <18, the bot will remove the method "Sterilization".

"excludeAnswerBased":{
            "age:[<18]":{
            "add":[],
            "remove":["Sterilization"],
            "replace" : []
        }

Action (add, remove or replace)

For each question/answer, it is possible to add, remove or replace a method. For adding and removing, the methods must be placed as an array, each of them must be written between double quotes and separated by commas. And, when replacing, separate the current method and the desired method by a colon. Both methods must be between double quotes and the whole expression between curly brackets.

Use add to incorporate a method to the list. Remember only the first three methods will be displayed.
Use remove to ensure the method will not be part of the response.
Use replace to exchange one method for another. This implies that the new method will keep the display order of the replaced method.

The following example shows how to replace COP method for POP, when the client responds yes to "Are you breastfeeding a baby less than 6 months old?"

Disclaimers

It is possible to add disclaimers according to a specific answer. These messages will be returned and should be shown on the UI as informational text messages. As in the questions.json file, the message is a term in POEditor but the variable is configured in the exceptions file.

To add a disclaimer, the following elements are needed:

Question/Answer

Identify the trigger of the disclaimer by adding the question and option. The option must be between square brackets.

disclaimer variable

The variable must have the following structure:

question.disclaimer

If the messages are different among the same question (but different options), the structure of the variable should be written as follows:

Changes: simple edits

How to exclude a method from an already listed country

To exclude a new method, search the country ISO code and then the keyword for the methods to exclude. The list of available methods is in the questions.json file. The methods must be separated by commas. Make sure there is no comma next to the closing bracket.

Example:

How to exclude an option from a new country

If the country does not exist, the first step is to add the new country key. To do that, write the ISO code of the country in double quotes then add a colon (:) and finally, add an array with the methods to exclude. All the methods must be separated by commas.

Example:

Before adding the new country, remember to add a comma to separate the countries (["EC"], "KE")

How to add a method based on a specific answer

Identify the question/option and in the "add" action write all the new methods. Remember each method must be in double quotes and separated by commas. In the following example, the method Oral Contraceptive Pills (OCP) will be added to the response when the user's answer is "yes" to "Are you breastfeeding a baby less than 6 months old?".

The new method will be appended last to the response list. Remember that only the first three methods will be displayed in the response.

How to remove a method based on a specific answer

Identify the question/option and in the "remove" action write all the new methods. Remember each method must be in double quotes and separated by commas. In the following example, the method Oral Contraceptive Pills (OCP) will be removed from the response when the user's answer is "yes" to "Are you breastfeeding a baby less than 6 months old?".

How to replace a method based on a specific answer

Identify the question/option and in the "replace" action use the following structure to indicate the method to be replaced:

{"methodToBeReplaced":"methodThatReplaces"}

The following example replaces Oral Contraceptive Pills (OCP) with Progesterone Only Pills (POP) when the user's answer is "yes" to "Are you breastfeeding a baby less than 6 months old?".

Other Changes: new logic

Add a new exception section

If a new parameter needs to be added such as questions or factor options, contact the C4C technical administrator to make the configuration change. Otherwise, the logic could get damaged.

Algorithm

Overview

Multilingual

Counseling for Choice

exceptions.json