Interface entrante « Organigramme » — Référence du schéma `OrganigrammeV8.xsd`

Table des matières

Interface entrante « Organigramme » — Référence du schéma OrganigrammeV8.xsd

Ce document décrit chaque élément et chaque attribut du fichier XML d’organigramme accepté par l’interface entrante de GEEF, ainsi que la structure hiérarchique attendue. Il croise la définition du schéma (OrganigrammeV8.xsd) avec le comportement réel du code d’intégration (InterfaceGEEFInXML.java) et des classes du modèle (OrgService, OrgServiceVersion, OrgServiceTranscode, OrgTypeService, OrgTypeServiceRelation).

Fichier XSD : OrganigrammeV8.xsd (voir installation de GEEF/Virtualia)
Point d’entrée d’intégration : InterfaceGEEFInXML.departement(...) → processService(...) (routage sur l’élément racine Departement, cf. InterfaceGEEFInXML.java).
Après intégration : rechargement complet du cache organigramme via OrgServlet.chargerOrg().

1. Vue d’ensemble de la hiérarchie

Departement                     ← élément racine (attr. Extraction requis)
├── Types            (0..n)     ← DICTIONNAIRE GLOBAL des types de service
│   └── LibelleType  (1)
├── Services         (1..n)     ← services RACINES de l'arbre
    ├── LibelleService (1)      ← identifiant / nom par défaut du service
    ├── Versions       (0..n)   ← état daté du service (libellé, mail, adresse…)
    │   ├── LibelleService     (1)
    │   ├── EmailService       (0..1)
    │   ├── Contact            (0..1)
    │   ├── AdresseRue         (0..1)
    │   ├── AdresseBatiment    (0..1)
    │   ├── AdresseCodePostal  (0..1)
    │   ├── AdresseVille       (0..1)
    │   └── Telephone          (0..1)
    ├── Types          (0..n)   ← AFFECTATION d'un type (du dictionnaire) au service
    │   └── LibelleType (1)
    ├── CodesServices  (0..n)   ← codes d'interface / nomenclature du service
    │   └── CodeService (1)
    └── Services       (0..n)   ← sous-services (récursif) = relation parent → enfant

⚠️ Point d’attention majeur — l’élément Types a deux significations distinctes selon son parent :

Sous Departement (TypesServicesType) : il déclare un type de service dans le dictionnaire global, avec tous ses drapeaux fonctionnels (EstFMPA, EstInterne…).

Sous un Services (ServicesTypesType) : il rattache ce service à un type déjà déclaré, sur une période (DateDebut/DateFin). Le rapprochement se fait par le LibelleType (clé métier). Si le type n’existe pas encore, il est créé à la volée avec des valeurs par défaut (trace ALERTE - Type de service inconnu).

2. Types simples (contraintes de valeur)

Tous les types texte sont des xsd:string avec une longueur bornée ; toute valeur hors bornes est rejetée à la validation.

Type simple	Base	Long. min	Long. max	Rôle
`CodeServiceType`	string	1	20	Code du service (interfaces / nomenclature)
`LibelleServiceType`	string	1	200	Libellé d’un service
`EmailServiceType`	string	1	200	Adresse courriel du service
`ContactType`	string	1	200	Nom du contact (publipostage, services externes)
`AdresseRueType`	string	1	100	N°, nature et nom de la voie
`AdresseBatimentType`	string	1	30	Bâtiment / complément d’adresse
`AdresseCodePostalType`	string	1	5	Code postal
`AdresseVilleType`	string	1	50	Ville
`TelephoneType`	string	1	20	Téléphone
`CodeTypeServiceType`	string	1	20	Code du type de service — désuet
`LibelleTypeServiceType`	string	1	200	Libellé du type de service (sert de clé)
`BooleenType`	int	—	—	Booléen : `0` = faux, `1` = vrai (borné à [0,1])

