Руководство по использованию WIPO Sequence Validator

1. Рабочий процесс

Программа позволяет выполнять следующие четыре операции:

1. проверка файла стандарта ST.26;
2. запрос состояния выполняемой проверки;
3. обновление файлов конфигурации (эта операция может быть выполнена только администратором ВИС);
4. вызов конечной точки обратного вызова с передачей результата проверки по завершении процесса проверки.

Примечание: конечная точка обратного вызова находится вне программы Validator.  Ведомства должны создать конечную точку сами при настройке сервиса.

Для проверки перечня последовательностей по стандарту ВОИС ST.26 программа использует экземпляры файлов XML, расположенные в папке, далее запускает процесс проверки и генерирует отчет о проверке с результатами проверки. В качестве опции программа может выдать отчет о проверке, вызвав конечную точку обратного вызова.

Validator функционирует следующим образом:

• компьютерная система соответствующего ВИС сохраняет файл XML в заданной по умолчанию папке «Inbox» или в указанной в запросе папке;
• система ВИС инициирует запрос HTTP Post на проверку файла. В зависимости от конфигурации система ВИС может инициировать проверку файла в режиме «full» (полная проверка) или «formality» (формальная проверка).  При проверке файла в режиме «formality» проверяется, представлен ли файл стандарта ST.26 в формате XML и соответствует ли определение типа документа в файле требованиям стандарта ST.26.  При проверке файла в режиме «full» проверяется соответствие файла правилам, прописанным в стандарте ВОИС ST.26, и выполняется проверка в режиме «formality»;  

Примечание: режим проверки «formality» рекомендуется использовать только для онлайновой подачи, поскольку этот режим позволяет выполнять проверку синхронно, а режим «full» рекомендуется использовать для пакетной обработки файлов, так как такая проверка занимает намного больше времени. 

• после выполнения проверки программа отправляет ответ с указанием того, прошел ли файл проверку в режиме «formality» или нет, также, если в компьютерной системе ВИС была выбрана проверка в режиме «full», в ответе дополнительно указывается, корректно ли запустился процесс проверки файла на соответствие установленным правилам;
• если выполняется проверка в режиме «full», программа загружает файл XML из папки «Inbox» и запускает проверку на соответствие правилам, после чего выполняются нижеследующие операции;
• программа создает файл отчета в формате XML (отчет о проверке, «Verification Report») в указанной папке «Output» и перемещает проверенный файл XML стандарта ВОИС ST.26 в папку «Outbox»;
• по завершении проверки на соответствие правилам из программы осуществляется вызов конечной точки обратного вызова (если конечная точка задана), при этом в запросе передаются дополнительные данные, касающиеся процесса проверки. Структура запроса и пример данных приводятся в разделе 2.2 ниже;
• в ответе конечная точка обратного вызова должна вернуть пустое значение или код успешного выполнения (означает, что ошибок не обнаружено). [Примечание: этот шаг выполняется только в том случае, если работает внешняя веб-служба и вызов настроен в программе].  Необходимо обеспечить интеграцию между программой и конечной точкой обратного вызова.  Как уже отмечалось выше, внешняя веб-служба не является частью программы и должна быть создана и настроена ведомством в соответствии с приведенными ниже требованиями;
• Cистема ВИС может загрузить отчет о проверке из папки «Report».

2. Развертывание

Этап 1: выбор формата

Как указано ранее, программа Validator предоставляется в одном из двух бинарных форматов: файл JAR, который выполняется в качестве веб-службы, или файл WAR, который может быть развернут на сервере Tomcat.  ВИС может выбрать наиболее подходящий формат в зависимости от типа инфраструктуры, на базе которой ведомство желает внедрить Validator.

Validator предоставляется в виде следующих двух бинарных файлов:

• бинарный файл SpringBoot JAR — исполняемый файл JAR. Требуется установка Java 17;
• бинарный файл WAR — бинарный файл для установки в контейнер сервлетов. Требуется сервер приложений, совместимый с Spring Boot 3.1.0 и Servlet Spec 4.0.1, например Tomcat 10.

В нижеследующих разделах подробно описывается процесс внедрения Validator в виде приложения на базе Spring Boot или в виде приложения WAR на сервере Java-приложений.

• Служба в формате JAR
• Служба в формате WAR

