WIPO Sequence Validator操作手册

1. 工作流程

该工具提供以下四个用例：

1. 验证WIPO ST.26文件。
2. 请求正在运行的验证的状态。
3. 更新配置文件（仅限知识产权局管理员）。
4. 当验证过程完成后，用验证过程的结果调用回调端点。

注：这个回调端点不在Validator的范围内。  由开发和设置这项服务的主管局来建立端点。

为验证WIPO ST.26 序列表，该工具使用位于文件夹结构中的 XML示例，运行验证过程并生成包含验证结果的验证报告。也可以选择通过调用回调端点返回此验证报告。

验证器的主要工作流程如下：

• 相应的知识产权局信息技术系统将XML文件保存在默认的“Inbox”文件夹或请求中指定的文件夹中。
• 知识产权局系统启动HTTP Post，请求对文件进行验证。根据配置情况，知识产权局系统可以请求对文件进行“full”或“formality”验证。 “formality”验证过程将检查ST.26文件是否为XML文件，并根据ST.26 DTD对文件进行验证。 “full”验证过程将比照业务验证规则对ST.26文件进行验证（验证规则来自ST.26的内容），并执行“formality”验证过程。 

注：建议“formality”验证过程仅针对在线申请使用，因为可以同步执行，而批量处理时建议使用“full”验证，因为会花费更长时间。 

• 验证完成后，将提供一条响应，说明文件是否通过了“formality”验证，并在知识产权局信息技术系统选择了“full”验证的情况下，另外说明业务规则验证是否已经正确启动。
• 如果验证器正在进行“full”验证，它将从“Inbox”文件夹中调取XML文件，并启动业务规则验证过程，然后进行以下操作：
• Validator在指定的“Output”文件夹中生成一个XML报告文件（“验证报告”），并将经过验证的WIPO ST.26 XML文件移至“Outbox”。
• 在业务规则验证过程完成后，如果配置了回调端点，则会从Validator中调用回调端点，并且请求中会填充与验证过程相关的附加信息。请求结构和一些样本数据在下文第2.2节提供。
• 回调端点应该在响应中返回一个空代码或成功代码（无错误）。[注：这一步只有在外部web服务可用且调用已在Validator中配置好的情况下才会执行。] Validator和回调端点之间也需要连接。 如上所述，外部web服务不构成Validator的一部分，应由各知识产权局根据下文定义的合约进行开发和配置。
• 知识产权局系统可以从“Report”文件夹中检索到验证报告。

2.部署

第1步：选择格式

如前所述，Validator以两种二进制格式之一提供：或者是可以作为Web服务执行的JAR文件，或者是可以部署在Tomcat服务器上的WAR文件。  根据主管局部署Validator时要采用的基础设施类型，知识产权局将从两种二进制格式中优先选择一种。

为Validator提供的两个二进制格式是：

• 二进制 SpringBoot JAR ：这种二进制是一个可执行的JAR文件。这需要安装 Java 17。
• War包二进制：这种二进制是为了在 Servlet容器上部署。需要与Spring Boot 3.1.0和Servlet Spec 4.0.1兼容的应用程序服务器，例如Tomcat 10。

以下各节将详细介绍将Validator部署为Spring Boot应用程序，或部署为Java应用程序服务器中的WAR。

• JAR形式的服务
• WAR形式的服务

Spring Boot JAR包含一个嵌入式服务器，它允许部署验证器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>

部署JAR文件后，可以通过 Swagger UI 访问 Validator API，其中知识产权局必须进行以下更改：[host-name] 必须替换为服务器主机名：

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

验证器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

验证器也可以作为由操作系统管理的服务来安装，以便支持其在操作系统启动时执行。 这种方式可用于为WIPO Sequence支持的所有平台——Windows、Linux和Mac OS——配置Spring Boot JAR文件。

以下指南详细介绍了如何为每个操作系统创建执行JAR文件的系统服务，还提供了关于如何配置这项服务的不同选项并执行应用程序的信息。

