SADV - Decision Support System for Vaccination

Introduction

The SADV tool, developed by Syadem, offers a service of personalized vaccination recommendations based on medical data. It is designed for use by healthcare professionals as well as patients, acting as a guide in the vaccination journey.

The uniqueness of SADV lies in its ability to optimize and keep each patient’s vaccination journey up-to-date. The primary goal of this tool is to ensure the safety and effectiveness of vaccinations, in strict compliance with current official recommendations.

In France, SADV relies on official guidelines from the High Authority for Health (HAS) or the Ministry of Health. Additionally, it also uses information contained in the marketing authorization dossiers.

SADV strictly respects patient confidentiality. The system does not have the capability to store personal data; it receives anonymous patient data inputs and returns personalized vaccination recommendations, without persisting any data.

Concepts

SADV is based on the following concepts:

Vaccination Diagnosis
This is a set of vaccination recommendations for a given patient.
Vaccination Recommendation
A recommendation concerns a given patient and a given target disease. The recommendation includes information such as the vaccination status (is the patient behind schedule or up to date?) and the suggested action (e.g., vaccinate the patient on a certain date).
Condition
This refers to a life condition that can impact vaccination recommendations (for example, being pregnant or having a chronic disease). Each condition is of a specific type (for example, "pregnancy" is a boolean value condition, while "last history of COVID-19" is a date type value condition).
Health Profile
This is a set of condition values associated with a given patient. It takes the form of a set of key-value pairs where the key is a condition identifier and the value conforms to the expected type for the condition.

Nomenclatures

SADV relies on two nomenclatures:

Integration

The SADV tool is accessible via a REST API. This API can be used through libraries documented below. These libraries will allow you as a business software publisher to integrate vaccination recommendations into your software.

Prerequisites

The integration of the SADV tool relies on three libraries.

Library Description
sadv-client Allows querying the SADV REST API.
nuva Allows retrieving data from the NUVA vaccine nomenclature to structure and display the patient's vaccination history in your software.
vaccination-profile Allows retrieving data from the VaccinationProfile nomenclature to structure and display the patient's health profile data in your software.

API Overview

The SADV API is available as a REST API.

Access to this API is restricted and relies on OAuth 2.0 and OpenID Connect 1.0 authentication protocols. To obtain access, please contact the Syadem team.

The API exposes 2 endpoints, the specifications of which are available in the swagger documentation.

Note: By using the sadv-client library, you do not need to build HTTP requests and parse JSON responses. The library takes care of all this for you.

Authentication Protocol

Authentication as a Publisher

The Colibri API uses OAuth 2.0, the industry standard protocol for authorization. More specifically, authorization to access the Colibri API is based on the authorization mechanism “client credentials authentication grant”.

In practice, you need to obtain an access token from our authentication server (by identifying with your client credentials), before including this token in requests sent to the Colibri API. It is recommended to use an OAuth library (suggested libraries).

Here is an example of obtaining the access token (prerequisites: curl and jq tools must be installed):

# parameters vary according to the environment
CLIENT_ID=...
CLIENT_SECRET=...
AUTH_ROOT_URL=https://auth.integration.mesvaccins.net

ACCESS_TOKEN=$(curl -s -X POST -u $CLIENT_ID:$CLIENT_SECRET -d 'grant_type=client_credentials' \
$AUTH_ROOT_URL/realms/professional/protocol/openid-connect/token | \
jq -r '.access_token')

echo $ACCESS_TOKEN

Example of Use

In this section, we will detail all the steps necessary to obtain personalized vaccination recommendations for a patient.

The context of use is as follows:

Before reading the following steps, we advise you to experiment with our online decision support tool, Mentor, which operates similarly to the integration of SADV in business software.

The steps to obtain vaccination recommendations are as follows:

  1. Retrieval of basic patient information
  2. Retrieval of the health profile questionnaire
  3. Completion of the health profile questionnaire
  4. Compilation of the patient file to send
  5. Retrieval of vaccination recommendations
  6. Display of vaccination recommendations

Steps 1 and 2 are optional. Their purpose is to retrieve additional information about the patient, which will refine the vaccination recommendations. This additional information constitutes the patient’s health profile.

