WIPO Sequence Validator – Manuel d’utilisation

1. Processus

Le logiciel peut être employé dans les quatre cas d’utilisation suivants :

1. valider un fichier au format ST.26 de l’OMPI;
2. demander le statut d’une validation en cours d’exécution;
3. mettre à jour des fichiers de configuration (réservé à l’administrateur de l’office de propriété intellectuelle); et
4. appeler un point d’extrémité de rappel pour lui envoyer le résultat de la validation à la fin du processus de validation.

Note : ce point d’extrémité de rappel ne fait pas partie du domaine d’application du logiciel.  C’est l’office de propriété intellectuelle chargé d’élaborer et de paramétrer ce service qui doit établir le point d’extrémité.

Pour la validation d’un listage des séquences au format ST.26 de l’OMPI, le logiciel prend en entrée des instances XML situées dans une structure de fichier, lance un processus de validation et génère un rapport de vérification contenant les résultats de la validation. Il peut aussi, à titre facultatif, renvoyer ce rapport de vérification en appelant un point d’extrémité de rappel.

Le principal processus effectué par le logiciel est le suivant :

• Le système informatique de l’office de propriété intellectuelle concerné enregistre le fichier XML dans un dossier par défaut appelé “Inbox”, ou dans le dossier spécifié dans la demande.
• Il lance ensuite une demande de type HTTP Post pour obtenir la validation du fichier. Selon la configuration, il peut demander une validation complète (“full”) ou de formalité (“formality”).  Le processus de validation “de formalité” vérifie que le fichier ST.26 est bien un fichier XML et le valide par rapport à la DTD du format ST.26.  Le processus “complet” valide le fichier ST.26 par rapport aux règles de vérification officielles, qui sont déduites de la norme ST.26; il effectue aussi le processus de validation “de formalité”.  

Note : il est recommandé de réserver le processus de validation “de formalité” aux dépôts de demande en ligne, car ce processus peut s’exécuter de manière synchrone, tandis que le processus de validation “complet”, qui prend beaucoup plus de temps, est recommandé pour le traitement des demandes par lots. 

• Une fois la validation achevée, la réponse envoyée indique si le fichier a obtenu la validation “de formalité” et, dans le cas où le système informatique de l’office a demandé une validation “complète”, si le processus de validation des règles officielles a été correctement lancé.
• Si le logiciel effectue une validation “complète”, il accède au fichier XML dans le dossier “Inbox” et lance le processus de validation selon les règles officielles, puis il exécute les tâches suivantes :
• Il génère un fichier XML contenant un rapport de vérification (“Verification Report”) dans le dossier “Output” spécifié, et il déplace dans un dossier “Outbox” le fichier XML ST.26 qu’il a validé.
• Une fois le processus de validation selon les règles officielles achevé, le logiciel appelle le point d’extrémité de rappel, s’il est configuré, en intégrant dans la demande des informations supplémentaires concernant le processus de validation. La structure de la demande et quelques exemples de données sont présentés dans la section 2.2 ci-après.
• Le point d’extrémité de rappel doit répondre soit par un code vide, soit par un code de succès (aucune erreur). [Note : cette étape n’est effectuée que si le service Web extérieur a été rendu accessible et que l’appel a été configuré dans le logiciel.]  Il est en outre nécessaire de disposer d’une connectivité entre le logiciel et le point d’extrémité de rappel.  Comme nous l’avons indiqué plus haut, le service Web extérieur ne fait pas partie du logiciel et doit être développé et configuré par les offices conformément à la convention définie plus loin.
• Le système de l’office de propriété intellectuelle peut accéder au rapport de vérification dans le dossier “Report”.

2. Déploiement

Étape 1 : Sélectionner le format

Comme indiqué plus haut, le logiciel est fourni sous deux formats binaires : un fichier JAR pouvant être exécuté comme un service Web, ou d’un fichier WAR pouvant être déployé sur un serveur Tomcat.  L’office choisira le format qui lui convient le mieux selon le type d’infrastructure sur laquelle il entend déployer le logiciel.