关于提供的第二种二进制，WAR包可以部署在现有的Java应用程序服务器中，如Apache Tomcat 8.5。[注：需要与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”

上文指出，验证器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

默认情况下，验证器将使用JVM默认内存设置。默认的堆大小上限是可用物理内存的四分之一。

为了修改堆大小上限，在使用命令行执行时必须使用“-Xmx”选项，如上文所述。

第 2 步：建立文件夹系统

Validator所用的文件系统结构由五个主要文件夹组成：

• “Inbox”文件夹：这是存储知识产权局提供用于验证的WIPO ST.26文件的本地文件夹。
• - “Process”文件夹：这是“Inbox”中的文件在处理过程中临时经过的本地文件夹。该文件夹包含两个子文件夹：
  • “Full validation”文件夹：存储有待全面验证的文件
  • “Formality validation”文件夹：存储有待形式验证的文件
• “Outbox”文件夹：验证完成后，应用程序将WIPO ST.26文件的源文件存储在该本地文件夹中。
• “Report”文件夹：这是将验证结果保存在验证报告文件中的本地文件夹。
• “Params”文件夹：这是一个本地文件夹，是带有验证请求中所有验证参数的JSON（.json）文件所在的位置，参数的目的是为异步深度验证过程提供参数。

文件系统结构示例如下：

步骤 3：测试

可以使用postman测试Validator服务，具体步骤如下：

• 打开postman应用程序，创建一个新的请求
• 添加请求体信息：
• 单击“发送”后，响应应如下所示：

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序列表的路径。如果主管局将此字段留空，该工具将尝试验证默认“Inbox”文件夹中以“nameFile”为文件名的XML文件。“nameFile”参数识别了要验证的序列表文件。

验证请求中的“verificationReportOutputPath”将提供该工具生成的验证报告（.xml）的文件位置。如果用户将该字段留空或引入一个无效的文件路径，验证报告将被存储在默认的“Reports”文件夹中。

如果配置了“api.URL”属性，验证器将尝试把验证结果发送到指明了URL的端点。

为了与Validator进行通信，回调端点必须符合此 Web 服务合约(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实例的示例，它将被发送到对验证器作出了调用的外部端点：

{ "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格式，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”验证时返回错误
• 警告——在“full”验证时返回警告
• XML_ERROR——在“FORMALITY”验证时返回错误
• XML_WARN——在“FORMALITY”验证时返回警告

验证后，以任何一种格式或两种格式生成的验证报告位于“verificationReportOutputPath”，默认路径是

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

下面的资源中提供了XML格式的验证报告示例。

5.配置

默认设置

Validator是通过使用一个属性文件来进行配置的。默认值可以在published application.yml 中找到。

要修改所提供的参数值，应使用另外的“application.yml”文件。在Springboot 文档中详细介绍了几个选项。

启动该工具时，可以通过在命令行建立参数来指定配置文件的路径和名称：

• 对于JAR部署：

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

• 对于Tomcat上的WAR部署，需要在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应用程序的“WEB-INF/classes”文件夹中。

在“application.yml 文件”中，可以启用或禁用生成HTML报告。值为“true”时启用报告生成，值为“false”时禁用报告生成。该报告的内容被发送到“ServiceRequest”的“errorSummary”字段中的回调端点。

验证规则VXQV_49

如果用户想要启用规则 VXQV_49，可以将optionalEnglishQualifierValue的值设置为true，并可以通过更新optionalRuleType的值为“ERROR”或“WARNING”来设置规则的严重级别。

健康端点

Validator有一个/health 端点，提供关于应用程序运行状况的基本信息。要了解健康端点，必须打开以下URL：

端点应显示以下内容：

• 只要应用程序运行良好，状态将为UP。
• 如果由于与数据库连接或磁盘空间不足等任何问题，导致应用程序运行不正常，则会显示DOWN。

健康端点仅显示简单的UP或DOWN状态。application.yml中文件的以下属性提供了完整详细信息，包括作为检查运行状况过程一部分而被检查的每个运行状况指标的状态。

健康端点现在包括作为运行状况检查过程一部分而运行的DiskSpaceHealthIndicator的详细信息。

健康端点将像这样显示：

本地化消息

Validator可以提供本地化消息，例如在验证报告中，可用PCT十种正式语言（阿拉伯文、德文、俄文、法文、韩文、葡萄牙文、日文、西班牙文、英文和中文）之一提供消息。

默认情况下，这些消息以英文提供。要将Validator配置为以其他语言提供消息，application.yml文件中的validator_locale参数必须设置为适当的语言代码。

自定义生物体名称

为便于主管局纳入各自的自定义生物体名称（这些名称不是原始预定义生物体名称列表的组成部分），可以通过在“alternativeResourceBasePath”文件夹中创建名为“custom_organism.json”的新文件，来提供自定义生物体列表。该文件应具备如下结构：

备选的DTD版本

Validator引用ST.26 DTD最新版本。WIPO Sequence Validator 的当前版本基于WIPO ST.26 DTD 1.3 版本。这版最新的ST.26 DTD包含在Validator库中，Validator库位于源代码的“/src/main/resources”文件夹（这是JAR或WAR文件中引用的已定义文件路径）。它在上述文件夹的“catalog.xml”文件中被引用。

在验证过程中，将使用XML文件的DOCTYPE声明中设置的DTD版本。首先，“publicId”将被用来识别要使用的DTD文件的位置。如果“publicId”不包含在目录中，系统将尝试在Java进程正在被执行的根文件夹中定位DTD文件。

为了能够验证引用旧版ST.26 DTD的WIPO ST.26文件，必须向验证器提供这个ST.26 DTD文件，以便进行适当的验证。 要实现这一目标，有两种可供选择的方法：

1. 解压JAR文件，并在“src/main/resources”文件夹中包含对附加的或其他的ST.26 DTD文件的引用。修改“catalog.xml”文件，为附加的ST.26 DTD添加新条目或编辑现有条目。 例如：

1. 无需修改JAR文件，但应遵循以下步骤：
   (i) 将“catalog.xml”和所有DTD复制到本地文件夹中；
   (ii) 修改“catalog.xml”，纳入对附加的ST.26 DTD的引用；并且
   (iii) 在启动时设置该Java 系统属性：“xml.catalog.files=<path_to_catalog.xml>”

在Tomcar for Windows中，可以通过添加以下环境变量来实现：

6. 资源

以下资源可能对知识产权局有用：

• 验证报告示例
• 完整的API规范，YAML
• 属性名称，JSON