Documentation du fichier de paramètres au format XML

Sommaire

1. Introduction
1. Exemple d’un fichier de paramètres
1. Description du fichier de paramètres
1. Exemples

Introduction

Un fichier de type XML donne le squelette du classeur de données. Il contient les critères à respecter pour la vérification pendant la validation et pour l’insertion des données dans la base des données.

Parmi les critères on trouve :

Le nom du schéma dans lequel les données seront insérées. (Attention ! Le nom du schéma respecte la casse !)
Le numéro de la première ligne de données pour toutes les feuilles du classeur.
Les noms des feuilles dans le classeur et les noms des tables correspondants dans la base de données.
Les noms des colonnes dans chaque feuille du classeur et leurs correspondances dans les attributs des tables de la base de données.
Pour chaque colonne on peut préciser :
- Si la valeur est unique
- Si la valeur est obligatoire
- Un type de données («integer», «numeric», «date», «text», «enum»)
- Un format (pour les dates)
- Une référence à une autre colonne d’une feuille du classeur ou une valeur par défaut.
- Un intervalle (pour les valeurs numériques et les dates)

Remarque :

Le classeur doit contenir une feuille au minimum.
La cohérence de la valeur d'une colonne d'une feuille peut être vérifiée avec au plus deux feuilles de référence.
Toutes les feuilles du classeur doivent être déclarées dans le fichier XML.
Les feuilles ne doivent pas contenir de colonnes vides.
La structure générale peut être générée avec sido-cli.jar. Voir java -jar sido-cli.jar createxml --help.

Exemple d’un fichier de paramètres

	<!DOCTYPE workbook>
	<workbook schemaNameBD="foret" startLine="4">
		<worksheet name="Données" tableNameBD="donnee" ignored="false">
			<fieldname name="Code du référentiel"
						columnNameBD="ref_taxonomique_code_ref">
				<unique>yes</unique>
				<missingValuesAccepted>no</missingValuesAccepted>
				<fieldType>text</fieldType>
			</fieldname>
	      	<fieldname name="Nom du référentiel" 
	      				columnNameBD="ref_taxonomique_nom_ref">
	         	<unique>no</unique>
	         	<missingValuesAccepted>no</missingValuesAccepted>
	         	<fieldType>text</fieldType>
	      	</fieldname>		
			<fieldname name="Date" columnNameBD="donnee_date">
				<unique>no</unique>
				<missingValuesAccepted>y/n</missingValuesAccepted>
				<fieldType>date</fieldType>
				<fieldFormat>yyyy-MM-dd</fieldFormat> 
				<rang min="2000-02-01" max="2005-02-01"></rang>
			</fieldname>		
			<fieldname name="Année" columnNameBD="donnee_annee">
				<unique>no</unique>
				<missingValuesAccepted>y/n</missingValuesAccepted>
				<fieldType>integer</fieldType>
			</fieldname>
	      	<fieldname name="Version" 
	      			columnNameBD="ref_taxonomique_version">
	         	<unique>no</unique>
				<missingValuesAccepted>no</missingValuesAccepted>
	       		<fieldType>text</fieldType>
	      	</fieldname>	
			<fieldname name="Sigle de la licence d'utilisation" 
					columnNameBD="licence_sigle">
				<unique>yes</unique>
				<missingValuesAccepted>no</missingValuesAccepted>
				<fieldType>enum</fieldType>
				<fieldValues>
					<value>LO2.0</value>
					<value>OdbL</value>
				</fieldValues>
			</fieldname>
		</worksheet>  
	</workbook>

Description du fichier de paramètres

(*) signifie que le mot-clef est obligatoire pour la validation du fichier XML des paramètres.

Mots clefs pour le classeur :

workbook(*) -> Classeur
worksheet(*) -> Feuille du classeur
fieldname(*) -> Colonne dans une feuille du classeur
startLine(*) -> Numéro de la première ligne de données (pour toutes les feuilles)
ignored(*) -> Boolean (true, false), feuille à ignorer pendant le traitement du classeur

Mots clefs pour la base de données :

schemaNameBD(*) -> Nom du schéma dans la base de données
tableNameBD(*) -> Nom de la table dans la base de données
columnNameBD(*) -> Nom de l'attribut dans la base de données, par convention = tableNameBD_columnName

Mots clefs pour les valeurs :