Les deux formats binaires sous lesquels le logiciel est disponible sont les suivants :

• Un fichier binaire JAR créé sous Spring Boot : Ce fichier binaire est un JAR exécutable. Il nécessite l’installation de Java 17.
• Un paquetage binaire WAR : Ce fichier binaire est destiné à être déployé sur un conteneur de servlets. Il faut disposer d’un serveur d’applications compatible avec Spring Boot 3.1.0 et Servlet Spec 4.0.1, comme Tomcat 10.

Les sections ci-après contiennent des indications détaillées sur la manière de déployer le logiciel, que ce soit par une application créée sous Spring Boot ou par un fichier WAR à déployer dans un serveur d’applications Java.

• Service en tant que JAR
• Service en tant que WAR

Le fichier JAR créé sous Spring Boot contient un serveur intégré qui permet de déployer l’API du logiciel sans avoir besoin d’un serveur indépendant. Ce système simplifie considérablement la configuration et le déploiement en termes d’infrastructures.

Pour lancer le serveur intégré, il faut exécuter la commande suivante, lorsque Java 17 est déjà installé sur le serveur :

java -jar wipo-sequence-validator.jar

Comme Java ne garantit pas l’emploi du codage UTF-8, il faut indiquer “UTF-8” dans le fichier de propriétés système “file.encoding”. Par défaut, le serveur se lance sur le port 8080; pour modifier le numéro de port, il faut ajouter l’option “--server.port” en ligne de commande, comme indiqué ci-après : Ce paramétrage peut être effectué de la manière suivante :

java -D"file.encoding=UTF-8" -jar wipo-sequence-validator.jar –-server.port=<port-number>

On peut accéder à l’API du logiciel au moyen de l’application Swagger UI après déploiement du fichier JAR, où l’office de propriété intellectuelle doit apporter les modifications ci-après : [host-name] doit être remplacé par le nom du serveur hôte :

 http://[host-name]:8080/wipo-sequence-validator/swagger-ui/index.html

On peut accéder à l’API du logiciel depuis les points d’extrémité suivants :

• Méthode GET : 

  http://[host-name]:8080/wipo-sequence-validator/api/v2.0/status/validationId

• Méthode POST : 

  http://[host-name]:8080/wipo-sequence-validator/api/v2.0/validate

Par défaut, le logiciel utilise les paramètres mémoire de la machine virtuelle de Java (JVM) définis par défaut. La taille du tas (“heap size”) maximale par défaut est un quart de la mémoire physique disponible. Pour modifier la taille du tas maximale, il faut utiliser l’option “-Xmx” lorsque l’exécution est lancée en ligne de commande :

java -D"file.encoding=UTF-8" -Xmx[size]-jar wipo-sequence-validator.jar

Le logiciel peut aussi être installé en tant que service géré par le système d’exploitation, par exemple pour qu’il puisse être lancé en même temps que lui. Il est possible de configurer de cette manière le fichier JAR créé sous Spring Boot sur toutes les plateformes prises en charge par le logiciel WIPO Sequence, à savoir Windows, Linux et Mac OS.

Le guide ci-dessous présente une méthode détaillée permettant de créer un service système qui exécute le fichier JAR sous chaque système d’exploitation. Il contient en outre des informations sur la manière de configurer les différentes options du service et d’exécuter l’application.

En ce qui concerne le second type de fichier binaire proposé, le paquetage WAR peut être déployé sur un serveur d’application Java existant, comme Apache Tomcat 10. Note : il faut disposer d’un conteneur compatible avec Servlet 4.0.1.

Les instructions ci-dessous concernent le déploiement sur un serveur d’applications Tomcat. Ici,

$TOMCAT_ROOT

désigne le dossier racine du serveur Tomcat; cette valeur doit être remplacée par le chemin réel :