Convention booléenne à l’intégration. Le code lit un BooleenType par comparaison stricte à la chaîne "1" :

pour la plupart des drapeaux (Est… des types, EstEntrant/EstSortant/EstNomenclature des codes, EstManuel) : 1 ⇒ vrai, tout le reste (absent, 0, vide) ⇒ faux ;
exception EstActif (sur Versions) : faux uniquement si la valeur vaut explicitement 0 ; absent ou toute autre valeur ⇒ actif (true).

Convention de dates. Les attributs de date (DateEffet, DateDebut, DateFin) sont typés xsd:date dans le schéma, mais l’intégration tolère deux formats en entrée : AAAA-MM-JJ (MySQL) ou JJ/MM/AAAA (Java). Un format non reconnu lève une erreur d’intégration. Valeurs par défaut appliquées quand l’attribut est absent :

DateEffet (version) et DateDebut (type / code / relation) ⇒ 01/01/1900 ;
DateFin absente ⇒ NULL (validité illimitée).

3. Élément racine `Departement`

Type : DepartementType. Élément racine du document.

Attributs

Attribut	Type	Occurrence	Description
`Extraction`	`xsd:dateTime`	requis	Date/heure d’extraction de l’organigramme. Sert de garde anti-régression : cf. ci-dessous.

Rôle de Extraction (garde anti-rejeu). Avant tout traitement, verifDateExtraction(...) compare (comparaison de chaînes) la valeur reçue à la dernière valeur intégrée, stockée dans PARAMETRES sous Date Extraction - Departement. Si la nouvelle date est antérieure ou égale à la précédente, l’intégration est rejetée (« La date d’extraction est antérieure ou égale à celle du dernier fichier reçu »). Cela évite de réintégrer un ancien fichier lors d’une reprise sur interruption. Une valeur vide provoque également une erreur.

Enfants

Enfant	Type	Occurrence	Description
`Types`	`TypesServicesType`	0..n	Déclarations du dictionnaire global des types de service (voir §4). Traités en premier, uniquement s’ils sont enfants directs de `Departement`.
`Services`	`ServicesType`	1..n	Services racines de l’arbre (voir §5). Tous les services directement sous `Departement` sont des racines.

Ordre de traitement. Le dictionnaire (Departement/Types) est intégralement traité avant les services, afin que chaque affectation de type (Services/Types) puisse être rapprochée d’un type déjà connu.

4. `Departement/Types` — dictionnaire global (`TypesServicesType`)

Déclare un type de service et ses caractéristiques fonctionnelles. Persisté dans la table TYPES_SERVICES (OrgTypeService). Le rapprochement création/mise à jour se fait par LibelleType (getOrgTypeServiceByName).

Enfant

Enfant	Type	Occurrence	Description
`LibelleType`	`LibelleTypeServiceType`	1	Libellé du type — clé/identifiant du type. Obligatoire et non vide (sinon erreur).

Attributs (tous optionnels, `BooleenType`)

Attribut	Colonne	Description fonctionnelle
`EstFMPA`	`EST_FMPA`	Le service peut servir à créer des FMPA sur centre.
`EstOrganisateurFrm`	`EST_ORGANISATEUR_FRM`	Le service peut être organisateur de sessions de stages.
`EstMutualisation`	`EST_MUTUALISATION`	Le service accepte un positionnement en « mutualisation » (affectation secondaire/officieuse).
`EstBassin`	`EST_BASSIN`	Le service est un bassin de formation (interface FOAD « EducExpert » — désuet).
`EstStockageEquipement`	`EST_STOCKAGE_EQUIPEMENT`	Un équipement (salle, engin…) peut être affecté dans ce service.
`EstEmplacementGarde`	`EST_EMPLACEMENT_GARDE`	Un agent peut être positionné en garde dans ce service (interface entrante des gardes).
`EstExterne`	`EST_EXTERNE`	Un agent externe peut y être affecté. Cumulable avec `EstInterne`.
`EstInterne`	`EST_INTERNE`	Un agent interne peut y être affecté. Cumulable avec `EstExterne`.
`EstDepartement`	`EST_DEPARTEMENT`	Recueil des besoins collectif : positionné au niveau racine (le plus haut).
`EstGroupe`	`EST_GROUPE`	Recueil des besoins collectif : niveau intermédiaire (branche).
`EstCentre`	`EST_CENTRE`	Recueil des besoins collectif : niveau le plus bas (feuille).

