Documentation Connor

## Versions

### Prochaines version 2.17 "???" (TODO non-planifié)

### Prochaines version 2.17 "Kiddo" (TODO non-planifié)

 - Dette technique

 - Deployment docker

### Version 2.16 "Connor" (Branche connor)

# Migration Elasticsearch 6/7 vers 8.19.17 - Note Technique

## Info

Depuis la version *Connor* de *Oscar*, il est recommandé de mettre à niveau *Elasticsearch* (moteur de recherche). Ce document décrit cette procédure.

### Plan d'action

- Mise en maintenance de Oscar

- Suppression de l'ancienne version de Elasticsearch

- Installation de **Elasticsearch 8.x**

- Reconstruction des index de recherche

- Remise en service de Oscar

### Prérequis

- Accès root (pour l'installation des paquet)

## Mise en maintenance de OSCAR

```bash

# On se place à la racine de OSCAR

cd /var/oscar

touch MAINTENANCE

```

## Installation d'Elasticsearch 8

### Suppression de l'ancienne version

#### On coupe le service

```bash

# Arret Elasticsearch

systemctl stop elasticsearch

# On check

systemctl status elasticsearch

```

#### On supprime les anciennes données

```bash

# Voir le dossier des données

grep "path.data" /etc/elasticsearch/elasticsearch.yml | awk '{print $2}'

```

>Normalement c'est le dossier `/var/lib/elasticsearch`

```bash

# Suppression des anciens index

rm -rf /var/lib/elasticsearch/*

```

#### On désinstalle

```bash

# Désinstallation de Elastic

sudo apt-get remove --purge elasticsearch

sudo apt-get autoremove

```

> Pensez à retirer le vieux elasticsearch de votre **source.list** (/etc/apt/source.list.d/)

> Par exemple pour Elasticsearch 7 : 

> ```bash

> rm /etc/apt/sources.list.d/elastic-7.x.list

> ```

---

#### Installation de Elaasticsearch 8

La partie qui suit est issue de la documentation officielle : https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-elasticsearch-with-debian-package

```bash

# PGP singinig key

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg

```

```bash 

# APT transport si besoin

sudo apt-get install apt-transport-https

```

```bash 

# Ajout de Elasticsearch 8 au source.list

echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/9.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-9.x.list

```

```bash

# Mise à jour des paquets

sudo apt-get update

```

```bash

# Installation de elasticsearch 8

sudo apt-get install elasticsearch

```

#### Configuration

```bash 

nano /etc/elasticsearch/elasticsearch.yml

```

```yaml

# Nom du cluster (à adapter)

cluster.name: oscar-elasticsearch

# Nom du nœud

node.name: oscar-node-1

# Vérifier que le répertoire de données est bien

path.data: /var/lib/elasticsearch

# Vérifier que le répertoire de log est bien

path.logs: /var/log/elasticsearch

# Adresse réseau (écouter sur localhost ou l'IP du serveur)

network.host: 0.0.0.0

# Port HTTP

http.port: 9200

# Désactiver la sécurité (pour compatibilité initiale - à réactiver plus tard)

xpack.security.enabled: false

```

#### Démarage du service

Le serveur Elasticsearch est prêt

```bash

# Démarage du service

sudo systemctl daemon-reload

sudo systemctl enable elasticsearch

sudo systemctl start elasticsearch

# Note, le premier lancement peut être long (Une à deux minutes)

# Vérifier le statut

sudo systemctl status elasticsearch

# Vérifier que le service répond

curl -X GET "localhost:9200/"

```

On doit avoir : 

```json

{

  "name" : "oscar-node-1",

  "cluster_name" : "oscar-elastic",

  "cluster_uuid" : "umfB8SitSnOMa1hs37BAlw",

  "version" : {

    "number" : "9.5.4",

    "build_flavor" : "default",

    "build_type" : "deb",

    "build_hash" : "9170df19cae1adb107b7b489b4d82dec66d7a337",

    "build_date" : "2026-09-09T22:42:53.976833287Z",

    "build_snapshot" : false,

    "lucene_version" : "10.5.1",

    "minimum_wire_compatibility_version" : "8.19.0",

    "minimum_index_compatibility_version" : "8.0.0"

  },

  "tagline" : "You Know, for Search"

}

```

Si vous êtes arrivé ici, on a bientôt fini :)