We assume here that you already have access to the NUVA to encode the patient’s vaccination history as well as access to the VaccinationProfile library.

Step 1: Retrieval of Basic Information

It is assumed that the healthcare professional’s business software has already retrieved the following basic information: patient’s date of birth, gender, and optionally, their residential postal code.

Step 2: Retrieval of the Health Profile Questionnaire

To retrieve the health profile questionnaire, the client software must send an HTTP POST request to the /questionnaire URL of the SADV API.

For example, for a patient born on January 1, 2000, and male, the request is as follows (the postal code is not specified):

SADV_ROOT_URL=https://sadv.integration.mesvaccins.net
BIRTHDATE="2000-01-01"
GENDER="m"

curl -X POST "${SADV_ROOT_URL}/questionnaire" \
-H "Content-Type: application/json" \
-d '{
  "birthdate": "'"${BIRTHDATE}"'",
  "gender": "'"${GENDER}"'"
}'

For more details regarding this request, you can consult:

Step 3: Completion of the Health Profile Questionnaire

The previous call point returns, in the form of a tree, the hierarchical questions of the health profile questionnaire.

Each node of the tree is a section containing a title and a list of conditions to be entered by the user.

For each condition, its type (boolean, choice list, date, etc.) and its label are specified.

The client software must display the tree-like questionnaire to the user and collect their responses. The information collected constitutes the health profile. The client software can persist this information to avoid asking the user each time.

To implement the interface of the health profile questionnaire, we suggest following the functioning of the health questionnaire in our Mentor tool.

Here is an example of a questionnaire response:

[
  {
    "alert": {},
    "description": {},
    "help": {},
    "question": {
      "en": "General information",
      "fr": "Informations générales"
    },
    "title": {
      "en": "General information",
      "fr": "Informations générales"
    },
    "id": "c396ad68-b41a-4712-9627-655de08541a2",
    "sections": [
      {
        "alert": {},
        "description": {},
        "help": {},
        "question": {
          "en": "Other",
          "fr": "IDR - BCG"
        },
        "title": {
          "en": "Other",
          "fr": "IDR - BCG"
        },
        "id": "4c39da47-6db7-41ee-84a5-6ecdd2144703",
        "sections": [],
        "conditions": [
          {
            "id": "ba606ef4-9ebb-41b2-a81f-56a36bf8897e",
            "label": {
              "en": "IDR (mm)",
              "fr": "IDR (mm)"
            },
            "condition_type": "integer",
            "help": {
              "en": "Intradermal tuberculin test",
              "fr": "Intradermoréaction à la tuberculine"
            },
            "position": 1
          },
          {
            "id": "ad7d3400-7c63-4581-ba87-5688fba50fae",
            "label": {
              "en": "BCG vaccine scar",
              "fr": "Cicatrice vaccinale du BCG"
            },
            "condition_type": "boolean",
            "help": {
              "en": "This scar is usually located behind the deltoid muscle, the usual site of the intradermal injection of BCG. It shows that this vaccine, which allows the development of an immune response against the Koch's bacillus (the bacillus responsible for tuberculosis), has been administered. Consult your doctor for more information.",
              "fr": "Cette cicatrice est généralement située en retard du deltoïde, lieu habituel de l'injection par voie intradermique du BCG. Elle montre que ce vaccin, qui permet le développement d'une réponse immunitaire contre le bacille de Koch (le bacille responsable de la tuberculose), a été administré. Consultez votre médecin pour plus d'information à ce sujet."
            },
            "position": 2
          }
        ]
      }
    ],
    "conditions": []
  }
]

A questionnaire consists of sections, which themselves consist of either sections or conditions. Here are the details of a Section object:

A section can only contain other sections or conditions, but never both.

Here are the details of a Condition object:

Step 4: Compiling the Patient File to Send

The client software must compile a patient file to send to the SADV API. This patient file is a JSON object that contains:

Here is the list of possible parameters:

Here is an example of a patient file for a man born on January 30, 1988, in France, residing in Bordeaux, and who received a boostrixtetra vaccine on January 1, 2019:

