FHIR questionnaires are a standardized way of representing clinical questionnaires. They are used in a variety of healthcare settings, including hospitals, clinics, and home health agencies. Beside containing the questions and structured answers (value types and value options), the also defined hide/show logic and validation statements. FHIR Questionnaires are used to collect a diversity of contents in relation to the patient. In the context of chatbots or USSD examples include:

• A bot or ussd app could be used to collect patient history information. This could help to ensure that all patients are asked the same questions, and that no important information is missed.

• A bot could be used to provide education to patients. This could help patients to understand their condition and how to manage it.

• A bot could be used to collect feedback from patients. This could help to improve the quality of care and patient satisfaction.

As of August 2023, PSI extensively uses conversational chatbots to collect information directly from clients. In some cases we also make use of USSD sessions, for which we run short questionnaires. For chatbots, the flow of those conversations is defined in system like RapidPro, and the answers are stored on a FHIR backend, as a QuestionnaireResponse resource. But in most cases PSI currently (Aug 2023) don’t have the associated Questionnaire, which means that the metadata is missing. The creates challenges for analytics, and also force to code questionnaires as part of the bot or the USSD application, instead of just using a FHIR questionnaire.

Questionnaire Processor application

Questionnaire Processor is a server-side Node.js application able to process FHIR Questionnaires. The service can be integrated with USSD or chatbot applications to prompt users with questionnaire items and gather their responses. The services validate user input in accordance to the constraints for the related FHIR Question Item, and it return the next question as part of the API response body. At the end of the process you get the FHIR QuestionnaireResponse resource, based on the answer provided.

The service includes:

• Parse the provided FHIR Questionnaire

• Prompt users with relevant questions

• Validate and process user responses based on question types

• Evaluates skip logic and conditional validations

• Save and resume sessions

• Keeps a detailed logging of user interactions

Link: https://drive.google.com/file/d/1WM5nvoVbOon-X0yTX7t5Prz7mt_1DRVP/view?usp=sharing

Request Parameters

• Headers

  • X-api-key: Your API token set in the .env file (required).

  • Accept-Language: Set the desired language for the response. Supported languages: English, French, Spanish and Burundi.

• Body

  • sessionId: Unique session id for the interaction (required).

  • userId: Unique identifier related to the user.

  • Input: User response to the prompt (optional for first request).

  • showQR: Return Questionnaire response after each request (optional). The valid values are or

  • questionnaire: FHIR Questionnaire in JSON format (optional after the initial request).

Example Request

{
  "sessionId": "123456789",
  "userId": "user123",
  "Input": null,
  "showQR": true,
  "questionnaire": {...} // Your FHIR Questionnaire JSON
}

Response Structure

• Status: Reflects the state of the session (CON or END).

• Message: Question item, options, or validation message displayed to the user.

• QuestionnaireResponse: Returned if showQR is true or the session reaches the end.

Example Response

{
    "status": "CON",
    "message": "2. Household owns a mobile phone?<br/>1. Yes<br/>2. No",
    "questionnnaireResponse": {
        "resourceType": "QuestionnaireResponse",
        "questionnaire": "BI USSD - Register Household",
        "status": "in-progress",
        "item": [
            {
                "linkId": "CHW_02",
                "text": "Has the client consented to data capture?",
                "answer": [
                    {
                        "valueBoolean": true
                    }
                ]
            }
        ]
    },
    "linkId": "CHW_03"
}

Supported FHIR Question Types

• Boolean

• Choice

• Date

• Decimal

• Display

• Integer

• Phone

• Quantity

• Text

• URL

Notes:

• For Boolean questions, 1 is used for True and 2 for False.

• Skip logic and validations like greater than, less than, or equals to are supported.

• The application uses SQLite for session management and Winston for logging.

• Use a simple token-based authentication mechanism for enhanced security.

• The application doesn’t support nested FHIR questionnaire.

Getting Started:

1. Environment Configuration:

   • Rename the .env.example file to .env.

   • Update the .env file based on your system configuration.

2. API Endpoint: base_url/api/v1/questionnaire

3. API Documentation: Access detailed API documentation and test endpoints using swagger-ui at base_url/api/v1/docs.

[Monday.com Board]