Connexion GraphDB <--> Colectica

--- title: Connexion GraphDB <--> Colectica tags: RMéS --- # Connexion des référentiels DDI et RDF L'objectif de ce document est de préciser les besoins de connexion des deux référentiels DDI (Colectica) et RDF (GraphDB). Le postulat de départ est qu'un référentiel est maître sur le deuxième pour un type de métadonnées et que pour réutiliser les métadonnées d'un référentiel maître, il est nécessaire de les reporter physiquement dans le référentiel esclave. L'approche de la note est celle des user stories. Il ne s'agit pas d'être exhaustif sur le long terme mais plutôt de formaliser les besoins identifiés à ce jour. Cette note n'aborde pas les questions techniques. ## Les objets Les objets dans le référentiel RDF : - en production - concepts - nomenclatures statistiques - nomenclatures géographiques - les opérations statistiques, indicateurs et rapports qualité - à venir - les définition de structures de données (DSD) - les descriptions de jeux de données - les questionnaires Les objets dans le référentiel DDI : - à venir - les variables représentées - les questionnaires :::info Les listes de codes ne sont pas traitées ici en attendant une réunion de brainstorming sur le sujet des listes de codes dans RMéS ::: ## Les besoins ### User stories **User story 1 : En tant que chargé d'une étude sur le chômage, je souhaite rechercher toute la documentation de référence (variables, questionnaires, description des jeux de données...) en lien avec le concept de chômage afin de documenter mon étude.** *Précision : ce récit suppose que l'on a associé des concepts aux questions.* Ce récit implique de disposer des concepts dans Colectica pour réaliser la recherche (*cela permettra également d'associer des concepts aux questions via Pogues ou aux variables via Colectica*). :::info **La proposition est de récupérer :** - concept (uri, libellé français, libellé anglais, libellé alternatif français, libellé alternatif anglais, définition longue français non formatée, définition longue anglais non formatée). Les autres informations ne sont pas récupérées : note éditoriale, définition courte, relation entre concepts... ::: --- **User story 2 : en tant que MOA du RP, je souhaite connaître l'ensemble de la documentation de mes séries d'opérations statistiques (rapport qualité, questionnaire et dictionnaire de variables) afin d'en améliorer le contenu** **User story 3 : en tant que concepteur de l'enquête TIC entreprises, je souhaite créer un questionnaire dans Pogues afin de réaliser la collecte à venir** *Précision : lors de la création d'un questionnaire, il est nécessaire de l'associer à sa (ou ses) campagne(s) de collecte. Il s'agit de le "ranger" dans le référentiel. À noter que même si l'endroit où les campagnes de collecte sont gérées n'est pas connu, cela ne pose pas de problème à la réflexion actuelle.* Ces deux récits impliquent de disposer de l'arborescence Famille/Série/Opération dans Colectica. :::info **La proposition est de récupérer :** - Famille (uri, intitulé français, intitulé anglais, relation avec les séries enfants) - Série (uri, intitulé français, intitulé anglais, nom court français, nom court anglais, relation avec les opérations enfants) - Opération (uri, intitulé français, intitulé anglais, nom court français, nom court anglais) Toutes les autres informations (rapports qualité, indicateurs...) ne sont pas récupérées. ::: --- **User story 4 : En tant que concepteur de l'enquête TIC Entreprises, je souhaite utiliser la liste des activités économiques niveau 5 afin de collecter l'activité de l'entreprise** **User story 5 : En tant que producteur de la base tous salariés (DSN), je souhaite utiliser la liste hiérarchique des activités économiques afin de documenter mon fichier de microdonnées** Ces deux récits impliquent de disposer de la Naf rév. 2 dans Colectica (que l'on peut étendre à d'autres nomenclatures comme la PCS 2003, la PCS 2020, la PCS-ESE 2017 et la dernière nomenclature des catégories juridiques). :::info **La proposition est de récupérer :** - la nomenclature (uri, libellé) et la liste hiérarchique des postes qui la compose (uri, valeur du code, niveau du code, libellé français, libellé anglais, relation avec son parent/enfant). Toutes les autres informations (titres abrégés, notes explicatives...) ne sont pas récupérées. Ces informations étant stables, il est également proposé de réaliser cette étape manuellement et non automatiquement. ::: --- **User story 6 : En tant que concepteur de l'enquête SRCV, je souhaite utiliser la liste des départements afin de collecter le département de naissance** **User story 7 : En tant que producteur de l'EEC, je souhaite utiliser la liste des communes au 1er janvier 2021 pour documenter mon fichier de microdonnées (ex : variable "Code commune du logement de résidence")** Ces récits impliquent de disposer de la liste des départements et communes au 1er janvier dans Colectica. On peut étendre ce besoin aux nouvelles et anciennes régions. À voir s'il faudra une liste des communes à date. :::info **La proposition est de récupérer :** - la liste de départements (uri, libellé de la liste en français) et les départements (uri, libellé français) Idem pour les anciennes/nouvelles régions et communes. Toutes les autres informations (prédécesseurs/successeurs, parent/enfant...) ne sont pas récupérées. À ce stade, il n'y a pas d'utilisation d'une liste hiérarchique dans Colectica...cependant, les producteurs ont tendance à renvoyer sur des pages du COG sur insee.fr. S'il n'y a pas de besoin de hiérarchie, il suffit d'initialiser manuellement la liste des départements et régions manuellement, ces derniers changeant très peu. Ce besoin reste à affiner notamment pour les communes. De plus, les listes de codes sur la géographie ne sont actuellement pas disponibles dans RMéS. Il est vraisemblablement préférable d'attendre ces objets pour les mettre à jour dans Colectica (voire le brainstorming sur les listes de codes dans RMéS). ::: --- :::info **Synthèse** Les objets suivants sont à récupérer dans le référentiel esclave avec un minimum d'information : | Objet | Source | Cible | Type de réplication | |:-------------------------------:| --------- | ---------- | ----------- | | Concepts | GraphDB | Colectica | Automatique | | Opérations statistiques (F/S/O) | GraphDB | Colectica | Automatique | | Nomenclatures statistiques (NAF rév. 2, PCS 2003, PCS 2020, PCS-ESE 2017, CJ)| GraphDB| Colectica | Manuelle | | Géographie (région, département, commune) | GraphDB | Colectica | À affiner selon besoin | Les autres objets tels les questionnaires, variables représentées, DSD et descriptions de jeux de données ne sont à ce jour pas identifiées comme devant être récupérés dans l'autre référentiel. ::: --- ### La fraîcheur de l'information L'ensemble des métadonnées à récupérer sont à ce stade dans le sens GraphDB (RDF) --> Colectica (DDI). Ainsi, pour ces objets, le processus de haut niveau se décrit simplement : 1. Le responsable gère (création, modification) ses métadonnées 2. Le responsable publie ses créations/modifications de métadonnées dans le référentiel GraphDB 3. L'information publiée dans le référentiel GraphDB est également publiée dans le référentiel Colectica Au départ, l'idée était de s'appuyer sur un système de notification où un référentiel écoute des évènements arrivant sur l'autre référentiel. Par exemple : le référentiel Colectica écoute les évènements de création de concepts et, lorsqu'il est informé d'une création, crée automatiquement le concept dans Colectica. Un avantage est que cette solution peut constituer une offre de services aux clients du référentiel RMéS, donc au-delà d'une solution interne au système d'information RMéS. Cependant, ces objets (concepts, nomenclatures statistiques et géographiques, F/S/O) sont relativement stables et le besoin n'est pas forcément de disposer d'une information *immédiatement* à jour dans le référentiel Colectica. :::info L'équipe RMéS définira la solution à apporter. En fonction de la solution, si écouter un évènement comme la mise à jour d'un concept revient à écouter toute mise à jour du concept, c'est-à-dire y compris des informations non reportées dans Colectica, cela ne doit pas poser de problème. ::: :::warning **Fin de la relecture, la suite est + technique et encore en work in progress. Si un curieux souhaite relire et me dire si c'est compréhensible ou me dire les compléments à apporter pour mieux expliciter la spec, je prends.** ::: ## Spécification détaillée : la modélisation DDI Chaque objet identifiable et versionnable du référentiel est identifié via le triplet : - Agency - ID - Version On notera que cela signifie que chaque version d'un objet reste présent physiquement dans le référentiel et ne peut être écrasé. Le principe actuellement mis en oeuvre dans Colectica est le suivant : 1. Si un objet ne change pas, alors celui-ci est réutilisé 1. Si un objet évolue, alors le principe retenu est de créer un nouvel objet basé sur son prédecesseur. 1. Si un objet "change", notamment pour corriger une erreur ou l'enrichir sans que cela ne constitue un changement majeur, alors le principe retenu est de monter de version (incrément de 1). Autrement dit, le changement de version d'un objet doit pouvoir être propagé à tous les objets parents le référençant et ainsi par récursivité à tous ses ancêtres. Pour en savoir plus, voir le support de formation [DDI Identification and Versioning](https://zenodo.org/record/5180607/files/DDITL_09_1_0_Identification_Versioning.pptx?download=1). ### Concept Lors de la publication d'un concept dans le référentiel GraphDB, - si le concept existe déjà dans Colectica (rechercher l'uri dans le UserID), alors pour le mettre à jour dans Colectica : - créer un nouveau fragment du concept en incrémentant de 1 la version du fragment existant dans Colectica En théorie, cette nouvelle version devrait impliquer une propagation du versionnement à tous ses ancêtres. Proposition : laisser à l'utilisateur le soin de référencer la dernière version (le jour où on référencera des concepts dans Colectica ou Pogues). Colectica a un système d'avertissement quand on récupère l'information du référentiel en local et dont une version plus récente est disponible. - si le concept n'existe pas, alors pour le mettre à jour dans Colectica : - créer un nouveau fragment avec un nouvel identifiant et un numéro de version valant 1 Le fragment est défini comme suit : ```xml= <Fragment xmlns:r="ddi:reusable:3_3" xmlns="ddi:instance:3_3"> <Concept isUniversallyUnique="true" versionDate="2021-11-22T15:15:21.0613813Z" isCharacteristic="false" xmlns="ddi:conceptualcomponent:3_3"> <r:URN>urn:ddi:fr.insee:ee723796-7f67-43eb-9cbf-5c6bd476e7ad:1</r:URN> <r:Agency>fr.insee</r:Agency> <r:ID>ee723796-7f67-43eb-9cbf-5c6bd476e7ad</r:ID> <r:Version>1</r:Version>  <r:UserID typeOfUserID="http://id.insee.fr/" >http://id.insee.fr/concepts/definition/c2238</r:UserID>  <r:Label> <r:Content xml:lang="en-IE" isPlainText="true" textFormat="text/plain" isTranslated="true">Research and development effort</r:Content> <r:Content xml:lang="fr-FR" isPlainText="true" textFormat="text/plain" isTranslated="false">Effort de recherche</r:Content> </r:Label>  <r:Label> <r:Content xml:lang="fr-FR" isPlainText="true" textFormat="text/plain" isTranslated="true">ER</r:Content> <r:TypeOfLabel>Synonym</r:TypeOfLabel> </r:Label> <r:Label> <r:Content xml:lang="en-IE" isPlainText="true" textFormat="text/plain" isTranslated="true">RDE</r:Content> <r:TypeOfLabel>Synonym</r:TypeOfLabel> </r:Label>  <r:Description> <r:Content xml:lang="en-IE" isPlainText="true" isTranslated="true">Research and development effort is the share of gross domestic product at market prices (GDP) devoted to gross domestic expenditure on research and experimental development (GERD). In other words, research and development effort is the GERD/GDP ratio.</r:Content> <r:Content xml:lang="fr-FR" isPlainText="false" isTranslated="false" textFormat="application/xhtml+xml">L’effort de recherche est la part du produit intérieur brut aux prix du marché (PIB) consacrée aux dépenses intérieures de R&D (DIRD). Autrement dit, l’effort de recherche est le ratio DIRD/PIB.</r:Content> </r:Description> </Concept> </Fragment> ``` ## Arborescence Famille, Série, Opération L'arborescence à récupérer est la suivante : - Famille d'opérations statistiques ([Group](https://ddialliance.github.io/ddimodel-web/DDI-L-3.3/item-types/Group/)) - Série d'opérations statistiques ([Group](https://ddialliance.github.io/ddimodel-web/DDI-L-3.3/item-types/Group/) dans un Group) - Opération statistique ([StudyUnit](https://ddialliance.github.io/ddimodel-web/DDI-L-3.3/item-types/StudyUnit/)) Pour chacun des objets les éléments à mettre à jour sont : - Famille (uri, intitulé français, intitulé anglais, relation avec les séries enfants) - Série (uri, intitulé français, intitulé anglais, nom court français, nom court anglais, relation avec les opérations enfants) - Opération (uri, intitulé français, intitulé anglais, nom court français, nom court anglais) Dans Bauhaus, un objet (F/S/O) est publiable si et seulement si son parent a déjà été publié au moins une fois. Une fois que l'objet parent a été publié, chaque objet est publiable indépendamment de l'état du parent et des enfants (ces derniers pouvant être en cours de création). Cela pose quelques difficultés car modifier un objet, c'est le faire monter de version et propager le changement de version à tous ses ancêtres. Pour une illustration, voir le schéma "cu-publier-operation-vie-fso.gif" illustrant le cas d'utilisation "Publier une nouvelle opération statistique". Cela signifie également qu'il risque d'y avoir des conflits pour les utilisateurs de Colectica Designer. En effet, si séquentiellement : 1. un concepteur récupère sa série d'opérations statistiques dans Colectica Designer pour concevoir son dictionnaire de variables 1. ce même concepteur publie des modification sur sa série ou son opération statistique 1. le concepteur publie son nouveau dictionnaire de variables via Colectica Designer Alors, le concepteur essaiera de publier une version des Fragement DDI déjà existant dans Colectica. Il s'agira alors de réaliser quelques manipulations dans Colectica Designer pour bien publier le dictionnaire de variables au sein d'une nouvelle version de sa famille, série et opération statistique. Fort de cette (peut-être trop courte) introduction, la spécification des traitements à réaliser à la publication d'un de ces objets est la suivante : ### Famille Lors de la publication d'une famille, - si la famille existe déjà dans Colectica (rechercher l'uri dans le UserID), alors pour la mettre à jour : - créer un nouveau fragment de la famille (Group) en incrémentant de 1 la version du fragment de la famille existante dans Colectica (donc récupérer l'identifiant Colectica) en conservant les liens avec les séries enfants - si la famille n'existe pas dans Colectica, alors pour la mettre à jour : - créer un nouveau fragment avec un nouvel identifiant et un numéro de version valant 1 sans référencer les séries enfants (elles le seront progressivement à la publication de chacune des séries). :::info **Pourquoi ne pas publier les références vers les séries filles dans le cas d'une création ?** Au moment de la publication d'une famille, une série fille peut ne pas avoir encore été publiée. Il paraît plus sain de référencer la série dans la famille seulement au moment de la publication de la série. **Pourquoi conserver les références vers les séries filles lorsque la famille existe déjà dans Colectica ?** S'il existe une référence vers une série fille dans la famille, c'est que la série a déjà été publiée et puisqu'il n'est pas possible de supprimer une série publiée alors la référence est toujours valable. ::: Le fragment d'une famille est tel celui ci-dessous. ```xml= <ddi:Fragment xmlns:r="ddi:reusable:3_3"> <Group isUniversallyUnique="true" externalReferenceDefaultURI="http://id.insee.fr/operations/famille/s25" versionDate="2021-11-16T10:53:18.634965Z" xmlns="ddi:group:3_3"> <r:URN>urn:ddi:fr.insee:21912dce-f7e8-4c6d-a0bd-152a0bbc7837:3</r:URN> <r:Agency>fr.insee</r:Agency> <r:ID>21912dce-f7e8-4c6d-a0bd-152a0bbc7837</r:ID> <r:Version>3</r:Version>  <r:UserID typeOfUserID="http://id.insee.fr/" >http://id.insee.fr/operations/famille/s25</r:UserID>  <r:VersionResponsibility>DG75-L201</r:VersionResponsibility>  <r:VersionRationale> <r:RationaleDescription> <r:String xml:lang="fr-FR">Mise à jour de la famille</r:String> </r:RationaleDescription>  <r:RationaleCode controlledVocabularyID="INSEE-VERSION-RATIONALE"/> </r:VersionRationale> <r:Citation>  <r:Title> <r:String xml:lang="en-IE">Economic outlook surveys</r:String> <r:String xml:lang="fr-FR">Enquêtes qualitatives de conjoncture</r:String> </r:Title> </r:Citation>  <r:GroupReference> <r:Agency>fr.insee</r:Agency> <r:ID>5651f534-21ff-4b09-818f-411c48ea3e01</r:ID> <r:Version>2</r:Version> <r:TypeOfObject>Group</r:TypeOfObject> </r:GroupReference> <r:GroupReference> <r:Agency>fr.insee</r:Agency> <r:ID>3169daab-040f-4470-a566-ac11fb36428a</r:ID> <r:Version>3</r:Version> <r:TypeOfObject>Group</r:TypeOfObject> </r:GroupReference> <r:GroupReference> <r:Agency>fr.insee</r:Agency> <r:ID>29d87660-85bb-447e-a367-d532aa430ae7</r:ID> <r:Version>3</r:Version> <r:TypeOfObject>Group</r:TypeOfObject> </r:GroupReference> </Group> </ddi:Fragment> ``` ### Série Lors de la publication d'une série, - si la série existe déjà dans Colectica (rechercher l'uri dans le UserID), alors pour la mettre à jour dans Colectica : - créer un nouveau fragment de la série (Group) en incrémentant de 1 la version du fragment de la série existante dans Colectica en conservant les liens avec les opérations enfants - si la série n'existe pas dans Colectica, alors pour la mettre à jour dans Colectica : - créer un nouveau fragment avec un nouvel identifiant et un numéro de version valant 1 sans référencer les opérations enfants (elles le seront progressivement à la publication de chacune des opérations). Puis dans les deux cas : - créer un nouveau fragment de la famille parente (pour la retrouver, prédicat "isPartOf" et rechercher dans le userID) en incrémentant de 1 la version du fragment de la famille existante dans Colectica et référencer le fragment de la série fraîchement créée (voir ci-dessus) ```xml= <ddi:Fragment xmlns:r="ddi:reusable:3_3"> <Group isUniversallyUnique="true" versionDate="2020-01-27T14:00:33.1340889Z" xmlns="ddi:group:3_3" externalReferenceDefaultURI="http://id.insee.fr/operations/serie/s1204"> <r:URN>urn:ddi:fr.insee:5651f534-21ff-4b09-818f-411c48ea3e01:2</r:URN> <r:Agency>fr.insee</r:Agency> <r:ID>5651f534-21ff-4b09-818f-411c48ea3e01</r:ID> <r:Version>2</r:Version>  <r:UserID typeOfUserID="http://id.insee.fr/" >http://id.insee.fr/operations/serie/s1204</r:UserID>  <r:VersionResponsibility>DG75-G120</r:VersionResponsibility>  <r:VersionRationale> <r:RationaleDescription> <r:String xml:lang="fr-FR">Mise à jour de la série</r:String> </r:RationaleDescription> </r:VersionRationale> <r:Citation>  <r:Title> <r:String xml:lang="en-IE">Bi-monthly business outlook survey on wholesaling</r:String> <r:String xml:lang="fr-FR">Enquête bimestrielle de conjoncture dans le commerce de gros</r:String> </r:Title>  <r:AlternateTitle> <r:String xml:lang="en-IE">Outlook on wholesaling</r:String> <r:String xml:lang="fr-FR">Conjoncture dans le commerce de gros</r:String> </r:AlternateTitle> </r:Citation>  <r:StudyUnitReference> <r:Agency>fr.insee</r:Agency> <r:ID>d1bc4932-6626-4967-8c3e-7f458442233a</r:ID> <r:Version>2</r:Version> <r:TypeOfObject>StudyUnit</r:TypeOfObject> </r:StudyUnitReference> </Group> </ddi:Fragment> ``` ### Opérations Lors de la publication d'une opération, - si l'opération existe déjà dans Colectica (rechercher l'uri dans le UserID), alors pour la mettre à jour : - créer un nouveau fragment de l'opération (StudyUnit) en incrémentant de 1 la version du fragment de l'opération existante dans Colectica et en conservant les références vers les DataCollection. - si l'opération n'existe pas, alors : - créer un nouveau fragment avec un nouvel identifiant et un numéro de version valant 1 sans référencer les campagnes de collecte enfants (elles le seront progressivement à la publication de chacune des camapagnes) Puis dans les deux cas : - créer un nouveau fragment de la série parente (pour la retrouver, prédicat "isPartOf") en incrémentant de 1 la version du fragment de la série existante dans Colectica et référencer la nouvelle version de l'opération à la place de l'ancienne version - créer un nouveau fragment de la famille parente de la série (Group) en incrémentant de 1 la version du fragment de la famille existante dans Colectica et référencer la nouvelle version de la série à la place de l'ancienne version ```xml= <ddi:Fragment xmlns:r="ddi:reusable:3_3"> <StudyUnit isUniversallyUnique="true" versionDate="2020-01-27T14:00:33.1340889Z" externalReferenceDefaultURI="http://id.insee.fr/operations/operation/s1500" xmlns="ddi:studyunit:3_3"> <r:URN>urn:ddi:fr.insee:d1bc4932-6626-4967-8c3e-7f458442233a:2</r:URN> <r:Agency>fr.insee</r:Agency> <r:ID>d1bc4932-6626-4967-8c3e-7f458442233a</r:ID> <r:Version>2</r:Version>  <r:UserID typeOfUserID="http://id.insee.fr/" >http://id.insee.fr/operations/operation/s1500</r:UserID>  <r:VersionResponsibility>DG75-G120</r:VersionResponsibility>  <r:VersionRationale> <r:RationaleDescription> <r:String xml:lang="fr-FR">Mise à jour de l'opération</r:String> </r:RationaleDescription> </r:VersionRationale> <r:Citation>  <r:Title> <r:String xml:lang="en-IE">Bi-monthly business outlook survey on wholesaling 2020</r:String> <r:String xml:lang="fr-FR">Enquête bimestrielle de conjoncture dans le commerce de gros 2020</r:String> </r:Title>  <r:AlternateTitle> <r:String xml:lang="en-IE">Outlook on wholesaling 2020</r:String> <r:String xml:lang="fr-FR">Conjoncture dans le commerce de gros 2020</r:String> </r:AlternateTitle> </r:Citation>  <r:DataCollectionReference> <r:Agency>fr.insee</r:Agency> <r:ID>60df5474-b63a-4c93-b3c6-f6e40022fffa</r:ID> <r:Version>2</r:Version> <r:TypeOfObject>DataCollection</r:TypeOfObject> </r:DataCollectionReference> <r:DataCollectionReference> <r:Agency>fr.insee</r:Agency> <r:ID>72a99b26-4140-4f20-8e2b-c67886861f82</r:ID> <r:Version>2</r:Version> <r:TypeOfObject>DataCollection</r:TypeOfObject> </r:DataCollectionReference> </StudyUnit> </ddi:Fragment> ``` :::info Cette spécification est-elle raisonnable ou trop alambiquée ? Une alternative un peu plus simple serait de déclencher la mise à jour dans Colectica uniquement lors de la publication d'une opération. La spécification serait alors celle décrite au niveau de l'opération en ajoutant la mise à jour des descriptions des séries et familles en créant à chaque fois des fragments avec le numéro de version incrémenté. ::: :::warning => Quand on publie une famille seule ou une série seule, on perd les triplets avec les prédicats hasPart. Cela se passe bien dans l'API, pas de pb pour Web4G mais vraisemblablement un bug. :::