Mise à jour incrémentale. Pour un type existant, seul un drapeau présent dans le XML et différent de la valeur en base est modifié ; un drapeau absent laisse la valeur en base inchangée (les attributs sont lus en Boolean nullable). À la création, un drapeau absent vaut false.

Caveats techniques (constatés dans le code, hors schéma) :

EstEmplacementGarde est lu à l’intégration du dictionnaire avec un nom d’attribut comportant une espace finale ("EstEmplacementGarde "), si bien qu’en pratique ce drapeau n’est pas repris depuis Departement/Types. (Il reste correctement géré côté service et à l’export.)

Un attribut EstEquipe est lu par le code mais n’est ni stocké ni utilisé (aucune colonne correspondante) : il est de fait ignoré. Il n’est pas déclaré dans le XSD.

À l’export uniquement, OrgTypeService.toXML() ajoute un attribut IdTypeService (identifiant technique). Il n’est pas relu à l’import et n’est pas dans le XSD.

5. `Services` — un service de l’arbre (`ServicesType`)

Représente un service organisationnel. Persisté dans SERVICES (OrgService). Le rapprochement création/existant se fait par le libellé par défaut (getOrgServiceByName, sur NOM_SERVICE_DEFAUT).

Enfants (dans l’ordre du schéma)

Enfant	Type	Occurrence	Description
`LibelleService`	`LibelleServiceType`	1	Identifiant / nom par défaut du service. Ce n’est pas nécessairement un libellé affiché : ça peut être un code technique. Il sert de clé de rapprochement de l’interface et doit être en première position (le 1er `LibelleService` enfant direct de `Services`). Non vide, unique dans le service.
`Versions`	`ServicesVersionType`	0..n	États datés du service (voir §5.1).
`Types`	`ServicesTypesType`	0..n	Affectations de type au service (voir §5.2).
`CodesServices`	`CodesServicesType`	0..n	Codes d’interface / nomenclature (voir §5.3).
`Services`	`RelationsServicesType`	0..n	Sous-services (récursif) — relation parent→enfant datée (voir §5.4).

Distinction des deux LibelleService. Le LibelleService enfant direct de Services est le nom par défaut (identifiant). Le LibelleService situé dans un Versions est le libellé applicable à partir de la date d’effet (celui affiché aux utilisateurs).

Sémantique de suppression (synchronisation « miroir »). À l’intégration d’un service, les sous-objets présents en base mais absents du XML sont supprimés afin de refléter exactement le fichier :

Versions et relations de sous-services : toujours supprimées si absentes du XML ;
affectations de type et codes/transcodes : supprimés sauf s’ils sont marqués EstManuel (saisie manuelle GEEF, protégée de l’écrasement par interface).

5.1. `Services/Versions` — état daté (`ServicesVersionType`)

Une version décrit l’état du service à partir de sa date d’effet. Persistée dans SERVICES_VERSIONS (OrgServiceVersion), clé composée (ID_SERVICE_ORG, DATE_EFFET).

Attributs

Attribut	Type	Occurrence	Description
`DateEffet`	`xsd:date`	optionnel	Date à partir de laquelle les valeurs de la version s’appliquent. Absente ⇒ `01/01/1900`. Sert aussi de clé de version (une version par date d’effet).
`EstActif`	`BooleenType`	optionnel	État du service à partir de `DateEffet` (et non « état de la version »). Faux uniquement si `0` ; sinon actif.

