Histórico da Página

01. DADOS GERAIS

02. SITUAÇÃO/REQUISITO

Para atendimento à solicitação para resolução de problemas relacionados à conexão com balanças rodoviárias, com comunicação efetuada através dos protocolos TCP/IP, em que duas ou mais estações, utilizando o módulo Portaria, tentam conectar-se simultaneamente à mesma balança, causando erro de conexão, foi elaborada a solução de integração para conexão entre as estações e as balanças configuradas.

A conexão, por dar-se através de sockets TCP/IP, causa erro de conexão por tratar-se de canal exclusivo de comunicação, não aceitando que dois ou mais canais sejam abertos simultaneamente. Mesmo que não haja a necessidade de duas ou mais estações acessarem a mesma balança simultaneamente, o problema pode ocorrer no momento em que o operador execute o processo de alteração da balança a ser acessada, uma vez que isso pode efetuar uma tentativa de conexão com uma balança já conectada a uma estação.

03. SOLUÇÃO

A solução, uma aplicação no modelo de serviço para o sistema Microsoft Windows, deve ser instalada em um servidor na infraestrutura local de rede, uma vez que, para garantir a estabilidade da comunicação desta com as balanças, a latência de rede deve ser a menor possível. Sendo assim, esta solução não está homologada para operação em nuvem, sendo vetada integralmente sua utilização em tal modelo.

Para tanto, as soluções dependem de requisitos a serem atendidos anteriormente e que podem ser vistos a seguir. É importante salientar que, para um perfeito processo de integração, todos os requisitos adiante devem ser atendidos antes da implantação, garantindo o perfeito funcionamento da solução. Os pré-requisitos são divididos em duas partes, uma para a estrutura containerizada com Docker, e outra para o serviço a ser instalado em um servidor Microsoft Windows.

Já o processo de implantação, uma vez que todos os requisitos sejam atendidos, é simples e rápido. Se seguido conforme as instruções constantes neste artigo, a possibilidade de falha no processo de integração é praticamente nula. 

