Manual de Utilização de WIPO Sequence Validator

1. Fluxo de trabalho

A ferramenta disponibiliza os quatros casos de uso seguintes:

1. Validação de um arquivo no formato ST.26 da OMPI.
2. Solicitação do status de uma validação em curso.
3. Atualização de arquivos de configuração (somente o administrador do IPI).
4. Chame um ponto final de chamada de retorno com o resultado do processo de validação assim que o processo de validação for concluído.

Nota: este ponto final de chamada de retorno está fora do escopo do Validator.  Cabe aos Institutos que desenvolvem e instalam este serviço estabelecer o ponto final de chamada.

Para validar uma listagem de sequências no formato ST.26 da OMPI, a ferramenta consome instâncias localizadas em um sistema de pastas, executa um processo de validação e gera um relatório de verificação contendo os resultados da validação. Opcionalmente, retorna este relatório de verificação, chamando um ponto final de chamada de retorno ("callback endpoint").

O principal fluxo de trabalho do Validator é o seguinte:

• O sistema de TI do IPI respectivo salva um arquivo XML numa pasta de caixa de entrada ("Inbox") predefinida ou na pasta especificada na solicitação.
• O sistema do IPI inicia uma postagem por HTTP solicitando a validação do arquivo. Dependendo da configuração, o sistema do IPI pode solicitar uma validação "completa" ("full") ou uma validação "formal" ("formality") do arquivo.  O processo de validação "formal" do arquivo verifica se o arquivo no formato ST.26 é um arquivo XML e valida o arquivo com relação ao DTD ST.26.  O processo de validação "completa" valida o arquivo no formato ST.26 com relação às regras de verificação de negócios derivadas do conteúdo da norma ST.26, além de conduzir o processo de validação "formal".  

Nota: Recomenda-se o uso do processo de validação "formal" apenas para depósitos online, já que este processo pode ser executado de forma síncrona, enquanto que a validação "completa" é recomendada para o processamento em lotes, já que demora muito mais tempo. 

• Uma vez a validação concluída, uma resposta é fornecida indicando se a validação "formal" do arquivo foi bem-sucedida ou não e, além disso, no caso em que o sistema de TI do IPI selecionou a validação completa, se a validação com relação às regras de verificação de negócios foi iniciada corretamente.
• Se o Validator estiver realizando uma validação "completa", recupera o arquivo XML na pasta de caixa de entrada ("Inbox"), inicia o processo de validação das regras de negócios, e executa as etapas seguintes:
• O Validator gera um arquivo XML contendo um relatório ("Verification Report") numa pasta de saída ("Output") especificada e move o arquivo XML validado no formato ST.26 da OMPI para uma caixa de saída ("Outbox").
• Após a conclusão do processo de validação com relação às regras de negócios, o ponto final, se configurado, é chamado de volta pelo Validator e a solicitação é povoada com informações adicionais relacionadas com o processo de validação. A estrutura da solicitação e alguns dados de amostra são dados na seção 2.2 abaixo.
• O ponto final da chamada de retorno ("callback endpoint") deve retornar um código vazio ou um código de êxito na resposta (nenhum erro). [Nota: Esta etapa é executada somente se o serviço web externo foi disponibilizado e se a chamada foi configurada no Validator.]  A conectividade entre o Validator e o ponto final de chamada de retorno também é necessária.  Como mencionado acima, o serviço web externo não faz parte do Validator e deve ser desenvolvido e configurado pelos Institutos de acordo com o contrato definido abaixo.
• O sistema do IPI pode recuperar o relatório de verificação na pasta dos relatórios ("report").

2. Implantação

Etapa 1: Selecionar o formato

Como indicado anteriormente, o Validator é fornecido em um dos dois formatos binários seguintes: um arquivo JAR que pode ser executado como um serviço web ou um arquivo WAR que pode ser implantado num servidor Tomcat.  Dependendo do tipo de infraestrutura em que o Instituto deseja implantar o Validator, o IPI pode selecionar um ou outro tipo de binário, segundo sua preferência.

Os dois formatos binários nos quais o Validator é fornecido são:

• Pacote binário SpringBoot JAR: Esse é um arquivo binário JAR executável. Requer que Java 17 seja instalado.
• Pacote binário WAR: Esse arquivo binário destina-se a ser implantado num recipiente de servlet. Um servidor de aplicativos compatível com Spring Boot 3.1.0 e Servlet Spec 4.0.1 é necessário, tal como Tomcat 10.