Enfants

Enfant	Type	Occ.	Colonne	Description
`LibelleService`	`LibelleServiceType`	1	`NOM_SERVICE`	Libellé du service applicable à partir de `DateEffet`. Obligatoire, non vide.
`EmailService`	`EmailServiceType`	0..1	`MAIL_SERVICE`	Adresse courriel.
`Contact`	`ContactType`	0..1	`NOM_CONTACT_SERVICE`	Nom du contact (services externes / publipostage).
`AdresseRue`	`AdresseRueType`	0..1	`ADR_RUE_SERVICE`	Rue de l’adresse.
`AdresseBatiment`	`AdresseBatimentType`	0..1	`ADR_BAT_SERVICE`	Bâtiment / complément.
`AdresseCodePostal`	`AdresseCodePostalType`	0..1	`ADR_CP_SERVICE`	Code postal.
`AdresseVille`	`AdresseVilleType`	0..1	`ADR_VIL_SERVICE`	Ville.
`Telephone`	`TelephoneType`	0..1	`ADR_TEL_SERVICE`	Téléphone.

Résolution temporelle (lecture). Pour une date donnée, la version applicable est la plus récente dont DateEffet ≤ date (parcours décroissant, cf. getNameFromDate, getMailFromDate, versionActiveDateEffet). D’où :

la 1re version (chronologiquement) doit être active : sa DateEffet marque la « naissance » du service ;
une dernière version inactive (EstActif=0) marque la fermeture : le service est actif jusqu’à la veille de cette date d’effet ;
plusieurs changements simultanés (libellé + mail + adresse…) partagent la même DateEffet dans une seule version.

Caveats techniques (hors schéma) :

Les sous-éléments d’adresse et Contact ne sont relus depuis le XML que dans un cas particulier de mise à jour d’une version existante (paramètre applicatif *« Interface entrante

XML - Vider mails services »* à OUI, et mail entrant vide). En dehors de ce cas, une version nouvelle ne renseigne que LibelleService, EmailService et EstActif depuis le flux ; les autres champs restent tels quels en base.

Un attribut EstAnnuaire (visibilité dans l’annuaire, colonne AFFICHAGE_ANNUAIRE) est géré par le code (lecture sur mise à jour + export toXML) mais n’est pas déclaré dans le XSD. Par défaut, une version est affichée dans l’annuaire.

5.2. `Services/Types` — affectation d’un type (`ServicesTypesType`)

Rattache le service à un type du dictionnaire global (§4) sur une période. Persisté dans SERVICES_TYPES_SERVICES (OrgTypeServiceRelation), clé composée (service, type).

Enfant

Enfant	Type	Occurrence	Description
`LibelleType`	`LibelleTypeServiceType`	1	Libellé du type — clé de rapprochement avec le dictionnaire. Obligatoire, non vide. Si inconnu, le type est créé avec des valeurs par défaut (trace `ALERTE`).

Attributs

Attribut	Type	Occurrence	Description
`DateDebut`	`xsd:date`	optionnel	Début de validité du type pour ce service. Absente ⇒ `01/01/1900`.
`DateFin`	`xsd:date`	optionnel	Fin de validité du type pour ce service. Absente ⇒ illimitée (`NULL`).

Caveat (hors schéma) : un attribut EstManuel est lu ici (OrgTypeServiceRelation). À 1, l’affectation est réputée saisie manuellement et protégée de la suppression automatique lors de la synchronisation miroir. Il n’est pas déclaré dans le XSD (usage plutôt interne / export).

5.3. `Services/CodesServices` — codes d’interface (`CodesServicesType`)

Codes (« transcodes ») du service utilisés par les interfaces et la nomenclature. Persisté dans SERVICES_TRANSCODES (OrgServiceTranscode).