fieldType -> Type de la valeur {«integer», «numeric», «date», «text», «enum»}
fieldFormat -> Format de la date (ex. : dd/MM/yyyy). Le programme utilise l’API DateTimeFormatter de Java pour le format de la date.
fieldValues -> Pour le type «enum» cette balise contient la liste des valeurs autorisée.
unique -> Unicité de la valeur {«yes», «no»}. Une valeur unique est fortement conseillée pour les colonnes étant référencées par refSheet.
rang -> Vérifier que la valeur appartient à un intervalle[min – max].
missingValuesAccepted -> Présence de valeur manquante {«yes», «no», «y/n»}. La valeur «y/n» signifie qu’une et une seule des deux colonnes doit être renseignée pour chaque ligne de la feuille. «y/n» peut être utilisé entre deux colonnes seulement et une seule fois dans une feuille.
refSheet -> Référence(s) à une autre colonne d’une feuille du classeur.
- value1 -> Feuille et colonne de référence numéro 1 ou valeur par défaut
- value2 -> Feuille et colonne de référence numéro 2
Fonctionnement :
- Si le format de «value1» ressemble à «Feuille:Colonne»
  - alors la valeur indiquée doit correspondre à une des valeurs de la colonne de la feuille de référence.
  - sinon la valeur indiquée doit correspondre à la valeur par défaut énoncée dans «value1» .
- Si le format de «value2» ressemble à «Feuille:Colonne»
  - alors la valeur indiquée doit correspondre à une des valeurs de la colonne de la feuille de référence.

Seule "value1" peut désigner une valeur par défaut. "value2" si présent fait toujours référence à une colonne.

Exemples

ignored:

Feuille à ignorer pendant le traitement du classeur :

<worksheet name="INFOS" ignored="true"/>

Feuille à ne pas ignorer pendant le traitement du classeur :

<worksheet name="INFOS" ignored="false"/>

fieldValues:

	<fieldname name="Sigle de la licence d'utilisation" 
			columnNameBD="licence_sigle">
		<unique>yes</unique>
		<missingValuesAccepted>no</missingValuesAccepted>
		<fieldType>enum</fieldType>
		<fieldValues>
			<value>LO2.0</value>
			<value>OdbL</value>
		</fieldValues>
	</fieldname>

Dans cet exemple le type est enum donc une liste des valeurs définie dans le fieldValues dans ce cas (LO2.0, OdbL).

unique

		<fieldname name="Sigle de la licence d'utilisation"
			columnNameBD="licence_sigle_licence_utilisation">

			<unique>yes</unique>

			<missingValuesAccepted>no</missingValuesAccepted>

			<fieldType>text</fieldType>

		</fieldname>

Le champ sigle_licence de la page de données sera quasi toujours jointe avec celui de la feuille de licences. C'est un bon exemple de bonne utilisation de la contrainte d'unicité : cela évite les exports en doublon vers le webservice.

range:

Intervalle des données :

Type numérique :

<range min="47.8" max="48.1"/>

Type date (format à respecter «yyyy-MM-dd») :

<range min="2000-02-01" max="2005-02-01"/>

missingValuesAccepted:

	<fieldname name="Date" columnNameBD="donnee_date">
		<unique>no</unique>
		<missingValuesAccepted>y/n</missingValuesAccepted>
		<fieldType>date</fieldType>
		<fieldFormat>yyyy-MM-dd</fieldFormat>
	</fieldname>
	<fieldname name="Année" columnNameBD="donnee_annee">
		<unique>no</unique>
		<missingValuesAccepted>y/n</missingValuesAccepted>
		<fieldType>integer</fieldType>
	</fieldname>

Dans cet exemple le programme détecte que les deux colonnes « Date » et « Année » comportent des valeurs « y/n » dans le critère « missingValuesAccepted ». Il vérifie que pour chaque ligne de la feuille il n'y a qu’une valeur renseignée pour les deux colonnes.

refSheet :

Exemple de « value1 » avec le séparateur « : ».

	<fieldname name="Nom de l'échelle phénologique"
		 columnNameBD="donnee_nom_echelle_phenologique">
		<unique>no</unique>
		<missingValuesAccepted>no</missingValuesAccepted>
		<fieldType>text</fieldType>
		<refSheet>
			<value1>Stades BBCH:Nom du référentiel</value1>
			<value2>Autres stades:Nom de l'échelle de référence</value2>
		</refSheet>
	</fieldname>

Dans cet exemple le programme va vérifier que la valeur indiquée dans la colonne «Nom échelle phénologique» est présente dans la colonne «Nom du référentiel» de la feuille «stades BBCH» ou dans la colonne «Nom de l'échelle de référence» de la feuille «Autres stades»

Exemple de « value1 » sans le séparateur « : »

«value1» sans le séparateur « : » signifier que cette valeur est par défaut.

	<fieldname name="Nom de l'échelle phénologique"
		 columnNameBD="donnee_nom_echelle_phenologique">
		<unique>no</unique>
		<missingValuesAccepted>no</missingValuesAccepted>
		<fieldType>text</fieldType>
		<refSheet>
			<value1>BBCH</value1>
			<value2>Autres stades:Nom de l'échelle de référence</value2>
		</refSheet>
	</fieldname>

Dans cet exemple le programme va vérifier que la valeur indiquée dans la colonne «Nom échelle phénologique» a pour valeur «BBCH» ou que sa valeur est présente dans la colonne «Nom de l'échelle de référence» de la feuille «Autres stades»