Файл Spring Boot JAR содержит встроенный сервер, что позволяет внедрить Validator API без необходимости использования отдельного сервера. Это существенно упрощает настройку и внедрение на уровне инфраструктуры.

Для того чтобы запустить встроенный сервер, выполните указанную ниже команду, если на сервере уже установлен Java 17:

java -jar wipo-sequence-validator.jar

Поскольку Java не гарантирует поддержку кодировки UTF-8, для системного параметра «file.encoding» необходимо задать значение «UTF-8». По умолчанию сервер использует порт 8080, а изменить порт можно при помощи команды «--server.port» так, как это показано ниже. Сделать это можно следующим образом:

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

Доступ к Validator API можно получить через интерфейс Swagger UI после развертывания JAR-файла, при этом ВИС необходимо внести следующие изменения: вместо «[host-name]» указать имя хоста сервера:

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

Доступ к Validator API возможен в следующих конечных точках:

• Метод GET: 

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

• Метод POST: 

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

Validator использует настройки памяти виртуальной машины Java (JVM), заданные по умолчанию. По умолчанию максимальный размер кучи равняется одной четвертой доступного физического объема памяти. Изменить максимальный размер кучи можно при помощи параметра «-Xmx» из командной строки:

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

Validator может быть установлен в виде службы, контролируемой операционной системой, например, чтобы программа запускалась при загрузке операционной системы. Файл Spring Boot JAR можно настроить соответствующим образом на всех платформах, с которыми совместимо приложение WIPO Sequence: Windows, Linux и Mac OS.

В данном руководстве подробно описано, как создать системную службу, выполняющую файл JAR, для каждой операционной системы. В нем также содержится информация о настройке различных параметров службы и параметров выполнения приложения.

Что касается второго бинарного файла, то пакет WAR можно установить на существующем сервере Java приложений, например Apache Tomcat 10. Примечание: требуется контейнер, совместимый с Servlet 4.0.1.

Далее приводятся инструкции для сервера приложений Tomcat. В приведенных инструкциях «$TOMCAT_ROOT»

означает корневую папку на сервере Tomcat, и это значение необходимо заменить, указав соответствующий путь к корневой папке:

• остановите сервер, выполнив команду:

  $TOMCAT_ROOT\bin\catalina.bat stop;

• скопируйте файл WAR в папку $TOMCAT_ROOT\webapps\wipo-sequence-validator.war

• запустите сервер, выполнив команду:

  $TOMCAT_ROOT\bin\catalina.bat start

Примечание: поскольку Java не гарантирует поддержку кодировки UTF-8, при запуске сервера приложений для системного параметра «file.encoding» необходимо задать значение «UTF-8». Сделать это можно следующим образом: -D"file.encoding=UTF-8"

Доступ к Validator API можно получить через интерфейс Swagger UI, как показано выше:

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

Доступ к Validator API возможен в следующих конечных точках, где вместо «[host-name]» нужно указать имя хост-сервера:

• Метод GET:

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

• Метод POST:

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

По умолчанию сервер использует порт 8080. Чтобы задать другой порт, необходимо внести изменения в файл конфигурации Tomcat, следуя инструкция по ссылке:

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

Validator использует настройки памяти виртуальной машины Java (JVM), заданные по умолчанию. По умолчанию максимальный размер кучи равняется одной четвертой доступного физического объема памяти.

Изменить максимальный размер кучи можно при помощи параметра «-Xmx» из командной строки, как показано выше.

Этап 2: создание системы папок

В программе Validator используется пять основных папок:

• папка «Inbox» — локальная папка, в которую ВИС загружает файлы стандарта ВОИС ST.26 для проверки;
• папка «Process» — локальная папка, в которой временно хранятся файлы из папки «Inbox» во время обработки. В этой папке содержится две вложенных папки:
  • папка «Full validation» — в этой папке хранятся файлы, отправленные на проверку в режиме «full»;
  • папка «Formality validation» — в этой папке хранятся файлы, отправленные на проверку в режиме «formality»;
• папка «Outbox» — программа сохраняет исходный файл стандарта ВОИС ST.26 в этой локальной папке по завершении проверки;
• папка «Report» — локальная папка, в которой хранятся результаты проверки в виде файла отчета о проверке;
• папка «Params» — локальная папка, в которой хранится файл в формате JSON (.json) со всеми переданными в запросе на проверку параметрами проверки, используемыми для проведения асинхронной глубокой проверки.

