Tempo aproximado para leitura: 00:40:00
Dúvida
Como atualizar o Patch e-Forms NDD para clientes com servidores In Loco, seguindo o modelo de implementação do CNPJ alfanumérico?
1. Objetivo / Problema
Este documento tem como objetivo orientar usuários finais, analistas de suporte e equipes técnicas na implementação da Fase 1 do projeto Alfanumérico, abrangendo as principais etapas de execução, parametrização da API de Certificados, equalização de dados legados e a resolução de inconsistências mapeadas durante o processo de homologação. Recomenda-se que o procedimento seja executado pelos responsáveis da TI e infraestrutura do ambiente local.
2. Ambiente
- Produto: Plataforma NDD e-Forms & NDD e-Connector
- Cenário de Aplicação: Ambientes Inloco NDD
-
Escopo de Versões: Patch e-Forms 98176 ou versões superiores (Recomendação mínima versão 98176)
3. Resolução / Procedimento Operacional
Passo 3.1: Ações Obrigatórias Pré-Atualização
Antes de iniciar a extração ou execução de qualquer arquivo/instalador, realize impreterivelmente as seguintes validações de infraestrutura:
- Backup: Execute o backup completo e estrutural do banco de dados operacional;
- Espaço e permissões: Valide se há espaço em disco suficiente e certifique-se de que o usuário executor possui privilégios administrativos completos (Administrador Local) no servidor.
- Componentes Core (Obrigatórios): Realize o download e a instalação prévia dos seguintes pacotes no servidor de aplicação:
dotnet-hosting-6.0.36-win
dotnet-sdk-6.0.428-win-x64
Para backup do diretório forms NDD e inetpub, seguir conforme abaixo:
Acesse o servidor onde o NDD está instalado e faça o backup da pasta eForms, criando uma cópia dela:
📂 Caminho: C:\Program Files\NDDigital
- Realize também o backup da pasta inetpub, ainda no servidor NDD, criando uma cópia dela:
📂 Caminho: C:\inetpub
Passo 3.2: Execução do Patch e Atualização do Banco de Dados
Após baixar os instaladores disponibilizados através do Release Notes no portal NDD Space, siga o passo a passo de execução abaixo:
Patch NDD e-Forms 4850 versão 98176
Navegue até o arquivo do patch baixado, clique com o botão direito, acesse a aba Propriedades e selecione a opção Desbloquear antes de realizar a extração.
Execute o instalador com privilégios de administrador:
Durante a evolução da barra de progresso, prompts de comando (CMD) serão disparados automaticamente pelo sistema para realizar a pausa e reinício automático dos serviços vinculados a NDD:
Os scripts de criação do banco de dados de Certificados são executados a partir da versão 98176 quanto nas versões posteriores. Abaixo, é apresentado um exemplo da mensagem exibida durante a execução do patch 98182, aplicado após a versão 98176. Nesse cenário, as mensagens de erro ocorrem porque algumas tabelas já haviam sido criadas anteriormente. Trata-se de um comportamento esperado, que não causa impacto no funcionamento da aplicação:
Prosseguindo com a atualização, a tela de conclusão será esta:
Passo 3.3: Configuração da API de Certificados
Documento de apoio - APICertificado.pdf - Google Drive
Com o patch instalado, é mandatório realizar o apontamento de comunicação entre o ecossistema e o barramento de certificados corporativos através das etapas abaixo:
Navegue até o diretório físico padrão da API:
C:\inetpub\wwwroot\eForms\Webs\ApiClientCertificado
Abra o arquivo appsettings.json utilizando um editor de texto estruturado:
Configure a string de conexão (Connection String) correspondente ao seu fornecedor de banco de dados (SQL Server, Oracle ou Informix) respeitando a sintaxe JSON:
Exemplo de como fica no banco de dados após a criação dos novos objetos:
Acesse o menu do Connector Settings e siga o caminho: Configurações Gerais > Certificados:
Insira a URL padrão da API: http://localhost:8120
Passo 3.4: Equalização de Dados Legados (Ferramenta Alfanumérica)
Alpha Base Normalize.pdf - Google Drive
A ferramenta Alpha Base Normalize foi desenvolvida especificamente para realizar o preenchimento retroativo das colunas recém-criadas com base nas informações históricas já presentes no ambiente. Para mitigar riscos de conexão.
Passo 4: Conclusão
A implementação da Fase 1 do Alfanumérico representa uma etapa importante na evolução da plataforma, proporcionando maior compatibilidade com os novos formatos de identificação fiscal, melhor desempenho operacional e mais consistência no armazenamento das informações.
Embora a atualização seja executada de forma automatizada por meio dos patches disponibilizados, o êxito da implantação depende diretamente da correta execução das etapas de validação, da configuração adequada da API de Certificados e da equalização dos dados legados.
Durante os testes e implantações realizados, foram identificados pontos de atenção relacionados principalmente à configuração do arquivo appsettings.json, à necessidade de reinicialização do servidor após a instalação dos componentes .NET e à validação dos parâmetros utilizados na ferramenta de equalização. Esses cenários não representam falhas da solução, mas exigem atenção durante o processo de implantação.
Recomenda-se que toda atualização siga rigorosamente as etapas descritas neste manual, incluindo:
- Validação dos pré-requisitos;
- Aplicação do patch;
- Configuração da API de Certificados;
- Verificação do acesso ao Swagger e à porta 8120;
- Execução da ferramenta de equalização;
- Validação dos documentos processados;
- Conferência dos logs e monitoramentos do ambiente.
Antes da liberação do ambiente para uso, é fundamental garantir que todas as validações tenham sido concluídas com sucesso e que não existam registros pendentes ou inconsistências decorrentes da migração.
Seguindo as orientações apresentadas neste documento, a atualização poderá ser realizada com maior segurança, previsibilidade e confiabilidade, reduzindo riscos operacionais e assegurando a integridade dos dados processados pelo ambiente.
FAQ – Problemas Comuns na Implementação Alfanumérica
1. API não inicializava mesmo com .NET instalado corretamente
Cenário
Após a conclusão da aplicação do Patch 98176 e instalação dos componentes obrigatórios:
- dotnet-hosting-6.0.36-win
- dotnet-sdk-6.0.428-win-x64
a API não inicializava corretamente após a instalação.
Os seguintes sintomas foram observados:
- impossibilidade de acessar o Swagger;
- acesso indisponível na URL:
http://localhost:8120
- retorno de erros de inicialização da aplicação.
Solução Aplicada
Mesmo com todas as versões corretas instaladas, foi necessário realizar o reinício completo do servidor Windows.
Após o reboot:
- a API iniciou normalmente;
- o Swagger ficou acessível;
- a comunicação foi estabelecida com sucesso.
Recomendação
Sempre que:
- o patch for aplicado com sucesso;
- o .NET estiver corretamente instalado;
- a API não iniciar;
nessa situação, recomenda-se reiniciar o servidor antes de avançar para análises mais aprofundadas.
2. Problemas de Formatação no appsettings.json
Outro ponto identificado durante a implantação esteve relacionado ao preenchimento incorreto do arquivo abaixo:
C:\inetpub\wwwroot\eForms\Webs\ApiClientCertificado\appsettings.json
Sintomas
- API não inicia;
- Swagger indisponível;
- erro HTTP 500.30;
- falha de comunicação com o banco.
Causa
A estrutura JSON exige formatação rigorosa.
Pequenos erros podem impedir a inicialização da API, como:
- aspas incorretas;
- vírgulas ausentes;
- fechamento incorreto de chaves;
- erro na Connection String;
- erro de sintaxe JSON.
Solução
Após a correção da estrutura do arquivo:
- a API voltou a responder normalmente;
- a comunicação foi restabelecida.
Recomendação
Antes de investigar problemas de .NET ou IIS, valide cuidadosamente a estrutura completa do arquivo appsettings.json.
3. Mensagens de Erro Durante a Instalação do Patch 98182
Cenário
Ao instalar o Patch 98182 em um ambiente que já havia recebido previamente o Patch 98176, foram apresentadas mensagens de erro relacionadas à execução de scripts no banco de dados.
Causa
O ambiente já possuía parte das estruturas criadas anteriormente.
Dessa forma:
- tabelas;
- colunas;
- ajustes de banco;
já estavam presentes no ambiente.
Conclusão
Neste cenário, as mensagens não representavam falha da atualização.
Tratava-se apenas de tentativas de criação de estruturas que já existiam.
Recomendação
Ao analisar erros apresentados no Patch 98182, valide primeiro se a estrutura já havia sido criada por atualizações anteriores antes de tratar a situação como falha efetiva.
4. Validação das Informações da Ferramenta de Migração
Durante a execução da ferramenta de validação da migração alfanumérica, é fundamental conferir os parâmetros de conexão com o banco de dados.
Boas práticas
Utilizar as mesmas informações configuradas no Connector Settings:
- servidor;
- banco;
- usuário;
- senha;
- porta de comunicação.
Benefício
Isso reduz significativamente erros de autenticação e falhas de conexão durante a análise da migração.
Recomendação
Antes de iniciar a análise:
- Abrir o Connector Settings;
- Validar os dados de conexão;
- Replicar exatamente os mesmos parâmetros na ferramenta de validação.
Essa prática contribui para maior confiabilidade nos resultados obtidos durante a validação.
Resumo geral das Recomendações
✔ Validar instalação do .NET
✔ Reiniciar o servidor após a instalação do Patch 98176 ou superior
✔ Revisar cuidadosamente o appsettings.json
✔ Validar a sintaxe da Connection String
✔ Não tratar automaticamente erros do Patch 98182 como falhas críticas
✔ Utilizar os dados do Connector Settings na ferramenta de migração
✔ Executar a ferramenta de validação após toda atualização
✔ Confirmar acesso ao Swagger antes de liberar o ambiente
Em caso de dúvidas ou qualquer dificuldade, recomendamos o acionamento a equipe de suporte TOTVS por meio dos nosso canais de atendimento.
3 Comentários