#### Reconstruction de l'index de OSCAR

La première fois, les commandes vont prendre pas mal de temps

```bash

# depuis le dossier de OSCAR

php bin/oscar.php activity:search-rebuild

php bin/oscar.php organization:search-rebuild

php bin/oscar.php person:search-rebuild

php bin/oscar.php project:search-rebuild

```

Et voilà

#### On arrête la maintenance

```bash

rm MAINTENANCE

```

# MEMO ELASTICSEARCH

## Commandes utiles

### Version

```bash

# Voir la version installée

curl -XGET 'http://localhost:9200'

```

```json

{

    "name" : "woscar-pp",

    "cluster_name" : "elasticsearch",

    "cluster_uuid" : "acnHEqDORMCb8JbHoZexIg",

    "version" : {

        "number" : "7.17.29", <<< VERSION ICI

        "build_flavor" : "default",

        "build_type" : "deb",

        "build_hash" : "580aff1a0064ce4c93293aaab6fcc55e22c10d1c",

        "build_date" : "2025-06-19T01:37:57.847711500Z",

        "build_snapshot" : false,

        "lucene_version" : "8.11.3",

        "minimum_wire_compatibility_version" : "6.8.0",

        "minimum_index_compatibility_version" : "6.0.0-beta1"

    },

    "tagline" : "You Know, for Search"

}

```

### health

Voir l'état du *cluster*, status GREEN ou YELLOW attendu.

```bash

# Etat du cluster

curl "localhost:9200/_cat/health?v"

```

```

epoch      timestamp cluster       status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent

1789479699 13:41:39  elasticsearch yellow          1         1     15  15    0    0        8             0                  -                 65.2%

```

> Note : 

> Dans l'exemple, le status est **yellow** (ce qui n'est pas forcement un souci, typiquement si on utilise des index sans replicats)

### indices

Liste des index présents sur le serveur

```bash

# Liste des index

curl -s "localhost:9200/_cat/indices?v"

```

```

health status index              uuid                   pri rep docs.count docs.deleted store.size pri.store.size

green  open   .geoip_databases   lpla5pViSgmhohZQWwywXg   1   0         43            7     45.7mb         45.7mb

yellow open   oscar-activity     S9mcnvt8TE2RgixOZ6vL8A   1   1       7808            5      9.4mb          9.4mb

yellow open   oscar-person       HPFhTWooQZC-5kJUSjYNMA   1   1      16204            9      7.9mb          7.9mb

yelow open   oscar-organization BFbPKJQ3S0-NU7jYJ0QQBA   1   1       3288           62        8mb            8mb

```

### shards

```bash

# Liste des noeuds

curl -s "localhost:9200/_cat/shards?v"

```

 No newline at end of file

# OSCAR 2.16.x "Connor"