As seções seguintes detalham a implantação do Validator como um aplicativo Spring Boot ou como um arquivo WAR em um servidor de aplicativos Java.

• Serviço como um JAR
• Serviço como um WAR

O arquivo Spring Boot JAR contém um servidor incorporado, o que permite implantar o API do Validator sem necessitar um servidor separado. Isto simplifica muito a configuração e a implantação no nível da infraestrutura.

Para executar o servidor incorporado, o comando seguinte deve ser executado quando Java 17 já está instalado no servidor:

java -jar wipo-sequence-validator.jar

Como Java não garante o uso de UTF-8, a propriedade "file.encoding" do sistema deve ser definida como "UTF-8". Por definição, o servidor será executado na porta 8080; para modificar a porta, a linha de comando opcional "--server.port" deve ser adicionada, como indicado abaixo. Isso pode ser feito incluindo o seguinte:

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

É possível acessar a API do Validator através de Swagger UI , depois de implantar o arquivo JAR; para isso o IPI deve efetuar as alterações seguintes: [host-name] deve ser substituído pelo nome do servidor host:

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

A API Validator está acessível nos seguintes pontos finais:

• Método GET: 

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

• Método POST: 

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

Por predefinição, o Validator usará as configurações predefinidas da memória da Máquina Virtual Java (JVM). A área dinâmica para dados tem um tamanho máximo predefinido igual a um quarto da memória física disponível. Para modificar o tamanho máximo da área dinâmica de dados, é preciso usar a opção "-Xmx" quando executando por meio da linha de comando:

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

O Validator também pode ser instalado como um serviço gerenciado pelo sistema operacional para permitir sua execução como parte da inicialização do sistema operacional, por exemplo. É possível configurar um arquivo Spring Boot JAR desta maneira para todas as plataformas compatíveis com WIPO Sequence: Windows, Linux e Mac OS.

O guia seguinte explica detalhadamente como criar um serviço de sistema que executa o arquivo JAR para cada sistema operacional. Também fornece informações sobre como configurar as diferentes opções do serviço e a execução do aplicativo.

No caso do segundo tipo de arquivo binário fornecido, o pacote WAR pode ser implantado em um servidor existente de aplicativos Java, tal como Apache Tomcat 10. Nota: Um recipiente compatível com Servlet 4.0.1 é necessário.

As instruções a seguir são para um servidor de aplicativos Tomcat. Aqui,

$TOMCAT_ROOT

refere-se à pasta raíz do servidor Tomcat e este valor deve ser substituído pelo valor relevante para o caminho do arquivo:

• Parar o servidor:

  $TOMCAT_ROOT\bin\catalina.bat stop

• Copiar o arquivo WAR para

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

• Iniciar o servidor:

  $TOMCAT_ROOT\bin\catalina.bat start

Nota: Como Java não garante o uso de UTF-8, a propriedade "file.encoding" do sistema deve ser definida como "UTF-8" durante a inicialização do servidor de aplicativos. Isso pode ser feito incluindo o seguinte: -D"file.encoding=UTF-8"

A API Validator pode ser acessada por meio de uma interface de usuário Swagger, como indicado acima:

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

A API do Validator pode ser acessada nos pontos finais seguintes, onde [host-name] deve ser substituído pelo nome do servidor host:

• Método GET:

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

• Método POST:

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

Por predefinição, o servidor funciona pela porta 8080. Para transferir para outra porta, o arquivo de configuração de Tomcat deve ser modificado seguindo as instruções fornecidas aqui:

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

Por predefinição, o Validator usará as configurações predefinidas da memória da Máquina Virtual Java (JVM). A área dinâmica para dados tem um tamanho máximo predefinido igual a um quarto da memória física disponível.

Para modificar o tamanho máximo da área dinâmica de dados, deve-se usar a opção "-Xmx" quando executando por meio da linha de comando, como indicado acima.

Etapa 2: Estabelecer o sistema de pastas

A estrutura do sistema de arquivos utilizado pelo Validator consiste em cinco pastas principais:

• Pasta de caixa de entrada ("Inbox"): É a pasta local onde os arquivos no formato ST.26 da OMPI são colocados por um IPI para validação.
• Pasta de processamento ("Process"): É a pasta local pela qual passam temporariamente os arquivos na caixa de entrada ("Inbox") durante o processamento. Esta pasta contém duas subpastas:
  • Pasta de validação completa ("Full validation"): onde são armazenados os arquivos aguardando uma validação completa
  • Pasta de validação formal ("Formality validation"): onde são armazenados os arquivos aguardando uma validação formal
