• O que é o WebAgent

• Pensado pra ser seguro

• Vantagens no uso do WebAgent em conjunto com o WebApp

• Instalação

  • Para o administrador do sistema

    • 1. Configurando o download do WebAgent a partir do arquivo AppServer.INI

    • 2. Configurando o download do WebAgent a partir do arquivo WebAgent.json

    • 3. Configurando uma porta específica para o WebAgent de todos os usuários

    • 4. Atualização automática de arquivos extras, exemplo, SIGALOJA.DLL

  • Para o usuário do ERP: Baixando o instalador para seu SO

    • Instalando no Windows

    • Instalando no Linux

      • Habilitando o icone da bandeja | Para Fedora, Oracle Linux e Red Hat 

    • Instalando no macOS

• Registrando o certificado SSL para uso do WebAgent

  • Para usuários Windows (automático)

  • Para usuários Linux

  • Para usuários macOS

• Habilitando o WebAgent na Tela de Parâmetros

• Executando o WebAgent em linha de comando

  • Comando launch: Abrindo o navegador diretamente pelo WebAgent

  • Comando --headless: Executando aplicações sem interface através do WebAgent

• Entendendo as arquiteturas 32 e 64 bits para uso do WebAgent

• Exemplos de integração utilizando o WebAgent

• Sistemas Operacionais homologados

• Sistemas Operacionais em homologação

O que é o WebAgent (topo)

O WebAgent é um serviço opcional necessário "apenas" nas estações de trabalho que precisem utilizar:

• Leitura e gravação de arquivos locais;
• Integração com o pacote Microsoft Office;
• Consumo de DLLs (Windows), SOs (Linux) e Dylibs (macOS), mais informações consulte ExecInDllOpen.

Pensado pra ser seguro (topo)

Os navegadores atuais possuem um ambiente de execução segura, chamado Sandbox, que impede o acesso à sua estação de trabalho.

O WebAgent permite esses acessos de forma segura, utilizando os seguintes mecanismos:

• Conexão entre o navegador e o WebAgent exclusivamente via Websocket Secure (wss);
• Conexão entre o navegador e o WebAgent exclusivamente através do endereço localhost, bloqueando ataques a partir de IPs externos;
• Uso do mesmo protocolo de comunicação utilizado entre SmartClient Desktop e o Appserver, um motor utilizado a mais de 20 anos, e conhecidamente seguro.

Vantagens no uso do WebAgent em conjunto com o WebApp (topo)

• Simplificação na montagem de ambientes;
• Instalação e atualização mais rápida, devido ao menor numero de arquivos do WebAgent;
• Ambiente HTML (navegador) sempre atualizado, preparado para os mais novos Frameworks de mercado.

Instalação (topo)

Para o administrador do sistema (topo)

Baixe os instaladores do WebAgent a partir da Central de Downloads.

1. Configurando o download do WebAgent a partir do arquivo AppServer.INI (topo)

Para consultar todas as opções de configuração acesse aqui.

Os parâmetros abaixo representam o Sistema Operacional e a Arquitetura(32/64 bits) do WebAgent:

[WEBAGENT]
VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
Windows_x86=webagent/web-agent-1.x.x-windows-x86.setup.exe
Windows_x64=webagent/web-agent-1.x.x-windows-x64.setup.exe
Darwin_universal=webagent/web-agent-1.x.x-darwin-universal.dmg
Linux_x64_deb=webagent/web-agent-1.x.x-linux-x64.deb
Linux_x64_rpm=webagent/web-agent-1.x.x-linux-x64.rpm

[WEBAGENT]
VERSION=1.x.x "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
Windows_x86=C:\totvs\files\web-agent-1.x.x-windows-x86.setup.exe
Windows_x64=C:\totvs\files\web-agent-1.x.x-windows-x64.setup.exe
Darwin_universal=C:\totvs\files\web-agent-1.x.x-darwin-universal.dmg
Linux_x64_deb=C:\totvs\files\web-agent-1.x.x-linux-x64.deb
Linux_x64_rpm=C:\totvs\files\web-agent-1.x.x-linux-x64.rpm

2. Configurando o download do WebAgent a partir do arquivo WebAgent.json (topo)

Neste exemplo utilizaremos o arquivo de configuração com o nome webagent.json, na mesma pasta do AppServer, mas tanto o nome do arquivo quanto o diretório são de sua escolha, ajuste a configuração de acordo com sua necessidade, por exemplo:

agentJsonUpdate=/home/admin/file_config/installers.json

Para definir o caminho dos instaladores inclua o parâmetro agentJsonUpdate na seção [WebApp] em seu arquivo AppServer.INI.

[WEBAPP]
Port=5002
ENABLE=1
agentJsonUpdate=webagent.json

Criando o arquivo WebAgent.json

Seguindo nosso exemplo, crie agora o arquivo webagent.json na mesma pasta do AppServer.

Os arquivos para download serão disponibilizados em uma subpasta do AppServer, exemplo: /home/admin/totvs/appserver/webagent/

{
    "version": "1.x.x","<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
    "windows_x86": "webagent\\web-agent-1.x.x-windows-x86-release.setup.exe",
    "windows_x64": "webagent\\web-agent-1.x.x-windows-x64-release.setup.exe",
    "darwin_universal": "20-10-10-p12_smartclient_web-agent_1.x.x_mac-universal.dmg",
    "linux_x64_deb": "webagent\\web-agent.deb",  
    "linux_x64_rpm": "webagent\\web-agent.rpm"
}

{
    "version": "1.x.x", "<ajuste esta opção com a versão correta do WebAgent que será disponibilizado>"
    "windows_x86": "webagent/web-agent-1.x.x-windows-x86-release.setup.exe",
    "windows_x64": "webagent/web-agent-1.x.x-windows-x64-release.setup.exe",
    "darwin_universal": "20-10-10-p12_smartclient_web-agent_1.x.x_mac-universal.dmg",
    "linux_x64_deb": "webagent/web-agent.deb",  
    "linux_x64_rpm": "webagent/web-agent.rpm"
}

3. Configurando uma porta específica para o WebAgent de todos os usuários (topo)

[WEBAGENT]
Port=21021
...

Ao habilitar essa chave, a opção "Habilita/Desabilita o Agente Local" não será mais exibida na tela de configuração para o usuário.

4. Atualização automática de arquivos extras, exemplo, SIGALOJA.DLL (topo)

A partir do WebAgent 1.0.15, é possivel definir a atualização automática de arquivos extras, como por exemplo, os arquivos do FrontLoja.

Esta implementação foi feita exclusivamente para Windows.

As chaves a seguir definem o caminho para um arquivo ZIP, que deverá conter a estrutura de diretórios e arquivos que o cliente deseja descompactar na pasta do WebAgent.

📢 Estas chaves estão disponiveis tanto no arquivo AppServer.INI quanto no arquivo JSON de configuração.

[WEBAGENT]
Windows_x86_extras=C:\totvs\files\DLL_SIGALOJA_Win32.zip
Windows_x64_extras=C:\totvs\files\DLL_SIGALOJA_Win64.zip

Para o usuário do ERP (topo)

Acessando a Tela de Parâmetros do WebApp, agora será exibida a tela para download dos instaladores:

O instalador vai sugerir o Sistema Operacional e a Arquitetura(32/64 bits).
Caso utilize o Windows 64 bits, mas precise integrar o ERP com o Microsoft Office 32 bits, poderá baixar o WebAgent 32 bits, mais detalhes aqui.

Instalando no Windows (topo)

Após o download do instalador, basta iniciar sua instalação, que irá seguir sem intervenção do usuário.

O programa ficará disponível no menu, como neste exemplo utilizando o Windows 11.

O WebApp irá iniciar o WebAgent sempre que necessário, mais detalhes consulte a seção Habilitar WebAgent na Tela de Parâmetros.

Apenas para testes, você pode iniciar o WebAgent manualmente, ele será exibido na bandeja de ícones:

Instalando no Linux (topo)

Após baixar o arquivo para o seu respectivo Linux, sendo o arquivo .deb para Ubuntu e .rpm para o Fedora, Oracle Linux e Red Hat.

Ubuntu

sudo apt install ./web-agent<versao>.deb

sudo chmod +x ./web-agent<versao>.deb

Fedora, Oracle Linux e Red Hat (utilizando o desktop GNOME) 

sudo dnf install oracle-epel-release-el9
sudo dnf update

sudo dnf install libappindicator-gtk3

sudo dnf install ./web-agent<versao>.rpm

sudo chmod +x ./web-agent<versao>.rpm

Instalando no macOS (topo)

Este exemplo de instalação/autorização se baseia no macOS Sequoia. (💡 Dica: Clique nas imagens para melhor visualização )