• Arrêter le serveur :

  $TOMCAT_ROOT\bin\catalina.bat stop

• Copier le fichier WAR dans

  $TOMCAT_ROOT\webapps\wipo-sequence-validator.war

• Lancer le serveur :

  $TOMCAT_ROOT\bin\catalina.bat start

Note : comme Java ne garantit pas l’emploi du codage UTF-8, il faut indiquer “UTF-8” dans le fichier de propriétés système “file.encoding” qui est utilisé au démarrage du serveur d’applications. Ce paramétrage peut être effectué de la manière suivante : -D"file.encoding=UTF-8"

On peut accéder à l’API du logiciel au moyen de l’application Swagger UI, comme indiqué plus haut :

http://host-name:8080/wipo-sequence-validator/swagger-ui/index.html

On peut accéder à l’API du logiciel depuis les points d’extrémité suivants, où [host-name] doit être remplacé par le nom du serveur hôte :

• Méthode GET :

  http://[host-name]:8080/wipo-sequence-validator/api/v2.0/status/validationId

• Méthode POST :

  http://[host-name]:8080/wipo-sequence-validator/api/v2.0/validate

Par défaut, le logiciel se lance sur le port 8080 du serveur. Pour changer le numéro de port, il faut modifier le fichier de configuration de la Tomcat en suivant les instructions ci-dessous :

https://tomcat.apache.org/tomcat-10.0-doc/config/index.html

Par défaut, le logiciel utilise les paramètres mémoire de la machine virtuelle de Java (JVM) définis par défaut. La taille du tas (“heap size”) maximale par défaut est un quart de la mémoire physique disponible.

Pour modifier la taille du tas maximale, il faut utiliser l’option “-Xmx” lorsque l’exécution est lancée en ligne de commande, comme indiqué plus haut.

Étape 2 : Créer le système de dossiers

La structure du système de fichiers employée par le logiciel comporte cinq dossiers principaux :

• Dossier “Inbox” : Dossier local dans lequel les fichiers ST.26 sont déposés par un office de propriété intellectuelle pour validation.
• Dossier “Process” : Dossier local par lequel les fichiers issus du dossier “Inbox” transitent temporairement pendant le traitement. Ce dossier contient deux sous-dossiers :
  • Dossier “Full validation” : Stocke les fichiers en attendant leur validation complète.
  • Dossier “Formality validation” : Stocke les fichiers en attendant leur validation de formalité.
• Dossier “Outbox” : Une fois la validation achevée, le logiciel stocke la source du fichier ST.26 dans ce dossier local.
• Dossier “Report” : Ce dossier local stocke les résultats de la validation, qui sont enregistrés dans un ou plusieurs fichiers contenant un rapport de vérification.
• Dossier “Params” : Dossier local dans lequel se trouve un fichier JSON (.json) contenant tous les paramètres de validation définis dans la demande de validation, afin que ces paramètres puissent être utilisés par le processus de validation profonde asynchrone.

On trouvera ci-dessous un exemple de structure de ce système de fichiers :

Étape 3 : Test

Pour tester le service Validator, il suffit de suivre les étapes ci-après dans l’application postman :

• Ouvrez l’application postman et créer une nouvelle demande
• Ajouter les informations relatives au corps de la demande :
• Après avoir cliqué sur « Send Â», vous devriez obtenir la réponse ci-après :

3. Demande

Demande du point d’extrémité de rappel

WIPO Sequence Validator, après la conclusion de la demande de validation, génère un fichier JSON qui comprend les paramètres nécessaires pour une demande à un point d’extrémité de rappel. La demande doit contenir les paramètres ci-après, qui définissent les emplacements des fichiers et le processus de validation :

{ "currentApplicationNumber": "string", "currentSEQLVersionNumber": "string", "patentApplicationNumber": "string", "seqlInputLocation": "string", "verificationReportOutputPath": "C:/temp/st26/reports/", "nameFile": "valid2Warning.xml", "type": "FULL" }