• Pasta de caixa de saída ("Outbox"): Uma vez concluída a validação, o aplicativo armazena a fonte do arquivo no formato ST.26 da OMPI nesta pasta local.
• Pasta de relatórios ("Report"): É a pasta local onde são salvos os resultados da validação em um arquivo de relatório de verificação.
• Pasta de parâmetros ("Params"): É a pasta local onde um arquivo JSON (.json) com todos os parâmetros de validação contidos na solicitação de validação estão localizados para fornecer os parâmetros do processo assíncrono de validação profunda.

Abaixo é dado um exemplo de estrutura de um sistema de arquivos:

Etapa 3: Teste

É possível testar o serviço do Validator por meio de postman, através das etapas seguintes:

• Abrir o aplicativo postman e criar uma nova solicitação
• Adicionar as informações na parte principal da solicitação:
• A resposta, depois de clicar em "Send" (enviar), deve ser a seguinte:

3. Solicitação

Solicitação pelo ponto final de chamada de retorno

Após a conclusão da solicitação de validação, WIPO Sequence Validator gera um arquivo JSON incluindo os parâmetros necessários para uma solicitação a um ponto final de chamada de retorno. A solicitação deve incluir os parâmetros seguintes que detalham as localizações dos arquivos e o processo de validação:

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

O campo “seqlInputLocation” da solicitação de validação deve ser definido para indicar o caminho até a listagem de sequências XML a ser validada. Se o Instituto deixar este campo em branco, a ferramenta tentará validar o arquivo XML com o nome de arquivo "nameFile" localizado na pasta predefinida de caixa de entrada ("Inbox"). O parâmetro "nameFile" identifica o arquivo contendo a listagem de sequências a ser validada.

O parâmetro “verificationReportOutputPath” na solicitação fornece a localização do arquivo do relatório de verificação (.xml) gerado pela ferramenta. Se o usuário deixar o campo em branco ou introduzir um caminho de arquivo inválido, o relatório de verificação será armazenado na pasta predefinida de relatórios, "Reports".

Se a propriedade "api.URL" estiver configurada, o Validator tentará enviar os resultados da validação para um ponto final tendo o URL especificado.

Para comunicar com o Validator, o ponto final de chamada de retorno deve estar em conformidade com este contrato de serviços web (YAML).

Além disso, a solicitação deve ser um objeto JSON tendo esta estrutura:

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

Este é um exemplo de instância JSON que será transmitido ao ponto final externo que chamou o 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. Relatório

Relatório de verificação

O relatório de verificação gerado por WIPO Sequence está no formato XML, e opcionalmente no formato HTML utilizando a mesma folha de estilo utilizada em WIPO Sequence. Os atributos indicados no nível raíz são os seguintes:

• "applicationNumberText": o pedido associado com essa listagem de sequências
• "productionDate": data em que a validação foi realizada
• "filingDate": data de depósito do pedido
• "softwareBuildVersion": versão do Validator utilizada para a validação
• "softwareVersion": versão de WIPO Sequence utilizada para gerar a listagem de sequências
• "sourceFileName": nome da instância XML da listagem de sequências

O modelo, ou XSD, utilizado para produzir o relatório de verificação é o seguinte:

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

No que diz respeito ao grau de severidade indicado, observe as categorias seguintes:

• ERROR - um erro retornado durante a verificação completa ("full")
• WARNING - um aviso retornado durante a verificação completa ("full")
• XML_ERROR - um erro retornado durante a verificação formal ("formality")
• XML_WARN - um aviso retornado durante a verificação formal ("formality")

Após a validação, o relatório de verificação gerado em um ou em ambos os formatos está localizado na "verificationReportOutputPath", predefinida em

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

Um exemplo do relatório de verificação em formato XML está fornecido nos Recursos abaixo.

5. Configuração

Configurações predefinidas

Um arquivo de propriedades é utilizado para configurar o Validator. Os valores predefinidos se encontram no *application.yml* publicado.

Para modificar o valor dos parâmetros fornecidos, um arquivo "application.yml" alternativo deve ser utilizado. Existem várias opções, conforme detalhado na documentação do SpringBoot.

O caminho e o nome do arquivo de configuração podem ser especificados estabelecendo o parâmetro na linha de comando ao iniciar a ferramenta:

• No caso da implantação de um arquivo JAR:

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

• No caso da implantação de um arquivo WAR em Tomcat, a seguinte entrada deve ser adicionada a 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>

Ao usar a implantação de WAR, o novo arquivo "application.yml" pode também ser copiado para a pasta “WEB-INF/classes” do aplicativo web.