Totvs custom tabs box
tabs Pré-requisitos,Instalação,Configuração,Inicialização,Documentação Swagger ids prerequisitos,instalacao,configuracao,inicializacao,documentacao
Totvs custom tabs box items default yes referencia prerequisitos Sistema operacional Microsoft Windows Server 2012 ou superior e; 25MB de espaço em disco. Totvs custom tabs box items default no referencia instalacao Totvs custom tabs box tabs Instalação manual,Instalação automatizada ids manual,automatizada Totvs custom tabs box items default yes referencia manual Para a instalação da solução, basta copiá-la para um diretório disponível no servidor alvo - como C:\TOTVS\SARA\Services\ IntgBalancaSvc IntgraçãoBalanças, por exemplo - e comandar sua instalação através do comando abaixo, devendo ser executado por um usuário com privilégios administrativos: C:\TOTVS\SARA\Services\IntgraçãoBalanças>TOTVSIntgBalanca.exe /install É importante notar que a instalação pode ser parametrizada, fornecendo as configurações adequadas através de linha de comando, sendo: Parâmetro Descrição Exemplo -h Nome do servidor de banco de dados Microsoft SQL Server. -hSERVIDORBD\SQLSERVER2019 -p Porta de comunicação com o servidor de banco de dados Microsoft SQL Server. -p1433 -d Nome do banco de dados a ser utilizado. -dsara_db -u Nome do usuário de banco de dados utilizado na conexão. -usa -P Senha do usuário de banco de dados utilizado na conexão. -PTotvs@123456 -r Porta de comunicação da API fornecida pelo serviço de integração. -r4321 Sendo assim, um exemplo de instalação parametrizada via linha de comando seria: C:\TOTVS\SARA\Services\ IntgBalancaSvc IntgraçãoBalanças> IntgBalacaSvc TOTVSIntgBalanca.exe -hSERVIDORBD\SQLSERVER2019 -dsara_db -p1433 -usa -PTotvs@123456 -r9876 /install NOTA Quando utilizando a versão legada do serviço, para que o novo serviço possa ser instalado, este deve ser parado e desativado no servidor afim de evitar a concorrência na conexão com as balanças integradas ou pelo consumo da porta de comunicação da API. Uma vez homologado o novo serviço, o serviço legado pode ser desinstalado por meio da linha de comando apropriada em um terminal com privilégios administrativos. Totvs custom tabs box items default no referencia automatizada Este serviço conta, também, com um assistente de instalação automatizado, o qual pode ser obtido aqui. Este assistente permite que ao usuário instalar o novo serviço e suas dependências de maneira simples e rápida. Assim como na instalação manual, é possível configurar o novo serviço durante sua instalação, fornecendo, inclusive, informações não contempladas na instalação manual, sendo: Diretório de instalação (valor padrão: C:\TOTVS\Logística\Recintos Aduaneiros\Services\IntegraçãoBalanças);  API: IP de instalação do servidor (quando o servidor de destino contar com mais de um endereço IP); Porta de comunicação (valor padrão: 4321) e; Leitura cumulativa (valor padrão: desmarcada); Banco de dados: Servidor\Instância (sem valor padrão); Porta de comunicação (valor padrão: 1433); Banco de dados (valor padrão: sara_db); Usuário (valor padrão: sa) e; Senha (sem valor padrão); Log: Caminho para os arquivos de log (valor padrão: C:\Temp\TOTVS\Log\IntegraçãoBalanças); Log de erros (valor padrão: desmarcado) e; Log de eventos (valor padrão: desmarcado). Vale ressaltar que a instalação ocorre de maneira sequencial, onde as informações são fornecidas conforme o usuário avança no processo de instalação. A escolha dos diretórios, tanto de instalação quanto de armazenamento dos arquivos de log é de escolha livre, sem a necessidade da observância dos valores padrão. Os demais valores sugeridos como valor padrão são os valores adotados por padrão no produto, mas podem ser alterados caso a implantação do ecossistema TLRA assim demande. É importante lembrar que, para uma melhor experiência durante o processo de instalação, o assistente seja executado com privilégios administrativos, permitindo que este remova, sendo este o caso, o serviço legado e, ao fim do processo, comande a inicialização do novo serviço. O assistente de instalação pode, também, ser executado através de linha de comando, com parametrização idêntica à utilizada para a instalação manual, fazendo com que os parâmetros de instalação venham preenchidos com os valores fornecidos na linha de comando. Além disso, o assistente pode promover a criação ou atualização1 do parâmetro BALANCA_SVC_HOST na base de dados, com os dados de endereço IP e porta de comunicação com o serviço sem a necessidade da interação direta do usuário. NOTAS Caso o instalador seja incapaz de determinar o endereço IP do servidor, parâmetro não contará com esta informação, devendo o usuário informá-la manualmente.  Totvs custom tabs box items default no referencia configuracao Após o término da instalação do serviço de integração - com a mensagem de sucesso sendo exibida pelo sistema operacional - é necessário realizar as configurações referentes ao serviço. Para isso, é necessário executar, com privilégios administrativos, o editor de registro do sistema Microsoft Windows, acessando a chave a seguir: Computador\HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\TOTVSIntgBalancaTOTVSIntegracaoBalancas Esta chave apresenta todas as configurações do serviço junto ao servidor e deve conter três subchavessub-chaves:   API, Database e Log. Cada uma destas subchaves sub-chaves contém um subgrupo de configurações, os quais devem conter os seguintes valores: SARA Subchave Configuração Função específica Valor padrão Padrão do valor a ser inserido API Audience Valor de validação das restrições de uso da API de integração disponibilizada pelo serviço. Integração Balanças Nenhum API DSContext Valor de configuração da rota de acesso à API de integração disponibilizada pelo serviço. api/ ^[a-z0-9_]+\/$ API Issuer Valor de validação das restrições de uso da API de integração disponibilizada pelo serviço. Nenhum API Port Porta TCP pela qual o serviço fará a exposição de sua API. 4321 1~65535 API RESTContext Valor de configuração da rota de acesso à API de integração disponibilizada pelo serviço. sara/ CumulativeReading Flag indicadora do parâmetro de leitura cumulativa do buffer de saída da balança. false true/false^[a-z0-9_]+\/$ Database CharSet Conjunto de caracteres utilizado pelo servidor Microsoft SQL Server. SQL_Latin1_General_CP1_CI_AS Nenhum Database Database Nome do banco de dados usado pelo ecossistema TOTVS Recintos Aduaneiros. sara_db Nenhum Database DriverID Identificação do tipo de banco de dados a ser utilizado. MSSQL Nenhum Database Hostname Indicação de localização do servidor Microsoft SQL Server. localhost NomeDoServidor\NomeDaInstância Database Password Senha do usuário usado na integração para acesso ao banco de dados. Totvs@123 Nenhum Database Port Porta padrão de comunicação do servidor Microsoft SQL Server. 1433 1~65535 Database Username Nome do usuário usado na integração para acesso ao banco de dados. sa Nenhum Log LogFile Caminho completo para o arquivo de log da aplicação. C:\Temp\TOTVS\IntgBalanca\IntgBalanca_%s.log ^[A-Z]{1}:\\([\w]+\\)+(IntgBalanca_%s\.log)$ Log ErrorLog Flag indicadora do parâmetro de registro de logs de erro. false true/false Log EventLog Flag indicadora do parâmetro de registro de logs de evento. false true/false Totvs custom tabs box items default no referencia inicializacao Após efetuada Para o caso de instalação manual - quando não parametrizada, é necessário efetuar a configuração dos parâmetros de operação do serviço por meio do registro do sistema operacional -, ou em caso de falha na inicialização do serviço através do assistente, basta acessar o gestor de serviços do servidor e comandar sua inicialização. Image Added Totvs custom tabs box items default no referencia documentacao Ao instalar e iniciar o serviço de integração com balanças com comunicação via TCP/IP, este fornecerá um canal para acesso à sua documentação OpenAPI através da ferramenta Swagger inclusa no serviço. Conforme exemplo citado na seção de instalação, o serviço tendo sido instalado em um servidor cujo endereço IP seja 172.25.48.1 e a porta de comunicação seja 9876, o acesso à documentação se dá pela URL http://172.25.48.1:9876/api/tlra/intgbalanca/v1/docs, exibindo-a conforme visto abaixo: Image Added Esta documentação permite que as respostas da API sejam testadas e validadas de forma rápida e simples. Contudo, excetuando o endpoint /access/currentdatetime, é necessário autenticar-se para executar os demais métodos. O processo é simples e pode ser feito por meio de um usuário válido dentro do ecossistema TLRA. São endpoints expostos pela API: [GET] /access/balances: Obtém a lista de balanças integradas ao serviço. [GET] /access/canconnecttodatabase: Verifica se o servidor está apto a se conectar ao banco de dados. [GET] /access/connecttodatabase: Comanda a conexão do servidor com o banco de dados. [GET] /access/currentdatetime: Requisita ao servidor a data e hora atualizadas. [GET] /access/isconnectedtodatabase: Verifica se o servidor está conectado ao banco de dados. [GET] /access/reloadbalances: Recarrega as configurações das balanças cadastradas no sistema. [GET] /config/cumulativereading/{action}: Ativa/Desativa a leitura cumulativa do buffer de saída da balança. (activate/deactivate) [GET] /config/errorlog/{action}: Ativa/Desativa os logs de erro do servidor. (activate/deactivate) [GET] /config/eventlog/{action}: Ativa/Desativa os logs de eventos do servidor. (activate/deactivate) [GET] /config/readconfig: Lê a configuração corrente do servidor. [GET] /config/reloadconfig: Recarrega as configurações do serviço. [GET] /reading/readweight/{balanca}: Lê o peso medido na balança solicitada. (nome_da_balanca) [GET] /log/showlog/{date}: Mostra o log de eventos da data informada. (formato ISO YYYY-MM-DD) Image Removed