⚠️ Le CodeService n’est pas l’identifiant du service pour cette interface (celui-ci est le LibelleService par défaut), même s’il peut être identique. Il sert aux autres interfaces (liste du personnel, etc.) et à la nomenclature.

Enfant

Enfant	Type	Occurrence	Description
`CodeService`	`CodeServiceType`	1	Valeur du code. Obligatoire, non vide.

Attributs

Attribut	Type	Occ.	Colonne	Description
`DateDebut`	`xsd:date`	optionnel	`DATE_DEBUT`	Début de validité. Absente ⇒ `01/01/1900`.
`DateFin`	`xsd:date`	optionnel	`DATE_FIN`	Fin de validité. Absente ⇒ illimitée (`NULL`).
`EstEntrant`	`BooleenType`	optionnel	`EST_ENTRANT`	Code utilisable pour les interfaces entrantes (ex. liste du personnel).
`EstSortant`	`BooleenType`	optionnel	`EST_SORTANT`	Code utilisable pour les interfaces sortantes (utile si le code entrant ≠ code sortant).
`EstNomenclature`	`BooleenType`	optionnel	`EST_NOMMENCLATURE`	Code utilisable pour nommer certains objets (ex. sessions de stages du service organisateur). Généralement non géré par un système tiers.

Caveats techniques :

L’attribut XSD s’écrit EstNomenclature (un seul m) ; la colonne en base est EST_NOMMENCLATURE (deux m). Utiliser l’orthographe du schéma dans le XML.

Un attribut EstManuel est également lu ici et protège le code de la suppression automatique (même logique qu’en §5.2). Hors schéma.

5.4. `Services/Services` — sous-services (`RelationsServicesType`)

Déclare les enfants directs du service courant : c’est le mécanisme qui construit l’arbre. Le type RelationsServicesType étend ServicesType : un sous-service a donc exactement la même structure qu’un service (récursivité — il peut à son tour porter Versions, Types, CodesServices et ses propres Services), plus deux attributs décrivant la relation parent→enfant. La relation est persistée dans RELATIONS_SERVICES (OrgServiceRelation).

Attributs additionnels (par rapport à `ServicesType`)

Attribut	Type	Occurrence	Description
`DateDebut`	`xsd:date`	optionnel	Début de validité de la relation parent→enfant. Absente ⇒ `01/01/1900`.
`DateFin`	`xsd:date`	optionnel	Fin de validité de la relation. Absente ⇒ illimitée (`NULL`).

Multi-parenté et cycles. Un même service peut apparaître comme enfant de plusieurs parents (multi-parenté gérée : cheminParentsADateEffet concatène alors les chemins). Le chargement de l’arbre contrôle les cycles sur plusieurs générations d’ascendance (cf. sqlServicesRelations) pour éviter les boucles.

Caveat (hors schéma) : à l’export, OrgService.toXML() ajoute un attribut IdService (identifiant technique). Il est ignoré à l’import (le rapprochement se fait sur le libellé par défaut) et n’est pas déclaré dans le XSD.

6. Exemple minimal

<?xml version="1.0" encoding="UTF-8"?>
<Departement Extraction="2026-08-04T09:30:00">

  <!-- 1) Dictionnaire global des types -->
  <Types EstInterne="1" EstEmplacementGarde="1">
    <LibelleType>Centre de secours</LibelleType>
  </Types>
  <Types EstOrganisateurFrm="1">
    <LibelleType>Groupement</LibelleType>
  </Types>

  <!-- 2) Arbre des services (racine → enfants) -->
  <Services>
    <LibelleService>GSE</LibelleService>            <!-- identifiant / nom par défaut -->
    <Versions DateEffet="2020-01-01" EstActif="1">
      <LibelleService>Groupement Sud-Est</LibelleService>
      <EmailService>gse@sdis.fr</EmailService>
    </Versions>
    <Types DateDebut="2020-01-01">
      <LibelleType>Groupement</LibelleType>          <!-- rapproché du dictionnaire -->
    </Types>
    <CodesServices DateDebut="2020-01-01" EstEntrant="1" EstSortant="1">
      <CodeService>GSE</CodeService>
    </CodesServices>

    <!-- sous-service (même structure, + dates de relation) -->
    <Services DateDebut="2020-01-01">
      <LibelleService>CS_LYON</LibelleService>
      <Versions DateEffet="2020-01-01" EstActif="1">
        <LibelleService>Centre de secours de Lyon</LibelleService>
      </Versions>
      <Types DateDebut="2020-01-01">
        <LibelleType>Centre de secours</LibelleType>
      </Types>
    </Services>
  </Services>