Пример структуры файловой системы приводится ниже:

Этап 3: тестирование

Тестирование службы Validator может быть выполнено посредством платформы Postman, для чего необходимо осуществить следующие шаги:

• Откройте приложение Postman и создайте новый запрос;
• Введите информацию как тело запроса: ;
• После нажатия на кнопку «Send» («Отправить») ответ должен выглядеть следующим образом: .

3. Запрос

Запрос конечной точки обратного вызова

После выполнения запроса на проверку WIPO Sequence Validator сгенерирует JSON-файл, который содержит параметры, необходимые для запроса к конечной точке обратного вызова. Запрос должен содержать указанные ниже параметры, задающие место хранения необходимых файлов и режим проверки:

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

В поле «seqlInputLocation» запроса на проверку указывается путь к перечню последовательностей в формате XML, проверку которого необходимо выполнить. Если ведомство оставляет это поле пустым, программа попытается выполнить проверку файла XML с названием «nameFile» в заданной по умолчанию папке «Inbox». Параметр «nameFile» указывает файл перечня последовательностей, проверку которого необходимо выполнить.

Параметр «verificationReportOutputPath» указывает путь к месту сохранения файла отчета о проверке (.xml), сгенерированного программой. Если оставить это поле пустым или указать неверный путь, отчет о проверке сохраняется в заданной по умолчанию папке «Reports».

Если задан параметр «api.URL», Validator попытается отправить результаты проверки в конечную точку с указанным URL-адресом.

Для взаимодействия с Validator конечная точка обратного вызова должна соответствовать этому контракту веб-службы (YAML).

Запрос должен представлять собой объект в формате JSON со следующей структурой:

