Comment définir des champs calculés

Informations pour les Administrateurs Système

Deux entrées de registre sont disponibles pour l’utilisation des Définitions de champ dans le module Normes :

• Entrée de Registre Preview Record : utilisée pour spécifier un enregistrement servant à prévisualiser le résultat des enregistrements Définition de champ du module Normes.
• Entrée de Registre Calculated : utilisé pour définir quels champs d’un module ont des valeurs calculées.

Le code de script utilisé pour calculer la valeur d’un champ est stocké dans un enregistrement Définition de champ du module Normes et activé via l’Entrée de Registre Calculated. Lorsqu’un enregistrement est enregistré, soit par insertion, soit par modification, chaque champ défini dans l’Entrée de Registre Calculated du module est vérifié afin de déterminer s’il existe un enregistrement Définition de champ. Si un tel enregistrement existe, tout code de script stocké dans l’enregistrement est exécuté et la valeur résultante est attribuée au champ.

Conseil : Les enregistrements Définition de champ du module Normes pour les Données sommaires et les Données étendues ont été fournis avec EMu 10 pour les modules EMu de base (à l’exclusion du Catalogue). Ceux-ci peuvent être modifiés pour répondre aux besoins spécifiques de chaque institution.

Le module Normes Définition de champ Type d’enregistrement1 Disponible à partir d'EMu 10. est utilisé pour calculer et attribuer une valeur à n’importe quel champ dans n’importe quel module :

Un enregistrement Définition de champ contient du code qui est exécuté chaque fois qu’un enregistrement est créé ou modifié, dont le résultat est une valeur attribuée à un champ immédiatement avant l’enregistrement de l’enregistrement. Cela permet de définir vos propres valeurs Données sommaires, Données étendues ou tout autre calcul de champ sans qu’Axiell ait à modifier les formulaires de la base de données.

L’Entrée de Registre Calculated est utilisée pour contrôler quels champs ont des valeurs calculées. La prise en charge est assurée pour les champs à valeur unique et multiple. Seuls les champs répertoriés dans une Entrée de Registre Calculated auront des valeurs calculées, et tous les autres champs continueront à utiliser le générateur de valeurs par défaut d’EMu.

Pour définir un champ calculé :

1. Créez un nouvel enregistrement dans le module Normes et sélectionnez Définition de champ dans la liste déroulante Type d’enregistrement :

   

2. Dans l’onglet Champ, nous nommons la Définition de champ et définissons le module et le champ dont la valeur doit être calculée. Dans Champs de Script nous sélectionnons un ou plusieurs champs dont les valeurs seront disponibles pour le code du script lors du calcul de la valeur du champ :

   Nom du champ

   Champ	Détails
   Nom	Nom descriptif donné à cette Définition de champ. Le nom inclut généralement le module et l’intitulé de la valeur du champ en cours de calcul (par exemple Données sommaires du Thésaurus). Le nom n’a pas besoin d’être unique.
   Module	Le nom du module EMu contenant la valeur du champ à calculer. Une liste déroulante des modules disponibles est fournie. La liste ne contiendra que les modules auxquels vous êtes autorisé à accéder.
   Champ	Le champ dont la valeur doit être calculée. Une liste des champs disponibles pour le module sélectionné s’affiche lorsque le bouton Liste de consultation est cliqué. Seuls les champs locaux au module sélectionné sont affichés (les champs se référant à d’autres modules ne peuvent pas être calculés). Utilisez le bouton Supprimer pour supprimer le champ.
   Version	La version d’EMu lors de la dernière modification du script de Définition de champ. Lorsqu'un script est installé dans le cadre d'une mise en place ou d'une mise à niveau d'EMu, le numéro de Version d'EMu est saisi ici (10.0 pour une mise en place ou une mise à niveau d'EMu 10, par exemple). Lors de la prochaine mise à jour d’EMu, si une nouvelle version du script est disponible et que le numéro dans Version n’a pas changé, le script sera remplacé (et le numéro Version sera mis à jour). Si vous avez activement modifié le script, il est donc important de changer le numéro Version, sinon votre version du script sera remplacée. Étant donné que les versions d'EMu peuvent comporter une mise à jour décimale (par exemple de 10.0 à 10.1), remplacez ce nombre par une valeur qui ne correspondra pas à une version potentielle d'EMu (10.001, par exemple).
   Statut	Documentez l’état actuel de cette Définition de champ : Actif Nouveau En attente Retiré

   Champs de script

   Champ	Détails
   Champ	Un champ de Liste de consultation. Cliquez sur le bouton Liste de consultation pour afficher une boîte de dialogue listant les champs disponibles (ainsi que toutes les références et références inverses) dans le module spécifié dans Module : (Nom du champ). Les références et les références inverses peuvent être imbriquées à n’importe quel niveau. Sélectionnez un champ pour l’ajouter à la table. Note: L’ordre des champs dans la table est important, car il définit l’ordre dans lequel les valeurs des champs sont transmises au code du script.
   [tableau]	Un champ sélectionné dans la Liste de consultation Champ est ajouté à la table. Les champs peuvent être réorganisés en sélectionnant et en faisant glisser un numéro de ligne à la position souhaitée. Utilisez le bouton Supprimer pour supprimer un champ sélectionné de la table.

   Nous voyons ici un exemple d’onglet Champ pour le champ Données sommaires dans le module Thésaurus :

   