04. DEMAIS INFORMAÇÕES

Para uma perfeita integração com o

...

ecossistema TOTVS Logística Recintos Aduaneiros, este deve estar em sua versão 12.1.

...

2411 ou superior para os módulos Operacional e Portaria, bem como o serviço do coletor de dados TELNET, uma vez que esta versão está preparada para a integração com

...

este serviço. Em versões anteriores a esta, a tentativa de integração ocasionará falhas no processo de integração que podem paralisar o serviço de integração e, na pior das hipóteses, paralisar o servidor onde ele esteja abrigado.

A configuração das balanças a serem integradas por meio deste serviço deve ter seu parâmetro Comunicação alterado para SERVIÇO INTEGRAÇÃO, de modo a permitir que o serviço as reconheça e estabeleça a comunicação. Os módulos Operacional e Portaria contam com cadastros distintos para balanças de armazém e rodoviárias, respectivamente, devendo a configuração das balanças integradas ser efetuada individualmente.

05. NOTAS

1. Para o devido funcionamento da integração com as balanças, seus nomes devem, obrigatoriamente, ser registrados sem uso de caracteres especiais ou acentuações.
2. É possível integrar qualquer aplicação à API para a leitura do peso de cada balança, bastando que a aplicação integrada utilize um usuário válido do ecossistema TLRA.
3. Para o devido funcionamento de leitura das informações disponibilizadas pela balança, a mesma deve enviar os valores de leitura de forma íntegra, com seu buffer contendo integralidade da medição. Para mais informações sobre esta configuração, verifique o manual do equipamento.
4. Esta solução é recomendada para ambientes em que haja concorrência na leitura do peso aferido em uma balança. Caso não haja necessidade, recomenda-se a configuração da balança como TCP-IP.