{ "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"

Ниже приводится пример объекта в формате JSON, который будет отправлен внешней конечной точке, направившей Validator вызов:

{ "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. Отчет

Отчет о проверке

WIPO Sequence генерирует отчеты о проверке в формате XML — и, в качестве опции, в формате HTML с использованием той же таблицы стилей, которая применяется в WIPO Sequence.На корневом уровне указаны следующие атрибуты:

• «applicationNumberText» — заявка, связанная с данным перечнем последовательностей;
• «productionDate» — дата проведения проверки;
• «filingDate» — дата подачи заявки;
• «softwareBuildVersion» — версия Validator, использованная для проверки;
• «softwareVersion» — версия WIPO Sequence, использованная для создания перечня последовательностей; и
• «sourceFileName» — имя XML-экземпляра перечня последовательностей.

Шаблон, или XSD, используемый для создания отчета о проверке, выглядит следующим образом:

<?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>

В следующей классификации представлена указываемая степень серьезности сообщений:

• «ERROR» — ошибка, выданная при проверке в режиме «FULL»
• «WARNING» — предупреждение, выданное при проверке в режиме «FULL»
• «XML_ERROR» — ошибка, выданная при проверке в режиме «FORMALITY»
• «XML_WARN» — предупреждение, выданное при проверке в режиме «FORMALITY»

После окончания проверки отчет о проверке генерируется в одном или обоих форматах и сохраняется по адресу, указанном в параметре «verificationReportOutputPath», по умолчанию это ./temp/st26/reports/[verificationID]/

Пример отчета о проверке в формате XML приводится в разделе «Ресурсы» ниже.

5. Конфигурация

Настройки по умолчанию

Настройки Validator задаются в файле конфигурации. Значения по умолчанию можно найти в файле the published application.yml.

Для того чтобы изменить значения параметров, следует использовать другой файл — «application.yml». Имеется несколько вариантов, которые подробно описаны в документации по Springboot.

Путь к файлу конфигурации и его имя можно задать в соответствующем параметре в командной строке при запуске программы:

• при внедрении программы в виде файла JAR:

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

• при внедрении программы в виде файла WAR на сервере Tomcat добавьте следующую запись к «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>

При внедрении программы в виде файла WAR можно также скопировать новый файл «application.yml» в папку «WEB-INF/classes» веб-приложения.

Вы можете включить или отключить создание отчетов в формате HTML в файле «application.yml». Для создания отчетов укажите значение «true», а для отключения данной функции используйте «false». Содержимое отчета отправляется конечной точке обратного вызова в поле «errorSummary» запроса «ServiceRequest».

Правило проверки «VXQV_49»

Значение «optionalEnglishQualifierValue» может быть установлено как «true», если пользователь хочет включить правило «VXQV_49», также пользователь может установить серьезность правила путем изменения значения «optionalRuleType» на «ERROR» или «WARNING».

Точка работоспособности «health»

В Validator имеется конечная точка «/health», которая предоставляет основную информацию о «здоровье» программы. Конечная точка «health» доступна по следующему URL-адресу: http://localhost:8080/wipo-sequence-validator/actuator/health.

Значение конечной точки должно быть следующим:

• Если работоспособность программы не нарушена, будет указан статус «UP».
• Если работоспособность программы нарушена из-за какого-либо сбоя, такого как отсутствие соединения с базой данных или недостаток свободного места на диске и др., будет указан статус «DOWN».

Конечная точка «health» показывает статус только в простом виде: «UP» или «DOWN». Следующий параметр в файле «application.yml» предоставляет информацию в полной мере, включая статус каждого индикатора работоспособности, проверенного в рамках процесса оценки работоспособности.

Конечная точка «health» теперь включает данные индикатора «DiskSpaceHealthIndicator», который запускается как часть процесса проверки работоспособности.

Конечная точка «health» будет отображаться следующим образом:

Локализованные сообщения

Validator может отображать локализованные сообщения, например в отчете о проверке, на каждом из десяти официальных языков PCT (английском, арабском, испанском, китайском, немецком, португальском, корейском, русском, французском и японском).

По умолчанию сообщения отображаются на английском языке. Для того чтобы Validator отображал эти сообщения на другом языке, укажите код соответствующего языка в параметре «validator_locale» в файле «application.yml».

Названия пользовательских организмов

Для того чтобы ведомства могли добавлять собственные названия пользовательских организмов, которые отсутствуют в предопределенном списке названий организмов, список пользовательских организмов можно задать путем создания нового файла с названием «custom_organism.json» в папке, указанной в параметре «alternativeResourceBasePath». Этот файл должен иметь следующую структуру:

Альтернативная версия DTD

По умолчанию WIPO Sequence Validator использует последнюю версию определения типа документа (DTD) стандарта ST.26. Текущая версия Validator основана на DTD версии 1.3 согласно стандарту ВОИС ST.26. Копия последней версии файла DTD стандарта ST.26 включена в библиотеку Validator, которая находится в папке «/src/main/resources» (этот путь к файлу задан в файле JAR или WAR). Файл DTD указывается в файле «catalog.xml», который находится в той же папке.

Во время проверки будет использоваться версия DTD, указанная в объявлении DOCTYPE в файле XML. Сначала по параметру «publicId» определяется, где находится файл DTD, который будет использоваться. Если «publicId» не указан в файле «catalog.xml», система попытается найти файл DTD в корневой папке, где выполняется процесс Java.

Для того чтобы иметь возможность проверять файлы стандарта ВОИС ST.26, которые ссылаются на более старую версию DTD стандарта ST.26, соответствующий файл DTD должен быть доступен Validator для выполнения проверки. Это можно обеспечить двумя способами:

1. Распакуйте файл JAR и поместите дополнительный или альтернативный файл DTD стандарта ST.26 в папку «src/main/resources». Внесите изменения в файл «catalog.xml» и добавьте новую запись для дополнительного файла DTD ST.26 или отредактируйте существующую запись. Например:

1. Вместо внесения изменений в файл JAR нужно выполнить следующее:
   (i) скопируйте файл «catalog.xml» и все файлы DTD в любую локальную папку;
   (ii) внесите изменения в файл «catalog.xml», добавив запись для дополнительного файла DTD стандарта ST.26; и
   (iii) установите следующий системный параметр Java при запуске: «xml.catalog.files=<path_to_catalog.xml>».

В Tomcat для Windows это можно сделать, добавив следующую переменную среды:

6. Ресурсы

Ведомствам ИС могут быть полезны следующие ресурсы:

• Пример отчета о проверке
• Полная спецификация API, YAML
• Названия свойств, JSON