3. L’onglet Script sert à définir une sous-routine Perl (fieldFormat ) pour calculer la valeur du champ. Il comprend deux champs :

   

   Champ	Détails
   Script	Saisissez une sous-routine Perl permettant de calculer la valeur du champ. Conseil : Si une Entrée de Registre Preview a été définie pour cette définition de champ (nommée dans Nom : (Nom du champ)), le bouton Aperçu sera activé. Cliquez sur le bouton pour prévisualiser la valeur du champ calculé. Une sous-routine de script Perl vide appelée fieldFormat est ajouté au champ Script lorsqu’un enregistrement de Définition de champ est créé : Modifiez la sous-routine pour produire la valeur du champ. La valeur souhaitée pour le champ est définie à l'aide de l'instruction return. Dans cet exemple, return ""; définit la valeur du champ comme étant vide. Une valeur return de la fonction Perl undef ne modifie pas la valeur du champ. Remarques : Strict : le code de la sous-routine doit être conforme au module strict de perl et toutes les variables utilisées doivent être strictement définies. Ainsi, chaque définition de variable doit être précédée du mot réservé my. Conteneur : le code de la sous-routine s’exécute à l’intérieur d’un conteneur afin que l’exécution du code ne permette que le calcul de la valeur et n’autorise pas l’accès aux fonctions Perl qui interagissent avec la machine (appels du système d’exploitation ou fonctions de fichiers, par exemple). Variables prédéfinies Les variables Perl suivantes sont accessibles dans le code du script : @fields liste Perl des valeurs des champs de script. $json référence à un hachage Perl des valeurs de Champs de Script. $luts référence à un hachage Perl contenant des valeurs de Liste de consultation au niveau du système. $langdelim délimiteur utilisé entre les différentes langues. $langcount nombre de langues prises en charge. $ENV{dateformat} la chaîne de format de date utilisée dans votre implémentation d'EMu. $ENV{timeformat} la chaîne de format d’heure utilisée dans votre implémentation d'EMu. Chacune de ces variables prédéfinies est présentée ci-dessous : Champs de Script Lorsque le code du script est exécuté, les valeurs des champs définis dans la liste Champs de Script sont transmises au code en cours d’exécution. Ces valeurs sont accessibles via deux variables Perl : Variable Détails @fields Le tableau Perl @fields est une liste Perl contenant les valeurs de la liste Champs de Script dans l’ordre où elles sont définies. Par exemple, si la liste Champs de Script contient : TerAcronyme TerTerme irn SecRecordStatus la liste @fields se compose de la valeur du champ TerAcronym, suivie de la valeur de TerTerm, puis de la valeur de irn, et enfin de SecRecrdStatus. Voici un exemple de liste @field en Perl : ('AAT', 'Culture', 400016, 'Active') L'index de la liste Perl permet d'accéder à des valeurs individuelles. En reprenant l'exemple précédent, on peut utiliser les index de liste suivants : $fields[0] (champ TerAcronyme, valeur 'AAT') $fields[1] (champ TerTerm, valeur 'Culture') $fields[2] (champ irn, valeur 400016) $fields[3] (champ SecRecordStatus, valeur 'Active') $json La variable $json est disponible pour accéder aux valeurs des Champs de Script. La variable est une référence à un hachage Perl, où la clé est le nom du champ et la valeur est la valeur du champ. En reprenant l'exemple précédent, on peut utiliser les recherches dans le hachage suivantes : $json->{TerAcronym} (champ TerAcronyme, valeur 'AAT') $json->{TerTerm} (champ TerTerm, valeur 'Culture') $json->{irn} (champ irn, valeur 400016) $json->{SecRecordStatus} (champ SecRecordStatus, valeur 'Active') Chaque valeur de champ passée au script existe même si elle est vide dans EMu. Il n’est donc plus nécessaire de vérifier constamment si une valeur est définie ou existe. Les variables Perl @fields et $json peuvent être intercalées selon les besoins. Valeurs La représentation Perl des valeurs des champs EMu dépend du type de champ. EMu prend en charge : Valeurs atomiques : une valeur unique. Valeurs imbriquées : une liste de valeurs. Le nom du champ se termine par _tab ou 0. Valeurs doublement imbriquées : une liste contenant une liste de valeurs. Le nom du champ se termine par _nesttab. Valeurs atomiques Les valeurs atomiques EMu sont représentées en Perl sous forme de chaîne de caractères ou de nombre. Le tableau ci-dessous indique la représentation d’une valeur EMu en Perl : Type EMu Type Perl Texte Chaîne de caractères Entier Nombre Nombre à virgule flottante Nombre Chaîne de caractères Chaîne de caractères Date Chaîne (aaaa-mm-jj e) Heure Chaîne (hh :mm :ss.sss) Latitude Chaîne (jj mm SS D) Longitude Chaîne (jj mm SS D) Si un champ EMu n'a pas de valeur (il est vide), une chaîne vide ("") est renvoyée lors de l'accès à la valeur sous Perl. Valeurs imbriquées Les valeurs imbriquées d’EMu sont représentées en Perl comme une référence à une liste de valeurs. Le type de chaque élément de la liste est déterminé à partir du tableau utilisé pour les valeurs atomiques ; par exemple, une liste de valeurs textuelles EMu correspond à une liste de chaînes de caractères en Perl. Le mécanisme d'indexation de Perl permet d'accéder à des valeurs individuelles de la liste. Par exemple, si nous avons un Champ de Script nommé Colours_tab avec des valeurs ['Red', 'Blue', 'Green'], le code suivant peut être utilisé pour accéder aux valeurs : my $colours = $json->{Colours_tab} ; my $first = $colours->[0] ; my $second = $colours->[1] ; my $third = $colours->[2] ; Le nombre de valeurs dans la liste est également disponible : my $colours = $json->{Colours_tab}; my $count = (ref($colour) eq "ARRAY" ? @{$colour} : 0); Note: Normalement, @{$colour} suffirait, mais Perl strict nécessite une vérification pour s'assurer que l'on accède bien à un tableau (une liste). Si un champ imbriqué EMu ne contient aucune valeur, une liste vide ([]) est renvoyée lors de l’accès à la valeur en Perl. Valeurs doublement imbriquées Les valeurs doublement imbriquées d’EMu sont représentées comme une référence à une liste de valeurs où chaque valeur est une référence à une liste de valeurs. Le type de chaque valeur est celui de son type atomique associé. Le mécanisme d'indexation de Perl permet d'accéder aux listes imbriquées et aux valeurs individuelles. Par exemple, si nous avons un Champ de Script nommé Countries_nesttab avec des valeurs [['Australia', 'Canada'], [], ['France']], le code suivant peut être utilisé pour accéder aux listes internes, puis aux valeurs individuelles : my $countries = $json->{Countries_nesttab}; # Accès à la liste interne my $first = $countries->[0]; my $second = $countries->[1]; my $third = $countries->[2]; # Accès aux valeurs individuelles my $firstfirst = $first->[0]; (returns 'Australia') my $firstsecond = $first->[1]; (returns 'Canada') Si le champ EMu doublement imbriqué ne contient aucune valeur, une liste vide ([]) est renvoyée lors de l’accès à la valeur en Perl. Si une liste interne ne contient pas de valeur, une liste vide ([]) est renvoyée pour cette valeur. Lorsque vous retournez une valeur dans le code du script pour définir une valeur de champ, la valeur Perl retournée doit correspondre au type de champ d’EMu pour le champ : Pour un champ atomique EMu, une chaîne ou un nombre doit être retourné dans le bon format (par exemple, pour un champ de date, la valeur doit être conforme à yyyy-mm-dd). Pour un champ imbriqué, une référence à une liste Perl contenant les valeurs à définir doit être retournée. Pour un champ à double imbrication, une référence à une liste Perl dont chaque valeur est une référence à une liste Perl, chaque liste interne contenant la valeur à définir. Pour effacer un champ atomique, retournez une chaîne vide "" ; et pour effacer un champ imbriqué ou doublement imbriqué, retournez une référence à une liste vide []. Champs de référence Si la liste Champs de Script contient un champ de référence, la représentation Perl de la valeur du champ est celle de chaque composant du champ de référence. Par exemple, si un champ Champs de Script est une entrée consistant en une liste de valeurs de référence où chaque référence fait référence à une liste de valeurs, alors la valeur Perl sera une référence à une liste où chaque entrée est une référence à une liste contenant la valeur. Suivre une série de champs de référence peut donner des valeurs Perl assez complexes. Champ de référence inversée Si la liste Champs de Script contient un champ de référence inversée, la représentation Perl du champ est une référence à une liste de valeurs, où chaque valeur est déterminée par la représentation Perl de ce qui suit le champ de référence inversée. Considérons le cas suivant La représentation Perl est une référence à une liste pour un champ de référence inversée. Cependant, un champ de référence inversée peut faire référence à un autre champ (local ou de référence), par exemple reversref.ref_tab.local. Dans ce cas, reverseref est une référence à une liste ; chaque élément de cette liste est une référence à une liste, car un champ ref_tab est représenté par une référence à une liste et, dans cette liste, chaque valeur est une chaîne de caractères pour local. C'est donc la partie qui suit le . qui détermine le reste de la structure Perl. Par exemple, si un champ Champs de Script est un champ de référence inverse référençant une seule valeur, alors la valeur Perl sera une référence à une liste de valeurs. Si, en revanche, le champ de référence inverse faisait référence à une liste de valeurs, alors la valeur Perl serait une référence à une liste de valeurs où chaque valeur est une référence à une liste de valeurs. Langues multiples Si plusieurs langues sont activées dans votre implémentation d’EMu, le code du script doit s’assurer que les valeurs générées pour les champs multilingues contiennent des valeurs pour toutes les langues : La variable prédéfinie $langcount contient le nombre de langues prises en charge par votre implémentation EMu. Si ce nombre est supérieur à un, assurez-vous que la valeur du champ renvoyée couvre toutes les langues $langcount. La variable prédéfinie $langdelim contient le délimiteur qui doit figurer entre chaque valeur de langue. Par exemple, si $langdelim contient la valeur ;:; et que $langcount est défini sur deux, une valeur de champ retournée doit ressembler à language 1;:;language 2. Lorsque vous écrivez du code de script générique où le nombre de langues prises en charge est inconnu, vous verrez un code de script qui boucle en fonction du nombre de langues : my $sumstr = ""; for (my $lang = 0; $lang < $langcount; $lang++) { my $str = langstr($term, $lang, $langdelim); ... $sumstr .= $langdelim if ($lang > 0); $sumstr .= $str; } Le code ci-dessus parcourt chacune des langues prises en charge, à l'aide de $langcount. Pour chaque langue, nous extrayons la valeur correspondant à cette langue à partir de la valeur d'un champ (à l'aide de la langstr()fonction prédéfinie). Nous construisons ensuite la chaîne de retour en ajoutant le délimiteur de langue $langdelim si nous traitons des langues supplémentaires, puis nous ajoutons la valeur de cette langue. Le résultat dans $sumstr est la valeur du champ pour toutes les langues avec le délimiteur correct entre chaque langue. Conseil : Si votre version d’EMu ne prend pas en charge plusieurs langues, la boucle peut être supprimée et le code simplifié pour ne manipuler que les valeurs complètes des champs. Fonctions prédéfinies Un certain nombre de fonctions prédéfinies sont disponibles pour une utilisation dans le code de script : langstr($value, $lang, $langdelim) Permet d'extraire une valeur spécifique à une langue à partir de la chaîne $value : $value est une chaîne de caractères, généralement une valeur d’un champ EMu. $lang est un nombre qui sert d'index pour accéder à la langue souhaitée (l'indexation commence à zéro). $langdelim est le délimiteur utilisé entre les langues dans $value. Notez que $langdelim est prédéfini ; vous n'avez donc pas besoin de le définir. Si aucune valeur n’est définie pour un index $lang donné, la première valeur non vide est renvoyée. addtext($prevalue, $postvalue, $join) Renvoie $prevalue$join$postvalue si $prevalue et $postvalue ne sont pas vides : Si une valeur est vide, l’autre est renvoyée. Si les deux sont vides, une chaîne vide est renvoyée. addstatus($str, $status, $lang, $langdelim) Ajoute la valeur $status pour l’index $lang donné à $str si $status n’est pas vide et si $status est différent de la valeur de la variable d’environnement EMUDEFAULTSTATUS. En d’autres termes, il ne préfixe le statut que s’il n’est pas la valeur par défaut. formatdate($string, $format) Renvoie une chaîne contenant une valeur de date formatée en utilisant $format. La valeur de $string doit être conforme au format de date yyyy-mm-dd e, qui est le format utilisé lorsqu’un champ de date est demandé dans la liste Champs de Script (détails sur les formats de date ici). Le format de date défini pour votre version d’EMu est accessible via la variable d’environnement prédéfinie $ENV{dateformat}. L’appel formatdate($string, $ENV{dateformat}) renverra une date au format affiché dans le client EMu. formattime($string, $format) Renvoie une chaîne contenant une valeur temporelle formatée en utilisant $format. La valeur de $string doit être conforme au format d’heure hh:mm:ss.sss, qui est le format utilisé lorsqu’un champ d’heure est demandé dans la liste Champs de Script (détails sur les formats d’heure ici). Le format d'heure défini pour votre version d'EMu est accessible via la variable d'environnement prédéfinie $ENV{timeformat}. L’appel formattime($string, $ENV{timeformat}) renverra une heure au format affiché dans le client EMu. formatlatlong($string) Renvoie une chaîne de latitude ou de longitude formatée en utilisant le format d m s D. La valeur de $string doit être conforme au format de latitude / longitude ddd mm SS D, qui est le format utilisé lorsqu’un champ de latitude / longitude est demandé dans la liste Champs de Script (détails sur les formats de latitude et de longitude ici). Listes de consultation système La variable prédéfinie $luts est une référence à un hachage Perl dont la clé est le nom d’une Liste de consultation système et dont la valeur est la valeur attribuée à cette Liste de consultation. Par exemple, la valeur $luts->{Yes} renvoie la valeur attribuée à la Liste de consultation Système Yes (une chaîne contenant la valeur Yes dans les langues prises en charge par votre installation EMu). Note: Lors de l’accès aux données de la Liste de consultation système, le nom (avec le mot System supprimé) de la Liste de consultation système est utilisé pour obtenir sa valeur. Pour Système Yes, c’est Yes, c’est-à-dire $luts->{Yes} Débogage Lors du développement d’un script, il peut être nécessaire de déboguer le code pour s’assurer que la valeur correcte du champ est calculée. La façon la plus simple de déboguer du code est de définir un Entrée du Registre Preview Record, qui vous permet de prévisualiser le résultat du code. Une fois qu’un enregistrement d’aperçu a été défini, le bouton Aperçu de l’onglet Script permet d’afficher la valeur du champ calculé. Vous pouvez utiliser une instruction prématurée return pour afficher la valeur des variables, y compris les valeurs de champ transmises à la fonction fieldFormat. Par exemple, considérons le code suivant : sub fieldFormat { my $acronym = $fields[0]; my $term = $fields[1]; my $irn = $fields[2]; my $status = $fields[3]; return($acronym); } L’instruction return a pour effet d’afficher la valeur de $acronym lorsque le bouton Aperçu est cliqué. Grâce à cette approche, il est possible de vérifier des valeurs individuelles au fur et à mesure du développement du script. Une deuxième méthode pour déboguer le code d'un script consiste à utiliser l'instruction print de Perl. Toute sortie générée par une instruction print est enregistrée dans le fichier journal de chargement en arrière-plan standards. Le fichier journal se trouve dans le répertoire loads/standards/logs/current du serveur EMu. Pour obtenir un résultat à partir des instructions print, il faut cliquer sur le bouton Aperçu afin d'exécuter le code du script.
   Erreurs	Une liste en lecture seule des erreurs identifiées dans la routine Perl. Toutes les erreurs doivent être corrigées avant que la valeur du champ puisse être générée.