Após baixar o arquivo de instalação para macOS (Universal), com a extenção .dmg, execute o instalador e na sequencia arraste o web-agent para pasta Aplicações (Applications)

Caso esteja atualizando o web-agent, pressione o botão Atualizar (Replace)

Abra o web-agent na pasta Aplicações e pressione o botão Done

Acesse as configurações do seu Mac e na sequencia Privacidade e Segurança (Privacy & Security)

Role até localizar a seção Segurança (Security) e na sequencia clique em Abrir Mesmo Assim (Open Anyway)

Confirme, cliquando em Abrir Mesmo Assim (Open Anyway)

Clique em Use sua Senha (Use Password)

Digite o usuário e senha de um usuário com autorização de Administrador do equipamento

Clique no botão OK para autorizar a execução do WebAgent

Registrando o certificado SSL para uso do WebAgent (topo)

Para utilizar o Websocket Secure (wss) é necessário registrar o TOTVS Certificate em seu sistema operacional.

 Para usuários Windows (automático) (topo)

O registro é automático para Windows 10/11, 32 ou 64 bits, e será efetivado na primeira execução do WebAgent.

Para usuários Linux (topo)

    Ubuntu    

• Após a instalação o WebAgent
• Localize o arquivo totvs_certificate_CA.crt na pasta /opt/web-agent

• Acesse seu navegador e efetue o registro:
  

  Para o Google Chrome

  • Na barra de navegação digite: chrome://settings/certificates
  • Acesse: Authorities (autoridades)
  • Na sequência: Import (importar)
  • Selecione o totvs_certificate_CA.crt na pasta /opt/web-agent
  • Selecione todos os Trusts, e por fim, o botão OK
    

  Para o Microsoft Edge

  • Na barra de navegação digite: edge://settings/privacy/manageCertificates

  • Acesse: Authorities (autoridades)

  • Na sequência: Import (importar)

  • Selecione o totvs_certificate_CA.crt na pasta /opt/web-agent

  • Selecione todos os Trusts e Okay
    

  Para o Firefox

  • Na barra de navegação digite: about:preferences#privacy

  • Acesse: View Certificates… (verificar certificados)

  • Acesse: Authorities (autoridades)

  • Na sequência: Import (importar)

  • Selecione o totvs_certificate_CA.crt na pasta /opt/web-agent

  • Selecione todos os Trusts e OK
    

        Fedora, Oracle Linux e Red Hat

• Para Google Chrome e Firefox o registro do certificado segue os mesmos passos do Ubuntu.

  Para o Microsoft Edge

  • O Edge utiliza o certificado do Sistema Operacional, proceda da seguinte forma para o registro:
    
    

    • Copie o certificado da pasta do web-agent para a pasta de certificados

      • sudo cp /opt/web-agent/totvs_certificate_CA.crt /etc/pki/ca-trust/source/anchors/
        
        

    • Registre o certificado

      • sudo update-ca-trust
        
        

    • Verifique se o certificado foi instalado

      • trust list | grep TO    
        label: TOTVS certificate CA

• Acesse os links abaixo para mais informações:
  • https://docs.fedoraproject.org/en-US/quick-docs/using-shared-system-certificates/
  • https://www.redhat.com/sysadmin/ca-certificates-cli

Para usuários macOS (topo)

Este exemplo de registro do certificado se baseia no macOS Sequoia.  (💡 Dica: Clique nas imagens para melhor visualização )

Após instalar o WebAgent, localize o arquivo totvs_certificate_CA.crt na pasta /Applications/web-agent.app/Contents/MacOS

No App Acesso às Chaves (Keychain Access) , selecione Sistema (System), e na sequência Certificados (Certificates).

Arraste o arquivo do certificado para o App Acesso às Chaves (Keychain Access).

Configure a confiança do certificado, clicando com o botão direito do mouse sobre o arquivo, e escolhendo a opção Obter Informações (Get Info).

Expanda a opção Confiança (Trust), e coloque Confiar Sempre (Always Trust) para todas as opções disponíveis.

Ao confirmar as informações, se for solicitado usuário e senha, utilize um usuário com acesso de administrador.

Habilitando o icone da bandeja (topo)

💡 Dica: Clique nas imagens para melhor visualização

Abra o Firefox, digite about:addons na barra de endereços, e na sequencia procure por GNOME.

Selecione GNOME Shell integration

Pressione Adicionar ao Firefox (Add to Firefox)

Pressione Adicionar (Add)