{
  "patient": {
    "birthdate": "1988-01-30",
    "gender": "m",
    "prevention_acts": [
      {
        "date": "2019-01-01",
        "prevention_method_id": "384198db-b13c-4e08-b7a1-9311809a21b9"
      }
    ],
    "conditions": [
      {
        "id": "3e76320a-0b4d-4cb2-8095-764b19b08017",
        "value": true
      }
    ],
    "area_of_residency": {
      "zipcode": "33000"
    },
    "birthplace": {
      "countrycode": "FRA"
    }
  },
  "requested_by_professional": true
}

Step 5: Retrieval of Vaccination Recommendations

The retrieval of vaccination recommendations is done by sending an HTTP POST request to the /diagnostic_for_patient URL of the SADV API.

# paramètre variant selon l’environnement
SADV_ROOT_URL=https://api.fr.sad.mesvaccins.net

curl -X POST "${SADV_ROOT_URL}/diagnostic_for_patient" \
-H "Content-Type: application/json" \
-d '{
  "patient": {
    "birthdate": "1988-01-30",
    "gender": "m",
    "prevention_acts": [
      {
        "date": "2019-01-01",
        "prevention_method_id": "384198db-b13c-4e08-b7a1-9311809a21b9",
        "booster": false
      }
    ],
    "area_of_residency": {
      "zipcode": "33000"
    },
    "birthplace": {
      "countrycode": "FRA"
    }
  },
  "requested_by_professional": true
}'

The response from the request is a JSON object containing the vaccination recommendations for the patient.

Step 6: Displaying Vaccination Recommendations

The client software must display the vaccination recommendations to the healthcare professional. The graphical rendering of the vaccination recommendations is at the discretion of the client software.

The JSON object returned by the SADV API contains the following information:

Example of the API response:

{
  "conclusion": "late",
  "diagnostic_per_disease": [
    {
      "disease": {
        "id": "47cac099-7918-4329-9079-bdeb057957f0",
        "name": "Diphtérie",
        "translations": {
          "en": "Diphtheria",
          "fr": "Diphtérie"
        }
      },
      "prevention_acts_count": 1,
      "advice": {
        "conclusion": "late",
        "messages": [
          {
            "id": "badbce0e-3674-491b-8c29-d73e45736ce5",
            "message_type": "summary",
            "public_destination": "general",
            "contents": {
              "en": "Second dose at least 2 months after the first dose.",
              "fr": "Deuxième dose au moins 2 mois après la première dose."
            }
          }
        ],
        "targeted_date": "2019-03-01",
        "limit_date": "2019-03-31",
        "matching_conditions": ["3e76320a-0b4d-4cb2-8095-764b19b08017"],
        "documents": [
          {
            "id": "8c7a7a9d-536a-4560-b5b6-0993e2fbf880",
            "title": "Vaccination contre la diphtérie, le tétanos et la poliomyélite (dTP ou DTP) - Calendrier vaccinal 2023",
            "url": "",
            "file": {
              "filename": "2023-dtp.pdf",
              "url": "https://ged.mesvaccins.net/r9kh69n7bxvwgnvvv2hd0ahb4fh8"
            },
            "organization": "Ministère de la santé",
            "language": "fr",
            "target_audience": "health_professional",
            "publication_date": "2023-04-12"
          }
        ]
      }
    }
  ]
}

A diagnosis has an overall conclusion to quickly identify any necessary action. This conclusion is determined based on the priority of the status of one disease relative to others. Here is the list:

In the given example, the patient is behind in their vaccinations. Here are the other possible conclusions:

The detail by disease includes the target disease and the number of prevention acts performed. In this example, it’s diphtheria, for which 1 prevention act was performed. The “advice” field contains all messages related to the disease, with a conclusion indicating that the patient is late (“late”) for this disease. The “target_date” indicates that the vaccine should be administered from March 1, 2019, and the “limit_date” indicates that it should be done before March 31, 2019.

The “messages” field contains additional instructions that can be displayed to healthcare professionals or patients. In this example, the message is intended for both healthcare professionals and patients. The “documents” field contains files describing the official recommendations associated with the disease.

Finally, the “matching_conditions” field is an array of condition IDs that correspond to the conditions that had an impact on the result.