TOTVS Logística Recintos Aduaneiros

Árvore de páginas


01. DADOS GERAIS

Produto:

TOTVS Logística Recintos Aduaneiros

Linha de Produto:

Linha Logix

Segmento:

Logística

Módulo:Serviços de Integração
Função:Integração com balanças TCP/IP
Ticket:
Requisito/Story/Issue (informe o requisito relacionado) :
  1. DLOGPORTOS-16389
  2. DLOGPORTOS-16395
  3. DLOGPORTOS-17979
  4. DLOGPORTOS-19464


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.

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. 

  1. Sistema operacional Microsoft Windows Server 2012 ou superior e;
  2. 25MB de espaço em disco.

Para a instalação da solução, basta copiá-la para um diretório disponível no servidor alvo - como C:\TOTVS\SARA\Services\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âmetroDescriçãoExemplo
-hNome do servidor de banco de dados Microsoft SQL Server.-hSERVIDORBD\SQLSERVER2019
-pPorta de comunicação com o servidor de banco de dados Microsoft SQL Server.-p1433
-dNome do banco de dados a ser utilizado.-dsara_db
-uNome do usuário de banco de dados utilizado na conexão.-usa
-PSenha do usuário de banco de dados utilizado na conexão.-PTotvs@123456
-rPorta 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\IntgraçãoBalanças>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.

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:

  1. Diretório de instalação (valor padrão: C:\TOTVS\Logística\Recintos Aduaneiros\Services\IntegraçãoBalanças);
  2.  API:
    1. Porta de comunicação (valor padrão: 4321) e;
    2. Leitura cumulativa (valor padrão: desmarcada);
  3. Banco de dados:
    1. Servidor\Instância (sem valor padrão);
    2. Porta de comunicação (valor padrão: 1433);
    3. Banco de dados (valor padrão: sara_db);
    4. Usuário (valor padrão: sa) e;
    5. Senha (sem valor padrão);
  4. Log:
    1. Caminho para os arquivos de log (valor padrão: C:\Temp\TOTVS\Log\IntegraçãoBalanças);
    2. Log detalhado (valor padrão: desmarcado) e;
    3. 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.

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\TOTVSIntegracaoBalancas

Esta chave apresenta todas as configurações do serviço junto ao servidor e deve conter três sub-chaves: API, Database e Log. Cada uma destas sub-chaves contém um subgrupo de configurações, os quais devem conter os seguintes valores:

SubchaveConfiguraçãoFunção específicaValor padrãoPadrão do valor a ser inserido
APIPortPorta TCP pela qual o serviço fará a exposição de sua API.43211~65535
APICumulativeReadingFlag indicadora do parâmetro de leitura cumulativa do buffer de saída da balança.falsetrue/false
DatabaseCharSetConjunto de caracteres utilizado pelo servidor Microsoft SQL Server.SQL_Latin1_General_CP1_CI_ASNenhum
DatabaseDatabaseNome do banco de dados usado pelo ecossistema TOTVS Recintos Aduaneiros.sara_dbNenhum
DatabaseDriverIDIdentificação do tipo de banco de dados a ser utilizado.MSSQLNenhum
DatabaseHostnameIndicação de localização do servidor Microsoft SQL Server.localhostNomeDoServidor\NomeDaInstância
DatabasePasswordSenha do usuário usado na integração para acesso ao banco de dados.Totvs@123Nenhum
DatabasePortPorta padrão de comunicação do servidor Microsoft SQL Server.14331~65535
DatabaseUsernameNome do usuário usado na integração para acesso ao banco de dados.saNenhum
LogLogFileCaminho completo para o arquivo de log da aplicação.C:\Temp\TOTVS\IntgBalanca\IntgBalanca_%s.log^[A-Z]{1}:\\([\w]+\\)+(IntgBalanca_%s\.log)$
LogDetailedLogFlag indicadora do parâmetro de registros de log detalhados.falsetrue/false
LogEventLogFlag indicadora do parâmetro de registro de logs de evento.falsetrue/false

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.

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:

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/detailedlog/{action}: Ativa/Desativa os logs detalhados 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)


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.