Selecione a opção Permitir esta extensão em janelas privativas, e na sequência, pressione Okay

Na barra de endereços do Firefox digite https://extensions.gnome.org/ , busque por appindicator e selecione a opção AppIndicator and KStatusNotifierItem Support.

Selecione a opção OFF para instalar a extensão.

Pressione Instalar (Install).

Na sequência, a opção mudará automáticamente para ON.

Apenas para teste, já que o proprio navegador irá instanciar o WebAgent, siga os passos a seguir:

cd /opt/web-agent
./web-agent

Para visualizar as opções do WebAgent, basta clicar em seu ícone.

A partir deste ponto, seu Linux estará pronto para testes.

Habilitando o WebAgent na Tela de Parâmetros (topo)

Para habilitar o uso do WebAgent pelo WebApp, na Tela de Parâmetros, selecione o botão de configuração.

Escolha a porta de inicialização do WebAgent (por padrão é a 21021).

Na sequencia feche essa janela clicando no X na parte superior da janela de configuração.

Ao confirmar os dados na Tela de Parâmetros será exibida a mensagem abaixo, solicitando autorização para abertura do WebAgent, basta clicar no botão Abrir.

Caso a conexão com o WebAgent falhe ou a solicitação de autorização seja ignorada, será exibida a mensagem de erro a seguir:

Executando o WebAgent em linha de comando (topo)

O WebAgent pode ser iniciado via linha de comando, os parâmetros podem ser usados em conjunto, as opções são:

web-agent -c --port 21023

web-agent -v
v1.0.9-RC3 - x64

Comando launch: Abrindo o navegador diretamente pelo WebAgent (topo)

Permite abrir uma janela destacada do navegador a partir do WebAgent.

web-agent launch...

webagent launch "ip+porta+[parâmetros<opcional>]" --browser="caminho para o navegador"

Exemplos:

Nos exemplos abaixo será aberto o SIGAFAT e preenchidos os parâmetros de abertura (&A=), artificio utilizado em produtos como SIGALOJA, e útil em algumas customizações.

C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011?E=padrao&P=SIGAFAT&A=param1&A=param2&A=param3" --browser="C:\Program Files\Google\Chrome\Application\chrome.exe"

/opt/web-agent/web-agent launch "http://10.173.9.215:5011?E=padrao&P=SIGAFAT&A=param1&A=param2&A=param3" --browser="/usr/bin/microsoft-edge"

Lista de parâmetros disponíveis:

Comando --headless: Executando aplicações sem interface através do WebAgent (topo)

A partir da versão 1.0.9 do WebAgent será possível executar programas sem interface gráfica, com o objetivo de dinamizar automações, testes e etc.

Nesse modo é recomendado o uso dos navegadores Google Chrome, Microsoft Edge ou Mozilla Firefox. 

webagent launch "ip+porta+[parâmetros<opcional>]" --browser="caminho para o navegador" --headless

Exemplos:

O exemplo abaixo executa a função de usuário u_headless em um navegador sem interface gráfica.

C:\Users\Administrator\AppData\Local\Programs\web-agent\web-agent.exe launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="C:\Program Files\Google\Chrome\Application\chrome.exe" --headless

/opt/web-agent/web-agent launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="/usr/bin/microsoft-edge" --headless

/Applications/web-agent.app/Contents/MacOS/web-agent launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless

{
"policies": {
"Certificates": {
    "ImportEnterpriseRoots": true,
    "Install" [
               "/opt/web-agent/totvs_certificate_CA.crt"
               ]
         }
    }
}

Entendendo as arquiteturas 32 e 64 bits para uso do WebAgent (topo)

O WebAgent para Linux e macOS será distribuido somente na versão 64 bits.

Para Windows ele será distribuido também na versão 32 bits, devido a dois cenários:

Mais alguns detalhes sobre arquitetura clique aqui.

Exemplos de integração utilizando o WebAgent (topo)

Integração com o Microsoft Excel, mais informações aqui.  (💡 Dica: Clique nas imagens para melhor visualização )

Consumindo uma DLL através da função ExeDllRun3:

Executando uma aplicação nativa através da função ShellExecute:

Retornando as pastas e arquivos de um diretório através da função Directory:

Recuperando a configuração da estação de trabalho através do Shift+F6.

Sistemas Operacionais homologados (topo)

O WebAgent está disponível e homologado para os seguintes Sistemas Operacionais:

Sistemas Operacionais em homologação (topo)