</Departement>

7. Aide-mémoire des correspondances XML → base

Élément XML	Classe Java	Table	Clé de rapprochement
`Departement`	(routage)	`PARAMETRES` (garde `Extraction`)	—
`Departement/Types`	`OrgTypeService`	`TYPES_SERVICES`	`LibelleType` (`NOM_TYPE_SERVICE`)
`Services`	`OrgService`	`SERVICES`	`LibelleService` par défaut (`NOM_SERVICE_DEFAUT`)
`Services/Versions`	`OrgServiceVersion`	`SERVICES_VERSIONS`	`(service, DateEffet)`
`Services/Types`	`OrgTypeServiceRelation`	`SERVICES_TYPES_SERVICES`	`(service, type)`
`Services/CodesServices`	`OrgServiceTranscode`	`SERVICES_TRANSCODES`	valeurs (code + drapeaux + dates)
`Services/Services`	`OrgServiceRelation`	`RELATIONS_SERVICES`	`(père, fils)`

Récapitulatif des écarts schéma ↔ implémentation

Attributs présents dans le code mais non déclarés dans OrganigrammeV8.xsd (utilisés surtout en interne ou à l’export sortant) :

Versions/@EstAnnuaire — visibilité annuaire (AFFICHAGE_ANNUAIRE).
Services/Types/@EstManuel et CodesServices/@EstManuel — protège l’objet de la suppression automatique par interface.
Departement/Types/@EstEquipe — lu mais non persisté (ignoré).
@IdService (sur Services) et @IdTypeService (sur Types) — écrits à l’export, ignorés à l’import.

Interface entrante « Organigramme » — Référence du schéma OrganigrammeV8.xsd

1. Vue d’ensemble de la hiérarchie

2. Types simples (contraintes de valeur)

3. Élément racine Departement

Attributs

Enfants

4. Departement/Types — dictionnaire global (TypesServicesType)

Enfant

Attributs (tous optionnels, BooleenType)

5. Services — un service de l’arbre (ServicesType)

Enfants (dans l’ordre du schéma)

5.1. Services/Versions — état daté (ServicesVersionType)

Attributs

Enfants

5.2. Services/Types — affectation d’un type (ServicesTypesType)

Enfant

Attributs

5.3. Services/CodesServices — codes d’interface (CodesServicesType)

Enfant

Attributs

5.4. Services/Services — sous-services (RelationsServicesType)

Attributs additionnels (par rapport à ServicesType)

6. Exemple minimal

7. Aide-mémoire des correspondances XML → base

Récapitulatif des écarts schéma ↔ implémentation

Interface entrante « Organigramme » — Référence du schéma `OrganigrammeV8.xsd`

3. Élément racine `Departement`

4. `Departement/Types` — dictionnaire global (`TypesServicesType`)

Attributs (tous optionnels, `BooleenType`)

5. `Services` — un service de l’arbre (`ServicesType`)

5.1. `Services/Versions` — état daté (`ServicesVersionType`)

5.2. `Services/Types` — affectation d’un type (`ServicesTypesType`)

5.3. `Services/CodesServices` — codes d’interface (`CodesServicesType`)

5.4. `Services/Services` — sous-services (`RelationsServicesType`)

Attributs additionnels (par rapport à `ServicesType`)