Le champ “seqlInputLocation” de la demande de validation doit être paramétré de manière à indiquer le chemin du listage des séquences XML à valider. Si l’office laisse ce champ vide, le logiciel va tenter de valider le fichier XML portant le nom “nameFile” et situé dans le dossier par défaut “Inbox”. Le paramètre “nameFile” indique le nom du fichier de listage des séquences à valider.

Le champ “verificationReportOutputPath” de la demande indique l’emplacement du fichier contenant le rapport de vérification (.xml) généré par le logiciel. Si l’utilisateur laisse ce champ vide ou s’il indique un chemin non valable, le rapport de vérification est enregistré dans le dossier par défaut “Reports”.

Si la propriété “api.URL” est configurée, le logiciel va tenter d’envoyer les résultats de la validation au point d’extrémité se trouvant à l’URL indiquée.

Pour communiquer avec le logiciel, le point d’extrémité de rappel doit respecter cette convention de service Web suivante (YAML).

En outre, la demande doit être un objet JSON ayant la structure suivante :

{ "currentApplicationNumber": "string", "currentSEQLVersionNumber": "string", "elapsedTime": 0, "endTime": "string", "errorSummary": [ { "dataElement": "string", "detectedSequence": "string", "index": 0, "key": "string", "locmessage": "string", "params": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "paramsForXML": [ { "key": "string", "value": "string" } ], "reportValue": "string", "sequenceIDNumber": "string", "type": "string" } ], "httpStatus": "string", "parentApplicationNumber": "string", "parentSEQLVersionNumber": "string", "processID": "string", "seqIDQuantity": 0, "seqInputQuantity": 0, "seqlType": "string", "startTime": "string", "totalErrorQuantity": 0, "totalWarningQuantity": 0, "verificationReportOutputPath": "string"

Voici un exemple d’instance JSON à envoyer au point d’extrémité extérieur ayant appelé le logiciel :

{ "processID": "1608194222169dvVE", "seqlType": "ST.26", "httpStatus": "SUCCESS", "currentApplicationNumber": "string", "currentSEQLVersionNumber": "string", "parentApplicationNumber": "string", "parentSEQLVersionNumber": "string", "verificationReportOutputPath": "C:/temp/report.xml", "startTime": "2020-12-17 09:36:54.000000", "endTime": "2020-12-17 09:37:26.000607", "elapsedTime": 32607, "totalWarningQuantity": 1, "totalErrorQuantity": 2, "seqInputQuantity": 3, "seqIDQuantity": 3, "errorSummary": [ { "index": 0, "reportValue": "", "type": "WARNING", "params":com.wipo.st26.ipotool.models.ServiceRequest@5887858, "key": "X_EARLIEST_PRIO_APPLICATION_ID_MISSING", "locmessage": "Earliest priority application information is absent. It must be provided when a priority claim is made to an earlier application.", "detectedSequence": "", "dataElement": "PROPERTY_NAMES.EARLIEST_PRIORITY_APPLICATION" }, { "index": 0, "reportValue": "-", "type": "ERROR", "params": {}, "key": "INVENTION_TITLE_MISSING", "locmessage": "The invention title is missing. At least one invention title must be entered.", "detectedSequence": "", "dataElement": "PROPERTY_NAMES.INVENTION_TITLE_BAG" }, { "index": 1, "reportValue": "-", "type": "ERROR", "params": {}, "key": "INVENTION_TITLE_MISSING", "locmessage": "The invention title is missing. At least one invention title must be entered.", "detectedSequence": "", "dataElement": "PROPERTY_NAMES.INVENTION_TITLE_BAG" } ] }

4. Rapport

Rapport de validation

Le rapport de vérification produit par WIPO Sequence est en format XML, et éventuellement en format HTML, au moyen de la même feuille de style que celle utilisée dans WIPO Sequence. Les attributs indiqués au niveau de la racine sont les suivants :

• "applicationNumberText" : la demande associée à ce listage des séquences;
• "productionDate" : la date à laquelle la validation a été réalisée;
• "filingDate" : la date de dépôt de la demande;
• "softwareBuildVersion" : la version du logiciel utilisée pour la validation;
• "softwareVersion" : la version de WIPO Sequence utilisée pour générer le listage des séquences; et
• "sourceFileName" : le nom de l’instance XML d’un listage des séquences.

Le modèle ou la définition du schéma XML, utilisé pour produire le rapport de vérification est le suivant :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <VerificationReport productionDate="YYYY-MM-DD" sourceFileName="[ST.26 filename]"> <VerificationMessageBag> <VerificationMessage> <Severity>[ERROR | WARN | XML_WARN | XML_ERROR]</Severity> <DataElement>[ST.26 element]</DataElement> <DetectedSequence>[Sequence ID]</DetectedSequence> <DetectedValue>[value]</DetectedValue> <MessageKey>[Message key]</MessageKey> <ParameterBag> <Parameter key="param key">Param value</Parameter> <ParameterBag> <LocalizedMessage> [Localized message] </LocalizedMessage> </VerificationMessage> ... </VerificationMessageBag> </VerificationReport>

En ce qui concerne la sévérité indiquée, veuillez noter la catégorisation suivante :

• ERROR – un message d’erreur s’affiche lors de la vérification “complète”
• WARNING - un avertissement s’affiche lors de la vérification “complète”
• XML_ERROR - un message d’erreur s’affiche lors de la vérification “de forme”
• XML_WARN - un avertissement s’affiche lors de la vérification “de forme”

Après validation, le rapport de vérification généré dans l’un ou l’autre des formats, ou dans les deux, est situé dans le "verificationReportOutputPath", qui se trouve par défaut à l’adresse suivante

./temp/st26/reports/[verificationID]/

Un exemple de rapport de vérification au format XML est fourni dans les ressources ci-dessous.

5. Configuration

Paramétrage par défaut

Le logiciel est configuré au moyen d’un fichier de propriétés. Les valeurs par défaut peuvent être trouvées dans *the published application.yml*.

Pour modifier la valeur des paramètres de ce fichier, il faut utiliser un autre fichier “application.yml”. Plusieurs options sont possibles, comme l’indique la documentation de Springboot.

Le chemin et le nom du fichier de configuration peuvent être indiqués en spécifiant le paramètre en ligne de commande lorsqu’on lance le logiciel :

• Pour un déploiement par un fichier JAR :

  java -jar -Dspring.config.location= <PATH_TO_FILE> wipo-sequence-validator.jar

• Pour un déploiement par un fichier WAR dans une Tomcat, il faut ajouter l’entrée suivante dans les options CATALINA_OPTS :
  • Windows :

    set SPRING_CONFIG_ADDITIONAL-LOCATION=-Dspring.config.location=<PATH_TO_FILE>

  • Linux :

    export SPRING_CONFIG_ADDITIONAL-LOCATION="-Dspring.config.location=<PATH_TO_FILE>

Si l’on déploie le logiciel par un fichier WAR, le nouveau dossier “application.yml” peut aussi être copié dans le dossier “WEB-INF/classes” de l’application Web.

Dans le fichier “application.yml file”, vous pouvez activer ou désactiver la création du rapport HTML. La valeur "true" permet d’activer la génération de rapports et la valeur "false" de la désactiver. Le contenu de ce rapport est envoyé vers le point d’extrémité de rappel dans le champ "errorSummary" de la demande “ServiceRequest”.

Règle de vérification VXQV_49

La valeur “optionalEnglishQualifierValue” peut être définie sur 'true' si l’utilisateur souhaite activer la règle VXQV_49, et peut définir la sévérité de la règle en mettant à jour la valeur “optionalRuleType” sur 'ERROR' ou 'WARNING'

Point health

Le logiciel a un point d’extrémité /health qui fournit des informations de base sur la santé de l’application. Pour explorer le point d’extrémité “health”, il faut ouvrir l’URL suivant :

Le point d’extrémité devrait afficher ce qui suit :

• Le statut sera “UP” tant que l’application sera en bonne santé.
• Il affichera “DOWN” si l’application est en mauvaise santé en raison d’un problème de connectivité avec la base de données ou d’un manque d’espace disque, etc.

Le point d’extrémité “health” n’affiche qu’un statut “UP” ou “DOWN”. La propriété suivante du fichier application.yml fournit tous les détails, y compris l’état de chaque indicateur de santé qui a été vérifié dans le cadre du bilan de santé.

Le point d’extrémité “health” comprend maintenant les détails du “DiskSpaceHealthIndicator” qui est exécuté dans le cadre du bilan de santé.

Le point d’extrémité “health” devrait apparaître comme suit :

Messages en langue locale

Le logiciel peut générer des messages, par exemple dans le rapport de vérification, dans chacune des 10 langues officielles du PCT (français, allemand, anglais, arabe, chinois, coréen, espagnol, japonais, portugais et russe).

Par défaut, ces messages sont générés en anglais. Pour configurer le logiciel afin qu’il génère ces messages dans d’autres langues, le paramètre “validator_locale” du fichier “application.yml” doit être modifié en indiquant le code de langue souhaité.

Noms d’organismes personnalisés

Pour que les offices puissent inclure leurs propres noms d’organismes personnalisés, c’est-à-dire des noms qui ne font pas partie de la liste originale prédéfinie de noms d’organismes, ils peuvent fournir une liste d’organismes personnalisés en créant un nouveau fichier appelé “custom_organism.json” et en le plaçant dans le dossier “alternativeResourceBasePath”. Ce fichier doit avoir la structure suivante :

Version DTD alternative

Par défaut, le logiciel utilise la version la plus récente de la DTD du format ST.26 de l’OMPI. La version actuelle du logiciel exploite la version 1.3 de cette DTD. Cette version de la DTD du format ST.26, qui est la plus récente, est intégrée dans la bibliothèque du logiciel qui se trouve dans le dossier "/src/main/resources” du code source (ce chemin est celui qui est défini dans le fichier JAR ou WAR). Elle est indiquée en référence dans le fichier “catalog.xml” qui se trouve dans le même dossier.

La version de la DTD employée au cours de la validation est celle qui est définie dans la déclaration DOCTYPE du fichier XML. Dans un premier temps, le système utilise le champ “publicId” pour déterminer l’emplacement de la DTD à utiliser. Si le catalogue ne contient pas de champ “publicId”, le système tente de trouver la DTD dans le dossier racine dans lequel le processus Java est en cours d’exécution.

Pour pouvoir valider des fichiers ST.26 par rapport à une version plus ancienne de la DTD de ce format, le fichier DTD concerné doit être accessible au logiciel. À cette fin, deux méthodes sont possibles :

1. Décompresser le fichier JAR et ajouter une référence à la DTD supplémentaire ou alternative du format ST.26 dans le dossier “src/main/resources”. Modifier le fichier “catalog.xml” et ajouter une nouvelle entrée définissant la DTD supplémentaire, ou modifier l’entrée existante. Par exemple :

1. Au lieu de modifier le fichier JAR, il convient de suivre les étapes suivantes :
   i) Copier "catalog.xml" et toutes les DTD dans un dossier local;
   ii) Modifier "catalog.xml" pour inclure une référence à la DTD ST.26 supplémentaire; et
   iii) Définir cette propriété du système Java lors du lancement : “xml.catalog.files=<path_to_catalog.xml>”

Dans Tomcar pour Windows, on peut également le faire en ajoutant cette variable d’environnement :

6. Ressources

Les ressources ci-après peuvent être utiles aux offices :

• Exemple de rapport de vérification
• Spécification complète de l’API, YAML
• Noms des propriétés, JSON