Introduction au mapping de données¶
Ce chapitre est une traduction adaptée de la documentation officielle de CollectiveAccess. Pour consulter la documentation originale, veuillez cliquer ici.
L'objectif d'un mapping d'import est de définir précisément comment et où les données sources seront importées dans CollectiveAccess. Les données doivent être importées dans CollectiveAccess à l'aide d'une correspondance d'import.
Un mapping d'import est une feuille de calcul (XLSX ou GoogleSheets) qui définit la manière dont les données sont importées dans CollectiveAccess. Cette feuille de calcul fait office de tableau de concordance, indiquant où les données proviennent de l'extérieur de CollectiveAccess et où ces mêmes données iront dans CollectiveAccess. Pour un tutoriel utilisant l'exemple de feuille de calcul pour l'import et l'exemple de données d'import, veuillez consulter Tutoriel : Feuille de calcul d'import.
Chaque feuille de calcul de mapping des imports contient un ensemble de colonnes intrinsèques. Une description complète et la fonction de ces colonnes sont décrites ci-dessous. Chaque mapping des imports contient également des paramètres spécifiques et personnalisés. Des tableaux seront utilisés pour énumérer plus en détail les options possibles et les fonctions de chaque aspect de la feuille de calcul.
Pour accompagner votre découverte, un tutoriel est disponible. Afin de vous faciliter la découverte, des exemples (mapping, données source, exemple de profil d'installation) vous permettront de vous entraîner sur votre installation locale de CollectiveAccess.
Exemple de feuille de calcul pour la mise en correspondance des imports
Exemple de données d'import (données source)
Exemple de profil d'installation
Feuille de calcul vierge pour la mapping des imports
Vous trouverez ci-dessous une explication colonne par colonne de chaque élément de la feuille de calcul de la mapping des imports.
Parties d'une mapping des imports : Paramètres, colonnes et autres¶
Paramètres¶
Chaque mapping d'import nécessite des paramètres généraux. Ces paramètres comprennent le nom de l'importateur, le format des données source (pour une liste complète des formats de fichiers pris en charge, la table CollectiveAccess sélectionnée, etc. Cette section peut être placée en haut ou en bas d'une feuille de calcul.
Bien que les paramètres soient intégrés dans la feuille de calcul, ils fonctionnent séparément du corps principal défini par les colonnes de la mapping des imports.
Note
Dans Paramètres, les types de règles de la colonne 1 doivent être définis sur "Paramètres".
| Paramètres | Description | Notes sur les paramètres | Exemple |
|---|---|---|---|
| nom | Donnez un nom à votre mapping. | Texte arbitraire | Ma mapping des échantillons |
| code | Donnez à votre mapping un code alphanumérique du mapping | Texte arbitraire, sans caractères spéciaux ni espaces | ma_mapping_de_l'échantillon |
| formats d'entrée | Définit le type de données source (d'entrée) qui peuvent être traitées par ce mapping d'import. Les valeurs sont des codes de format définis par les différents plugins DataReader. | type de fichier | XLSX |
| table | Définit la table pour les données importées. Si vous importez des objets, définissez la table sur ca_objects. Si vous importez des collections, définissez la table sur ca_collections, et ainsi de suite. | Correspond aux tableaux de base de CollectiveAccess | ca_objets |
| type | Définissez le type d'enregistrement auquel tous les enregistrements importés doivent correspondre. Si vous importez des objets, de quel type sont-ils ? Photographies, artefacts, peintures, etc. Cette valeur doit correspondre à une valeur existante dans la liste des types. Pour les objets, la liste estobject_types. Si l'import inclut une correspondance avec l'identifiant de type, celle-ci sera privilégiée et le paramètre de type sera ignoré. | Code de l'élément de la liste CollectiveAccess | image |
| numInitialRowsToSkip | Nombre de lignes en haut de l'ensemble de données à ignorer. Ce paramètre permet d'ignorer les en-têtes de colonnes dans les feuilles de calcul et autres données similaires. | valeur numérique | 1 |
| politique d'enregistrement existante | Détermine comment les enregistrements existants dans le système CollectiveAccess sont vérifiés et traités pour le mappage. Détermine également la manière dont les enregistrements créés par le mapping sont fusionnés avec d'autres instances (numéro d'identification et/ou étiquette préférée) dans la source de données. (Dans CollectiveAccess, le champ d'identification primaire est "idno" et le champ titre/nom de chaque enregistrement est "preferred_label"). Depuis la version 1.8, les options permettant d'ignorer, de fusionner ou d'écraser les enregistrements internes de CollectiveAccess sont également prises en charge via les options *_on_id. Ces options peuvent être utiles lors de la réimport de données précédemment exportées à partir d'une instance de CollectiveAccess. aucun skip_on_idno merge_on_idno overwrite_on_idno sauter_sur_les_étiquettes_préférées merge_on_preferred_labels overwrite_on_preferred_labels skip_on_idno_and_preferred_labels merge_on_idno_and_preferred_labels overwrite_on_idno_and_preferred_labels merge_on_idno_with_replace merge_on_preferred_labels_with_replace merge_on_idno_and_preferred_labels_with_replace skip_on_id merge_on_id merge_on_id_with_replace overwrite_on_id | aucun | |
| ignoreTypeForExistingRecordPolicy | Si cette option est activée, le type d'enregistrement sera ignoré lors de la recherche d'enregistrements existants, conformément à la politique relative aux enregistrements existants. | 0 ou 1 | 0 |
| omitPreferredLabelFieldsForExistingRecordPolicy (champs d'étiquetage préférentiels pour la politique d'enregistrement existante) | Liste délimitée par des virgules ou des points-virgules de champs d'étiquettes préférentielles à omettre lors de la recherche d'enregistrements existants utilisant des étiquettes préférentielles. Généralement utilisé avec les étiquettes d'entités pour supprimer des sous-champs spécifiques tels que le nom d'affichage. | Généralement utilisé pour les étiquettes d'entités afin de restreindre les champs utilisés pour la mise en correspondance. | nom d'affichage ; nom de milieu |
| mergeOnly | Si cette option est activée, les données ne seront fusionnées qu'avec les enregistrements existants en utilisant la politique relative aux enregistrements existants et aucun nouvel enregistrement ne sera créé. Disponible à partir de la version 1.8. | 0 ou 1 | 0 |
| dontDoImport | Si cette option est activée, le mapping sera évalué, mais aucune ligne ne sera importée. Cela peut s'avérer utile lorsque vous souhaitez exécuter un raffinage sur les lignes d'un ensemble de données, mais que vous n'effectuez pas l'import primaire. | 0 ou 1 | 0 |
| basePath | Pour les formats de données XML, une expression XPath sélectionnant les nœuds à traiter comme des enregistrements individuels. Si elle est laissée vide, chaque document XML sera traité comme un seul enregistrement. | Doit être une expression Xpath valide | /export |
| lieu | Définit les paramètres linguistiques utilisés pour toutes les données importées. Laisser vide ou omettre pour utiliser la locale par défaut du système. Dans le cas contraire, attribuez-lui un code de locale valide (ex. en_US, es_MX, fr_CA). | Doit être un code régional ISO valide. | fr_US |
| politique d'erreur | Détermine la manière dont les erreurs sont gérées lors de l'import. Les options sont les suivantes : ignorer l'erreur, arrêter l'import en cas d'erreur et recevoir une invite en cas d'erreur. La valeur par défaut est "ignorer". | ignorer arrêter | ignorer |
Colonnes¶
Colonne 1 : Types de règles¶
Pour chaque ligne de la feuille de calcul de la correspondance d'import, un type de règle doit être défini. Ces règles déterminent la manière dont l'importateur traitera l'enregistrement ou la ligne. En d'autres termes, les règles définissent la manière dont chaque ligne sera importée. Cinq règles sont disponibles :
| Type de règle | Description |
|---|---|
| mapping | Associe une source de données (telle qu'une colonne dans une feuille de calcul Excel ou une balise spécifique dans XML) à un élément de métadonnées CollectiveAccess. Définissez cette règle pour vous assurer que la ligne sera importée. |
| Sauter | Utilisez Ignorer pour ne pas tenir compte d'une source de données ; elle ne sera pas incluse dans l'import lorsque cette règle est définie. |
| Constant | Définit une valeur constante arbitraire. Ajoutez la valeur à la colonne source et la valeur sera définie dans l'élément de métadonnées correspondant pour chaque enregistrement importé. Cette valeur est utilisée lors de la mise en correspondance avec des conteneurs. |
| Paramètres | Définit les préférences générales pour la mapping elle-même. Il s'agit simplement de définir divers paramètres en tant que paramètres. |
Colonne 2 : Source¶
Comme nous l'avons mentionné plus haut, l'objectif d'une feuille de calcul de correspondance d'import est de définir précisément comment et où les données sources seront importées dans CollectiveAccess. La colonne Source définit *où* les données proviennent de l'extérieur de CollectiveAccess ; c'est la première partie du tableau de concordance.
L'emplacement des valeurs dans la colonne Source dépend du format de fichier des données sources importées. CollectiveAccess prend en charge un grand nombre de formats de fichiers, et chaque format a une valeur unique et correspondante dans la colonne Source.
Quelques-uns d'entre eux sont décrits ci-dessous :
| Format du fichier | Format de la source |
|---|---|
| Excel (XLSX), autres feuilles de calcul | Les lettres des colonnes doivent être converties en chiffres. Une fois cette opération effectuée, les valeurs de Source seront saisies sous forme de nombres : 1, 2, 3, etc. |
| XML | Les valeurs sources seront saisies sous la forme du nom textuel de la balise XML, précédé d'une barre oblique, /. |
| XPath | |
| MARC | |
| FMPXML/RESULTAT |
Une description complète des formats d'import pris en charge et de la manière dont ils peuvent être référencés dans une correspondance d'import est disponible sur la page Formats de fichiers pris en charge.
Note
Dans l'exemple que nous utilisons pour ce tutoriel, les données de l'échantillon sont dans Excel. Toutefois, il se peut que vous ayez besoin d'importer des données au format XML. Les sources XML sont citées dans xPath, qui est la syntaxe standard pour récupérer des données encodées en XML. La documentation concernant xPath se trouve ici.
Les colonnes de données sources peuvent également être référencées ailleurs dans la mapping des imports (généralement dans les colonnes Options ou Refinery décrites ci-dessous) en faisant précéder le numéro de la colonne d'un "\^" (par exemple "\^10"), ce qui indique à la mapping que la valeur de la colonne 10 doit être insérée.
Elle permet de combiner plusieurs colonnes à l'aide des paramètres d'options et est fréquemment utilisée dans Les Refinery pour créer des entités liées détaillées, des collections, etc.
Colonne 3 : CA table.element¶
En tant que tableau de concordance, la feuille de calcul des imports détermine l'origine des données en dehors de CollectiveAccess (données sources), mais aussi l'emplacement de ces données dans CollectiveAccess. De la même manière que la colonne 2 définit les données sources, la colonne 3 détermine l'emplacement de ces données dans CollectiveAccess, à l'aide de divers codes ca_table.element_codes.
Cette colonne indique le code de l'ensemble ou l'élément de métadonnées de CollectiveAccess auquel les données sources seront associées. Il est possible d'afficher les éléments de métadonnées disponibles et leur formatage directement dans CollectiveAccess. Pour ce faire, accédez à Manage > My Preferences > Developer > Show Bundle Codes, puis sélectionnez Show. Retournez sur la page d'un enregistrement et ces codes s'afficheront pour chaque champ ; ils pourront alors être directement insérés dans la colonne 3. Pour copier un code de regroupement, il suffit de le sélectionner et de le coller dans la feuille de calcul des correspondances d'import.
Lorsque vous importez du texte libre, des plages de dates, des nombres, des devises ou d'autres types de données, un code ca_table.element suffit.
Note
Lors de la création d'enregistrements de lots dans un mapping d'import, le code de l'élément ca_table doit correspondre à l'identifiant du lot ca_objects.lot_id.
Cependant, dans certains cas, des étapes supplémentaires sont nécessaires. Pour plus d'informations, voir Conteneurs et Utilisation des codes de regroupement dans un mapping d'import.
Colonne 4 : Groupe¶
Dans de nombreux cas, les données seront mappées dans des éléments de métadonnées correspondants regroupés dans un conteneur. Déclarer un groupe dans la colonne 4 d'un mapping d'import est un moyen simple de s'assurer que tous vos mappages vers un conteneur aboutissent au même endroit. Les noms de groupe sont arbitraires ; CollectiveAccess reconnaîtra un groupe de n'importe quel nom pour n'importe quel nombre d'éléments de métadonnées, tant que le nom est cohérent.
Pour créer un groupe, attribuez le nom arbitraire du groupe à une ligne de la colonne Groupe. Cela permettra au mapping de placer les lignes de données dans un seul conteneur. Pour s'assurer que la date elle-même et le type de date se retrouvent dans la même instance du conteneur Date, il suffit de les affecter au même groupe dans la quatrième colonne de mappage.
Le nom que vous attribuez au groupe est arbitraire, mais il doit être reconnaissable pour vous.
Colonne 5 : Options¶
Les options peuvent être utilisées dans un mapping d'import pour définir une variété de choix de formatage et fixer des conditions sur l'import elle-même. Les options peuvent également aider à traiter les données qui ont besoin d'être nettoyées ou à formater les données à l'aide d'une variété de modèles. Certaines options sont conçues pour paramétrer le comportement du mapping d'import, par exemple en empêchant l'import de certains champs.
Les options sont écrites dans le code. Ce code contient des termes spécifiques pour les options qui permettent de manipuler le comportement des données sources. Les options courantes pour les correspondances d'import sont énumérées et décrites ci-dessous :
| Type d'option | Description | Notes sur les paramètres | Exemple pour la colonne "Options" de la mapping |
|---|---|---|---|
| skipIfEmpty | Si la valeur des données correspondant à cette correspondance est vide, la ligne de correspondance est ignorée. | fixé à une valeur non nulle | {"skipIfEmpty" : 1} |
| délimiteur | Délimiteur pour séparer les valeurs répétitives. | valeur du délimiteur | {"delimiter" : " ;"} |
La définition de l'option de délimitation dans le mapping permet de s'assurer que les valeurs des données de la source sont analysées et importées en tant qu'instances distinctes des champs concernés. Sans l'option de délimitation, la chaîne entière se retrouverait dans une instance unique du champ Subject. Pour une liste complète des options, voir Options de mappage.
Colonne 6 : Refinery¶
Un Refinery est un traitement conçu pour prendre un format de données spécifique et le transformer lors de l'import. Les Refinery permettent une plus grande complexité dans la représentation des données, on les utilise principalement pour créer des enregistrements liés à partir de la feuille de calcul d'import. Pour en savoir plus sur les Refinery, leurs définitions, leurs types et leur utilisation, consultez la page sur [Les Refinery.]
Si une import de données nécessite des enregistrements liés, des Refinery doivent être utilisées.
Bien que les paramètres de raffinage puissent être très complexes, dans sa forme la plus simple, un raffinage crée simplement un enregistrement, ou des correspondances sur un enregistrement existant, et crée une relation entre cet enregistrement et l'enregistrement que vous importez directement à partir des données sources.
L'objectLotSplitter nécessite quelques paramètres supplémentaires, tous cités dans notre exemple de mapping.
Enfin, les splitters ne sont pas le seul type de Refinery, mais le plus courant. Une liste complète des Refinery et des splitters est disponible ici.
Colonne 7 : Paramètres du Refinery¶
Les paramètres de Refinery définissent les conditions d'utilisation du Refinery dans la mapping d'import. Lorsqu'un Refinery déclare quelles données sont manipulées, le paramètre de Refinery indique comment les données seront modifiées.
Les paramètres de raffinage sont écrits en code et nécessitent un code valide pour fonctionner correctement dans la mapping d'import. Les paramètres de raffinage les plus courants sont énumérés ci-dessous :
| Paramètre du type de Refinery | Notes sur les paramètres | Exemple pour la colonne "Paramètres du Refinery" de la mapping |
|---|---|---|
| type de relation | Accepte un code de type constant pour le type de relation ou une référence à l'emplacement dans la source de données où le type peut être trouvé. | {"relationshipType" : "\^10"} ou {"relationshipType" : "author"} |
| type d'entité | Accepte un élément de liste constant idno de la liste entity_types ou une référence à l'emplacement dans la source de données où le type peut être trouvé. | {"entityType" : "individual"} |
| attributs | Définit ou met en correspondance les métadonnées pour l'enregistrement de l'entité en faisant référence au code metadataElement et à l'emplacement dans la source de données où les valeurs des données peuvent être trouvées. | { "attributs" : { "biographie" : "\^23", "adresse" : { "address1" : "\^24", "address2" : "\^25", "ville" : "\^26", "stateprovince" : "\^27", "code postal" : "\^28", "pays" : "\^29" } } } |
Colonnes 8 et 9 : Valeurs d'origine/Valeurs de remplacement¶
Un mapping d'import peut trouver des valeurs dans les données sources et les remplacer par de nouvelles valeurs lors de l'import. Cette étape est nécessaire pour les données qui ne correspondent pas au code des éléments de la liste pour les valeurs correspondantes dans CollectiveAccess. Les valeurs des données sources seront saisies dans la colonne 8, tandis que les valeurs qui les remplacent seront saisies dans la colonne 9. Plusieurs valeurs peuvent être ajoutées à une seule cellule dans un mapping d'import, à condition que la valeur de remplacement corresponde à la valeur d'origine ligne par ligne.
Dans notre exemple de données, il y a un élément de liste appelé "Reproduction" avec des valeurs pour la reproduction, l'original et l'inconnu. Dans nos données sources, cependant, vous remarquerez que les entrées de données pour ces valeurs sont abrégées (par exemple "orig", "repro" et "dontknow"). En utilisant les valeurs d'origine et de remplacement, notre mapping transforme "orig" en "original" et "repro" en "reproduction" afin qu'ils puissent correspondre au code de l'article de la liste pour les valeurs correspondantes dans CollectiveAccess.
Note
Les valeurs originales et les valeurs de remplacement sont idéales pour les petits remplacements. Pour les grands dictionnaires de transformation, utilisez l'option transformValuesUsingWorksheet.
Pour savoir quand et comment utiliser ces colonnes, voir Utilisation des valeurs d'origine et de remplacement dans un mapping d'import.
Colonnes 10 et 11 : description de la source et notes¶
La description de la source et les notes sont les deux dernières colonnes incluses dans une feuille de calcul de mapping des imports et sont facultatives. Utilisées pour clarifier les données sources et l'objectif de chaque ligne de la mapping des imports elle-même, ces colonnes peuvent être utiles pour garder une trace de l'origine exacte des données de la mapping des imports. La colonne Notes offre un espace pour expliquer comment et pourquoi une certaine ligne est mappée de la manière dont elle l'est. Ces deux colonnes permettent de s'y référer facilement et sont particulièrement utiles lorsque plusieurs utilisateurs créent un mapping d'import.
Ces colonnes peuvent être utiles pour des références ultérieures, si une correspondance est destinée à être utilisée à plusieurs reprises. Ces colonnes permettent également de s'assurer que la mise en correspondance correspond aux données sources.