WIPO Sequence Validator Operations Manual

1. Workflow

The tool provides the following four use cases:

1. Validation of an WIPO ST.26 file.
2. Request the status of a running validation.
3. Update configuration files (only the IPO Admin).
4. Call a callback endpoint with the result of the validation process once the validation process is completed.

Note: This callback endpoint is outside the scope of the Validator.  It is up to the Offices developing and setting up this service to establish the endpoint.

For the validation of the WIPO ST.26 sequence listing, the tool consumes XML instances located in a folder structure , runs a validation process and generates a verification report with validation results. Optionally, this verification report is returned by calling a callback endpoint.

The main workflow of the Validator is as follows:

• The respective IPO IT system saves an XML file in a default “Inbox” folder or the specified one within the request.
• The IPO system initiates a HTTP Post requesting the validation of the file. Depending on the configuration, the IPO system can request a “full” or a “formality” validation of the file.  The “formality” validation process will check whether the ST.26 file is an XML file and validates the file against the ST.26 DTD.  The “full” validation process will validate the ST.26 file against the business verification rules, derived from the content of ST.26 as well as conducting the “formality” validation process.  

Note: It is recommended to use the “formality” validation process for online filing  only as this can be performed synchronously while the “full” validation is recommended for batch processing as it will take much longer. 

• Once the validation is complete, a response will be provided indicating whether or not the file has passed the “formality” validation and additionally whether the business rule validation has started correctly in the instance where the IPO IT system has selected “full” validation.
• If the Validator is conducting a “full” validation, it retrieves the XML file from the “Inbox” folder and starts the business rule validation process, and then conducts the following:
• The Validator generates an XML report file (“Verification Report”) in a specified “Output” folder and moves the validated WIPO ST.26 XML file to an “Outbox”.
• After the business rule validation process has completed, the callback endpoint, if configured, is called from the Validator, and the request is populated with additional information related to the validation process. The structure of the request and some sample data is provided in section 2.2 below.
• The callback endpoint should either return an empty or a success code in the response (no errors). Note that this step is only executed if the external web service has been made available and the call has been configured in the Validator.  Connectivity between the Validator and the callback endpoint is also required.  As mentioned above, the external web service does not form part of the Validator and it should be developed and configured by Offices according to the contract defined below.
• The IPO system can retrieve the Verification Report from the “Report” folder.

2. Deployment

Step 1: Select format

As indicated previously, the Validator is provided as one of two binary formats: a JAR file that can be executed as a web service or a WAR file that can be deployed on a Tomcat server.  Depending on the type of infrastructure in which the Office wants to deploy the Validator, the IPO will have a preference for selecting one type of binary over the other.

The two binaries that the Validator are provided as are:

• Binary Spring Boot JAR: This binary is an executable JAR file. This requires Java 17 to be installed.
• War Package Binary: This binary is intended to be deployed on a Servlet container. An application server compatible with Spring Boot 3.1.0 and Servlet Spec 4.0.1 is required, such as Tomcat 10.

The following sections detail the deployment of the Validator as a Spring Boot app or as a WAR within a Java Application Server.

• Service as a JAR
• Service as a WAR

The Spring Boot JAR contains an embedded server, which allows the deployment of the Validator API without requiring a separate server. This greatly simplifies the configuration and deployment at the infrastructure level.

In order to run the embedded server, the following command should be executed where Java 17 is already installed on the server:

java -jar wipo-sequence-validator.jar

Since Java does not guarantee the use of UTF-8, the system property “file.encoding” must be set to “UTF-8”. By default the server will run on port 8080, to change the port the “--server.port” command line option should be added as shown below. This can be done by including the following:

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

The Validator API can be accessed through the Swagger UI after deploying the JAR file, where the IPO must make the following changes: [host-name] must be replaced by the server host name:

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

The Validator API is accessible in the following endpoints:

• GET Method: 

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

• POST Method: 

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

By default the Validator will use the Java Virtual Machine (JVM) default memory settings. The default maximum heap size is one fourth of the physical memory available. In order to modify the maximum heap size, the “-Xmx” option must be used when executing using the command line :

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