No arquivo "application.yml", você pode ativar ou desativar a geração de relatórios HTML. O valor "true" ativa a geração de relatórios e o valor "false" a desativa. O conteúdo do relatório é enviado ao ponto final de chamada de retorno dentro do campo "error Summary" de "ServiceRequest".

Regra de verificação VXQV_49

Se o usuário deseja ativar a regra VXQV_49, pode definir o valor "optionalEnglishQualifierValue" como "true" e pode definir a severidade da regra atualizando o valor "optionalRuleType" para "ERROR" ou "WARNING".

Healthpoint

O Validator implementa um "/health endpoint" que fornece informações de base sobre o estado de funcionamento do aplicativo. Para explorar o "health endpoint", é preciso consultar o URL seguinte:

O ponto final deve apresentar o seguinte:

• O status será "UP" enquanto o estado de funcionamento do aplicativo for bom.
• Será "DOWN" se o aplicativo não estiver funcionando bem devido a algum problema, tais como conectividade com a base de dados ou falta de espaço no disco, etc.

O "health endpoint" indica apenas um simples status "UP" ou "DOWN". A propriedade a seguir no arquivo "application.yml" fornece os detalhes completos, incluindo o status de cada indicador do estado de funcionamento verificado como parte do processo de verificação do estado de funcionamento.

O "health endpoint" agora inclui os detalhes do “DiskSpaceHealthIndicator” que é executado como parte do processo de verificação do estado de funcionamento.

O "health endpoint" se apresenta como a seguir

Mensagens localizadas

O Validator pode fornecer uma mensagem localizada, por exemplo no relatório de verificação, em cada uma das dez línguas oficiais do PCT (árabe, chinês, inglês, francês, alemão, português, japonês, coreano, russo e espanhol).

Por predefinição, essas mensagens são fornecidas em inglês. A fim de configurar o Validator para que forneça essas mensagens em outra língua, o parâmetro "validator_locale" do arquivo "application.yml" deve ser definido com o código da língua apropriado.

Nomes de organismos personalizados

Os Institutos podem incluir seus próprios nomes de organismos personalizados numa lista de organismos personalizados que não fazem parte da lista original predefinida de nomes de organismos, criando um novo arquivo, chamado “custom_organism.json”, na pasta “alternativeResourceBasePath”. Este arquivo deve ter a estrutura seguinte:

Versão alternativa de DTD

Por definição, Validator referencia a versão mais recente do DTD da norma ST.26. A versão atual de WIPO Sequence Validator está baseada na versão 1.3 do DTD da norma ST.26 da OMPI. Esta cópia da versão mais recente do DTD ST.26 está incluída na biblioteca do Validator localizada na pasta “/src/main/resources” do código fonte (é o caminho de arquivo definido e referenciado no arquivo JAR ou WAR). Está referenciado no arquivo "catalog.xml" na mesma pasta.

Durante a validação, a versão do DTD definida na declaração DOCTYPE do arquivo XML será usada. Primeiramente, o "publicId" será usado para identificar a localização do arquivo DTD a ser usado. Se "publicId" não estiver incluído no catálogo, o sistema tentará localizar o arquivo DTD na pasta raíz onde o processo Java está sendo executado.

Para poder validar arquivos no formato ST.26 da OMPI que referenciam uma versão mais antiga do DTD ST.26, este arquivo DTD ST.26 deve ser posto à disposição do Validator para possibilitar a validação apropriada. Para isto, há dois caminhos alternativos:

1. Descompactar o arquivo JAR e incluir uma referência ao arquivo DTD ST.26 adicional ou alternativo na pasta "scr/main/resources". Modificar o arquivo "catalog.xml" e adicionar uma nova entrada para o arquivo DTD ST.26 adicional ou editar o arquivo existente. Por exemplo:

1. Em vez de modificar o arquivo JAR, é preciso seguir as etapas seguintes:
   (i) Copiar "catalog.xml" e todos os DTDs para uma pasta local;
   (ii) Modificar "catalog.xml" de modo a incluir uma referência ao DTD ST.26 adicional; e
   (iii) Definitir esta propriedade do sistema Java logo do lançamento: “xml.catalog.files=<path_to_catalog.xml>”

Em Tomcat para Windows, isto pode ser feito adicionando a variável de ambiente seguinte:

6. Recursos

Os recursos seguintes podem ser úteis para os Institutos de PI:

• Exemplo de relatório de verificação
• Especificação completa da API, YAML
• Nomes de propriedades, JSON