## Contenu de cette mise à jour

 - Mail template

 - API (Liste des conventions / PUSH)

 - Jalon : Déclencheurs

 - Avenants : Fichiers optionnels

 - Champs libres

 - Mail de jalon : Les jalons proposent une option pour envoyer un mail dédié aux personnes concernées

 - Jalon (modèle) : Enregistrement de "lots" de jalon préenregistrés permettant d'ajouter plusieurs jalons sur une activité en fonction d'une date de référence 

 - Refonte UI

 - Recherche des organisations : 

   - Nouvelle interface

   - Ajout d'un critère "d'usage"

 - Refonte moteur de recherche Organisation

 - Refonte moteur de recherche activité

 - Fiche personne : Ajout de boutons pour voir les activités/projet d'une personne

 - Versements : 

   - Nouvel écran pour le suivi/recherche

   - Option permettant de modifier rapidement en "Réalisé" les versements prévisionnels

 - Fiche Activité > Avenants

    - Le **document est optionnel** (mais requis pour appliquer l'avenant)

    - Le modificateur **Date de début** a été ajouté

 - Fiche activité > Champs libres : Système normalisé pour ajouter des champs à la fiche activité

 - Recherche activité :

   - Les jalons sont affichés dans les résultats avec un code couleur pour identifier les jalons en retard

   - La recherche est plus rapide, elle est appliqué lors des changements de filtre

   - Nouveau filtre **Actif l'année**

   - Nouveau filtre **N°API**

   - Ajout d'un filtre **champ personnalisé**

   - Amélioration du filtre **Jalon** : 

     - On peut recherche les jalons "à faire" sans spécifier le type de jalon 

     - On peut chercher des dates

 - API

   - Activité Liste : On peut extraire les données détaillées des activités (JSON)

   - Activité PUSH : Une API permet de synchroniser des données via JSON (inclus le push de document)

 - Optimisation des requêtes "todo"

### Général

 - Nouveau système de recherche (Elasticsearch 8), les résultats des recherches sont beacoup plus rapide

 - Refonte UI / optimisation

 - Textes disponibles dans l'interface mis à jour

 - Zone de saisie des personnes améliorée

 - Zone de saisie des organisations améliorée

 - Zone de saisie des activités améliorée

### Activités

- LISTE

    - Nouveau moteur de recherche

    - Ajout des jalons dans les résultats avec un code couleurs pour identifier les jalons en retard facilement

    - Filtres ajoutés : N°API, Actif l'année XXXX, Champs personnalisés

    - Filtre JALON : Le type est optionnel, ajout de dates (entre DATE et DATE)

- FICHE

    - Nouvelle interface,

    - Onglets de synthèse

    - Avenants :

        - Le fichier est maintenant optionnel tant que l'avenant n'est pas appliqué

        - Le modificateur "Date de début" a été ajouté

    - On peut configurer des champs personnalisés

    - On peut configurer des rôles de personnes/organisation pour les proposer directement dans la fiche de saisie.

### Personnes

- Nouveau moteur de recherche

- FICHE : Ajout d'un bouton "Voir les contrats/projets"

### Organisations

 - Nouveau moteur de recherche

 - Ajout d'un filtre sur les organisations "utilisées"

### Versements

 - Moteur de recherche (Administrateurs, Reponsable de structures) 

   - Filtre : N°financier/N°de contrat, Dates, Montant

   - Actions rapides (passer en réalisé)

### Jalons

 - Moteur de recherche

   - Mode personnel/structure/global

   - Recherche par N°Financier/contrat, acronyme

   - Filtre : Type, état de réalisation, dates

   - Interaction rapide (pour les jalons à progression)

 - On peut maintenant configurer les types de jalons pour qu'ils envoient un mail dédié (ex: envoyer un mail pour les rapports financiers)

 - Enregistrement de "lots" de jalon préenregistrés permettant d'ajouter plusieurs jalons sur une activité en fonction d'une date de référence

 - Déclencheurs (détails plus loin)

### Déclencheurs

- Note technique : Cette fonctionnalité impose la mise en place une tâche automatisée (CRON) journalier sur le serveur (pour certaines actions)

 - Système permettant de programmer des actions en fonction de certains événements

 - Déclencheurs : 

   - état d'un jalon modifié (Type de jalon, passe à l'état...)

   - une date de la fiche est atteinte (Début, fin, signature, etc...)

   - un document a été déposé (Choix du type)

 - Actions : 

   - Créer un Jalon (date programmable en fonction du déclencheur)

   - Envoyer un mail (Template, choix des rôles concernés)

   - Modifier une date dans l'activité

   - Modifier le statut de l'activité

 > Nous invitons les fonctionnels à proposer d'autres Déclencheurs à ajouter et d'autres actions à ajouter

### API

 - Liste des activités

 - *Push* : Permet à une application tiers d'envoyer des activités/mettre à jour des activités (inclus l'envoi de document)

### Technique

 - Passage à Elasticsearch 8

 - Compilation d'interface optimisée (les fichiers ont un HASH pour éviter la mise en cache excessive)

 - Mail template

 - API

   - Modification des en-têtes d'accès (Ajout de headers `x-api-user` / `x-api-key`) 

 - Recherche générale

   - Système de recherche en direct depuis l'index (plus rapide)

     - Refonte du *mapping* des données (méthode de référencement)

   - Refonte du *mapping* des données référencées > **reconstruction de l'index requis**

## Mise en place technique

Basculer sur la branche "connor"

### Prérequis

 - Debian à jour (12+) - testé sur Trixie (13)

 - PHP 8.2 (Pas de changement)

 - Postgresql (Pas de changement - Testé sur 18+)

 - **Elasticsearch 8.x** ([Mettre à jour Elasticsearch](./../technique/elasticsearch-7-to-8.md )

Cette version impose une mise à jour de *Elasticsearch* pour la version **8.x**

```bash

# Actualisation du dépôt

git fetch