The Validator can also be installed as a service managed by the operating system to support its execution with the start-up of the operating system, for instance. It is possible to configure a Spring Boot JAR file in this manner for all platforms supported by WIPO Sequence: Windows, Linux and Mac OS.

The following guide provides detail how to create a system service that executes the JAR file for each operating system. It also provides information on how to configure the different options of the service and the execution of the application.

For the second type of binary provided, the WAR package can be deployed in an existing Java application server such as Apache Tomcat 10. Note, a container compatible with Servlet 4.0.1 is required.

The following instructions are for a Tomcat application server. Here,

$TOMCAT_ROOT

refers to the root folder of the Tomcat server, and this value should be replaced with the relevant value for the file path:

• Stop server:

  $TOMCAT_ROOT\bin\catalina.bat stop

• Copy .war file to

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

• Start server:

  $TOMCAT_ROOT\bin\catalina.bat start

Note: Since Java does not guarantee the use of UTF-8, the system property “file.encoding” must be set to “UTF-8” in the start-up of the application server. This can be done by including the following: -D"file.encoding=UTF-8"

The Validator API can be accessed through a Swagger UI, as indicated above:

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

The Validator API is accessible in the following endpoints, where [host-name] must be replaced by the server host name:

• GET Method:

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

• POST Method:

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

By default, the server will run on port 8080. To change this over to another port the Tomcat configuration file should be modified by following the instructions provided here:

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

By default, the Validator will use the JVM default memory settings. The default maximum heap size is one fourth of the physical memory available.

In order to modify the maximum heap size, the “-Xmx” option must be used when executing using the command line, as indicated above

Step 2: Establish folder system

The structure of the file system used by the Validator consists of five main folders:

• "Inbox” folder: This is the local folder where WIPO ST.26 files are provided by an IPO for validation.
• "Process" folder: This is the local folder through which the files in the “Inbox” temporarily pass during processing. This folder contains two subfolders
  • "Full validation" folder: Stores the files pending a full validation.
  • "Formality validation" folder: Stores the files pending a formality validation.
• "Outbox" folder: Once the validation is complete, the application stores the source of the WIPO ST.26 file in this local folder.
• "Report" folder: This is the local folder where the results of the validation are saved in a verification report file.
• "Params" folder: This the local folder where a JSON (.json) file with all the validation parameters from the validation request are located in order to provide parameters for the asynchronous deep validation process.

An example file system structure is provided below:

Step 3: Testing

Testing for the Validator service can be done using postman, by using the following steps:

• Open the postman application and create a new request
• Add the request body information:
• After clicking on "Send", the response should be like this:

3. Request

Callback endpoint request

WIPO Sequence Validator, after the conclusion of the validation request, will generate a JSON file which includes the necessary parameters for a request to a callback endpoint. The request should include the following parameters, detailing the file locations and the validation process:

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

The “seqlInputLocation” field of the validation request should be set to indicate the path of the XML sequence listing to be validated. If the Office leaves this field empty, the tool will try to validate the XML file with the filename “nameFile” located at the default “Inbox” folder. The “nameFile” parameter identifies the sequence listing file to be validated.

The “verificationReportOutputPath” within the request will provide the file location of the verification report (.xml) generated by the tool. If the user leaves the field in blank or introduces an invalid file path, the verification report will be stored in the default “Reports” folder.

If the property “api.URL” is configured, the Validator will try to send the results of the validation to an endpoint with the URL specified.

In order to communicate with the Validator, the callback endpoint must comply with this web service contract (YAML)

Furthermore, the request should be a JSON object with this structure:

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

This is an example JSON object that will be sent to the external endpoint which made the call to the 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. Report

Verification report

The verification report generated by WIPO Sequence is in XML format, and optionally HTML format using the same stylesheet that is used in WIPO Sequence.The attributes indicated at the root level are as follows:

• "applicationNumberText": the application associated with this sequence listing
• "productionDate": the date that the validation was conducted
• "filingDate": the date of filing of the application
• "softwareBuildVersion": the version of the Validator used for validation
• "softwareVersion": the version of WIPO Sequence used to generate the sequence listing
• "sourceFileName": the name of the sequence listing XML instance

The template, or XSD, used to produce the verification report is as follows:

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

Interms of the severity indicated, please note the following categorization:

• ERROR - an error returned during the 'FULL' check
• WARNING - a warning returned during the 'FULL' check
• XML_ERROR - an error returned during the 'FORMALITY' check
• XML_WARN - a warning returned during the 'FORMALITY' check

After validation, the verification report generated in either or both formats is lcoated at the "verificationReportOutputPath", which by default is at

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

An example of the verification report in XML format is provided in the Resources below.

5. Configuration

Default settings

The Validator is configured by using a properties file. The default values can be found in the published application.yml file

In order to modify the value of the parameters provided, an alternative “application.yml” file should be used. There are several options as detailed in the Spring boot documentation

The path and name of the configuration file can be specified by establishing the parameter on the command line when starting the tool:

• For a JAR deployment:

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

• For a WAR deployment on Tomcat, the following entry to CATALINA_OPTS should be added:
  • Windows:

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

  • Linux:

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

When using the WAR deployment, the new “application.yml” file can also be copied into the “WEB-INF/classes” folder of the web application.

In the “application.yml file”, you can enable or disable HTML report generation. A value of "true" to enable report generation and a value of "false" to disable it. The content of this report is sent to the callback endpoint within the "errorSummary" field of the “ServiceRequest”.

Verification rule VXQV_49

The "optionalEnglishQualifierValue" value can be set to true if the user wants to enable the rule VXQV_49, and can set the rule’s severity by updating "optionalRuleType" value to 'ERROR' or 'WARNING'.

Healthpoint

The validator has a "/health" endpoint that provides basic information about the application’s health. To explore the health endpoint, one must open the following URL:

The endpoint should display the following:

• The status will be UP as long as the application is healthy.
• It will show DOWN if the application gets unhealthy due to any issue like connectivity with the database or lack of disk space etc.

The health endpoint only shows a simple UP or DOWN status. The following property in the application.yml file provides the complete details including the status of every health indicator that was checked as part of the health check-up process.

The health endpoint now includes the details of the "DiskSpaceHealthIndicator" which is run as part of the health checkup process.

The health endpoint will display like this

Localized messages

The Validator can provide a localized message, for instance in the Verification Report, in each of the official ten PCT languages (Arabic, Chinese, English, French, German, Portuguese, Japanese, Korean, Russian, and Spanish).

By default, these messages are provided in English. In order to configure the Validator to provide these messages in other language, the validator_locale parameter of the application.yml file must be set to the appropriate language code.

Custom organism names

In order for Offices to include their own custom organism names, which do not form part of the original pre-defined list of organism names, a list of custom organisms can be provided by creating a new file, called "custom_organism.json", in the "alternativeResourceBasePath" folder. This file should have the following structure:

Alternative DTD version

By default, the Validator references the latest version of ST.26 DTD. The current version of WIPO Sequence Validator is based on version 1.3 of WIPO ST.26 DTD . This copy of the latest version of the ST.26 DTD is included in the Validator library located in the “/src/main/resources” folder of the source code (this is the defined file path referenced within the JAR or WAR file). It is referenced in the “catalog.xml” file in the same folder

During validation, the version of the DTD set in the DOCTYPE declaration of the XML file will be used. Firstly, the “publicId” will be used to identify the location of the DTD file to be used. If the “publicId” is not included in the catalog, the system will try to locate the DTD file in the root folder where the Java process is being executed.

In order to be able to validate WIPO ST.26 files that reference an older version of the ST.26 DTD, this ST.26 DTD file must be made available to the Validator to allow the appropriate validation. In order to achieve this, there are two alternative approaches:

1. Uncompress the JAR file and include a reference to the additional or alternative ST.26 DTD file in the “src/main/resources” folder. Modify the “catalog.xml” file and add a new entry for the additional ST.26 DTD or edit the existing one. For example:

2. Instead of modifying the JAR file, the following steps should be followed:
(i) Copy “catalog.xml” and all the DTDs into a local folder;
(ii) Modify “catalog.xml” to include a reference to the additional ST.26 DTD; and
(iii) Set this Java system property on launch: “xml.catalog.files=<path_to_catalog.xml>”

In Tomcat for Windows, this can be done by adding the following environment variable:

6. Resources

The following resources may be useful to IP Offices

• Example verification report
• Complete API specification, YAML
• Property Names, JSON