[WebApp]
Port=5002
ENABLE=1
agentJsonUpdate=

webagent.json

{
    "version": "0.0.4",
   
    "windows_x86": "webagent\\web-agent-1.0.0-RC1-windows-x86-release.setup.exe",
    "windows_x64": "webagent\\web-agent-1.0.0-RC1-windows-x64-release.setup.exe"

    "darwin_x64": "webagent/web-agent-1.0.0-SNAPSHOT-darwin-x64-release.dmg",
    "darwin_arm64": "webagent/web-agent-1.0.0-SNAPSHOT-darwin-x64-release.dmg",
    "darwin_universal": "webagent/web-agent-1.0.0-SNAPSHOT-darwin-x64-release.dmg",

    "linux_x64_deb": "webagent/web-agent-1.0.0-SNAPSHOT-linux-x64-release.deb",  
    "linux_x64_rpm": "webagent/web-agent-1.0.0-SNAPSHOT-linux-x64-release.rpm",
}

🚨 Após a configuração do arquivo webagent.json, deve-se reiniciar o/s AppServer/s de seu ambiente para que as configurações sejam iniciadas.

Para o usuário do ERP

Após a configuração acima, ao acessar a Tela de Parâmetros do WebApp, será exibida a tela para download, conforme exemplo abaixo:

Image Removed

O instalador vai sugerir o Sistema Operacional, porém, caso use o Windows 64 bits, mas possua o Microsoft Office 32 bits, poderá instalar a versão 32 para garantir sua integração, veja mais informações aqui.

Image Removed

Após o download basta clicar no arquivo de instalação, que irá prosseguir sem qualquer outra intervenção do usuário.

Image Removed

Após a instalação o programa estará disponível no menu, como neste exemplo, utilizando o Windows 11.

Image Removed

Iniciando a aplicação será exibido o ícone na bandeja em destaque abaixo, informando a porta para conexão com o WebAgent, no exemplo, a 21021.

Image Removed

Registro do Certificado (SSL) para uso do WebAgent (topo)

Como explicado no tópico Segurança, a conexão com o WebAgent é feita através de um protocolo seguro, o Websocket Secure (wss), para tanto é necessário registrar o TOTVS Certificate em seu sistema operacional.

Image Removed Para usuários Windows

Esse registro é automático para Windows 10/11, 32 ou 64 bits, e será efetivado na primeira abertura do WebAgent.

🚨 Importante: Na primeira execução do WebAgent, caso seja apresentada uma tela de confirmação para o registro do certificado, selecione a opção Sim.

Image Removed Para usuários Linux

Image Removed

Para o Microsoft Edge

Image Removed

Image Removed Para usuários macOS

Para detalhes acesse a documentação oficial da Apple aqui:

• Após a instalação do WebAgent
• Localize o arquivo totvs_certificate_CA.crt na pasta /Applications/web-agent.app/Contents/MacOS
• No app Acesso às Chaves (keychain access) do Mac Image Removed , selecione as chaves de início de sessão ou de Sistema.
• Arraste o arquivo do certificado para o app Acesso às Chaves.
• Se for solicitado que você forneça um nome e senha, digite o nome e a senha de um usuário administrador nesse computador.

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

Image Removed

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

Image Removed

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

Image Removed

🚨 Importante: A inicialização do WebAgent pode ser feita de duas formas:

1a - Conforme explicado na seção Instalação, ao iniciar o WebAgent via menu, ele ficará disponível nos ícones da bandeja.

2a - Caso o WebAgent não tenha sido iniciado, ao clicar no botão OK da Tela de Parâmetros, será solicitada autorização para abertura da aplicação, basta clicar no botão Abrir.

Image Removed

Em sua primeira liberação o WebAgent estará disponível para os Sistemas Operacionais:

Image RemovedWindows 10 Pro/Enterprise ou superior

Image Removed

Criando o arquivo WebAgent.json
Seguindo nosso exemplo, crie agora o arquivo webagent.json na mesma pasta do AppServer.
Aqui os arquivos para download serão disponibilizados em uma subpasta do AppServer, exemplo: /home/admin/totvs/appserver/webagent/
🚨 Importante: 
Caso esteja utilizando um AppServer Windows é necessário utilizar barras duplas \\ para configuração do arquivo, pois a primeira barra é considerada um caracter de escape pelo formato .json, e não permitirá o download do instalador.
 Nota
title
Importante
🚨 VERSION: define a versão dos instaladores do WebAgent disponíveis pra download, dois pontos importantes:
Sempre que atualizar os instaladores na pasta de download é necessário atualizar também sua versão no arquivo json;
O versão pode ser alterada tanto para update quanto para downgrade do WebAgent.
As Tags abaixo representam o Sistema Operacional e a Arquitetura do WebAgent, as opções são:
windows_x86: Windows 10/11 32 bits
windows_x64: Windows 10/11 64 bits
darwin_x64: macOS 64 bits Intel
darwin_universal: masOS 64 bits Universal Apps (mais informações aqui)
linux_x64_deb: Linux 64 bits pacote DEB (Ubuntu)
linux_x64_rpm: linux 64 bits pacote RPM (Red Hat)

 Bloco de código
language
c#
theme
RDark
title
Exemplo de Configuração do WebAgent (webagent.json) - AppServer Windows
{
    "version": "1.0.0",   
    "windows_x86": "webagent\\web-agent-1.0.0-windows-x86-release.setup.exe",
    "windows_x64": "webagent\\web-agent-1.0.0-windows-x64-release.setup.exe",
    "darwin_universal": "20-10-10-p12_smartclient_web-agent_1.0.0_mac-universal.dmg",
    "linux_x64_deb": "webagent\\web-agent.deb",  
    "linux_x64_rpm": "webagent\\web-agent.rpm"
}

 Bloco de código
language
c#
theme
RDark
title
Exemplo de Configuração do WebAgent (webagent.json) - AppServer Linux
{
    "version": "1.0.0",   
    "windows_x86": "webagent/web-agent-1.0.0-windows-x86-release.setup.exe",
    "windows_x64": "webagent/web-agent-1.0.0-windows-x64-release.setup.exe",
    "darwin_universal": "20-10-10-p12_smartclient_web-agent_1.0.0_mac-universal.dmg",
    "linux_x64_deb": "webagent/web-agent.deb",  
    "linux_x64_rpm": "webagent/web-agent.rpm"
}
 Âncora
InstAdmin3
InstAdmin3
3. Configurando uma porta específica para o WebAgent de todos os usuários(topo)
O parâmetro PORT(opcional) habilita uma porta específica para o WebAgent de todos os usuários, impedindo que eles alterem esta configuração.
 Bloco de código
language
c#
theme
RDark
title
Trecho do arquivo AppServer.ini
[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.
Image Added
 Âncora
InstUser
InstUser
Para o usuário do ERP (topo)
Acessando a Tela de Parâmetros do WebApp, agora será exibida a tela para download dos instaladores:
 Nota
title
Importante
🚨O Popup para instalação do WebAgent deixará de ser exibido assim que a primeira conexão entre ele e o Navegador for bem sucedida, para que não induza o usuário a instalar mais de uma vez a ferramenta.
🚨O checkbox "Não mostrar novamente" deve ser usado caso o usuário não precise instalar o WebAgent e também não queira que esta opção continue sendo exibida.
Image Added
O instalador vai sugerir o Sistema Operacional e a Arquitetura, caso utilize o Windows 64 bits, mas precise integrar o ERP com o Microsoft Office 32 bits, poderá instalar o WebAgent 32 bits, para permitir essa integração, mais detalhes aqui.
Image Added
 Âncora
InstWindows
InstWindows
Instalando no Windows (topo)
Após o download do instalador, basta iniciar sua instalação, que irá seguir sem intervenção do usuário.
Image Added
O programa ficará disponível no menu, como neste exemplo utilizando o Windows 11.
Image Added
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, será exibido o ícone na bandeja, como no exemplo abaixo.
Image Added
 Âncora
InstLinux
InstLinux
Instalando no Linux (topo)
Após baixar o arquivo para o seu respectivo Linux, sendo o arquivo .deb para Ubuntu e .rpm para o Red Hat.
Para Ubuntu Image Added
 Bloco de código
language
bash
theme
RDark
title
No diretório onde o arquivo .deb foi copiado
sudo apt install ./web-agent<versao>.deb
 Bloco de código
language
bash
theme
RDark
title
Caso tenha problema durante a instalação, o comando abaixo define o arquivo como um instalador, execute e na sequencia repita o comando acima
sudo chmod +x ./web-agent<versao>.deb
Para Red hat 8.x Image Added
 Bloco de código
language
bash
theme
RDark
title
Pré requisito: Necessário instalar a biblioteca libappindicator
sudo dnf install libappindicator-gtk3
 Bloco de código
language
bash
theme
RDark
title
No diretório onde o arquivo .rpm foi copiado
sudo dnf install ./web-agent<versao>.rpm
 Bloco de código
language
bash
theme
RDark
title
Caso tenha problema durante a instalação, o comando abaixo define o arquivo como um instalador, execute e na sequencia repita o comando acima
sudo chmod +x ./web-agent<versao>.rpm
 Âncora
Certificado
Certificado

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.
Image Added Para usuários Windows
O registro é automático para Windows 10/11, 32 ou 64 bits, e será efetivado na primeira execução do WebAgent.
🚨 Importante: Na primeira execução do WebAgent, caso seja apresentada a tela de confirmação para o registro do certificado, selecione a opção "SIM".
 Informações
title
Dicas para configuração do Firefox
Na configuração do Firefox pode estar desabilitada a utilização de certificados do sistema, causando falha na conexão com o WebAgent, é necessário habilitar os certificados da seguinte maneira:
Na barra de navegação digite: about:config
Clicar em "Aceitar o risco e continuar"
Image Added
Na barra de pesquisa digite: security.enterprise_roots.enabled e mude a opção para true (verdadeiro) clicando no botão a direita.
Image Added
Image Added Para usuários Linux
    Image Added Ubuntu    
Após a instalação do WebAgent
Localize o arquivo totvs_certificate_CA.crt na pasta /opt/web-agent
Acesse seu navegador e efetue o registro:
 Informações
icon
false
title
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
Image Added
 Informações
icon
false
title
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
Image Added
 Informações
icon
false
title
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
Image Added
   Image Added Red Hat 8.x
Para Google Chrome e Firefox o registro do certificado segue os mesmos passos do Ubuntu.
 Informações
icon
false
title
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
Image Added Para usuários macOS
Para mais detalhes acesse a documentação oficial da Apple aqui:
Após a instalação do WebAgent
Localize o arquivo totvs_certificate_CA.crt na pasta /Applications/web-agent.app/Contents/MacOS
No app Acesso às Chaves (keychain access) Image Added, selecione as chaves de início de sessão ou de Sistema.
Arraste o arquivo do certificado para o app Acesso às Chaves.
Configure a confiança do certificado clicando com o botão direito sobre o mesmo e escolhendo a opção Get Info. 
Expanda a opção Trust e coloque Always Trust para todas as opções disponíveis, conforme as imagens abaixo. 
Se for solicitado que você forneça um usuário, utilize um usuário com acesso de administrador.
Image Added ↪ Image Added ↪ Image Added
🚨 Repita o mesmo processo de registro do certificado acima para o arquivo totvs_certificate.crt, também na pasta /Applications/web-agent.app/Contents/MacOS

 Informações
title
Importante
Atente-se à utilização dos certificados disponibilizados na pasta de instalação do WebAgent, não utilize os certificados da pasta de instalação do AppServer
 Âncora
Configuracao
Configuracao

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.
Image Added
Escolha a porta de inicialização do WebAgent (por padrão é a 21021).
Image Added
Na sequencia feche essa janela clicando no X na parte superior da janela de configuração.
Image Added
Assim que 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.
Image Added
Após dez tentativas de conexão mal sucedidas, ou caso a solicitação de autorização seja ignorada, será exibida a seguinte mensagem:
Image Added
 Âncora
command_line
command_line

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 -h ou --help
Exibe help com essas opções
web-agent -c ou --console
Abre o Agente em console e não no systray, nesse exemplo abrimos em console e subimos o WebAgent na porta 21023:
web-agent -c --port 21023
web-agent -v ou --version
Exibe a versão do Agente
web-agent -t ou --tray
Abre o agent via systray
web-agent --locallog 1
Habilita a geração de log de execução do Agente
web-agent --locallog 0
Desabilitar o log de execução
 Âncora
Launch
Launch
Comando Launch: Abrindo o navegador diretamente pelo WebAgent (topo)
Permite abrir uma janela destacada do navegador a partir do WebAgent.
Image Added
 Informações
title
Dica importante
Durante a primeira execução com comando launch, a janela pode não ser exibida de forma maximizada, impedindo uma melhor experiência, maximize a janela, e nas próximas execuções o navegador irá respeitar o estado em que foi encerrado.
Importante: O comando launch deve obrigatóriamente ser o primeiro da linha de comando, exemplo:
web-agent launch...
Quando utilizado o comando launch, o webagent iniciará em uma porta aleatória, permitindo multiplas execuções, cada uma em sua porta específica.
Para execução de aplicações que não utilizam interface, como processamentos e execução de jobs, utilize a opção --headless, mais informações acesse aqui.
 Bloco de código
language
bash
theme
RDark
title
Sintaxe
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.
 Bloco de código
language
bash
theme
RDark
title
Exemplo de abertura do WebAgent em linha de comando em Windows
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"
 Bloco de código
language
bash
theme
RDark
title
Exemplo de abertura do WebAgent em linha de comando em Linux
/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:
Parâmetro de linha para a URL
Descrição
Observações
&E=
Indica o nome do ambiente que será utilizado para definições gerais.

&P=
Identifica o programa inicial que será executado.

&A=
Identifica um parâmetro que será passado para o programa inicial.
 Esse parâmetro de linha pode ser especificado mais de uma vez.
 O valor recebido pelo programa, através do parâmetro de linha, é do tipo caractere.
 Âncora
Headless
Headless

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. 
 Bloco de código
language
bash
theme
RDark
title
Sintaxe
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.
 Bloco de código
language
bash
theme
RDark
title
Exemplo de execução headless do WebAgent em Windows
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
 Bloco de código
language
bash
theme
RDark
title
Exemplo de execução headless do WebAgent em Linux
/opt/web-agent/web-agent launch "http://10.173.9.215:5011?E=padrao&P=u_headless" --browser="/usr/bin/microsoft-edge" --headless
 Bloco de código
language
bash
theme
RDark
title
Exemplo de execução headless do WebAgent em MacOS
/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
 Informações
title
Dica importante
O navegador Safari no MacOS não suporta o modo headless.
O Mozilla Firefox, em Linux e modo headless, pode recusar os certificados de autoridade CA já registrados, impossibilitando o uso. É possível utilizar policies.json do navegador para contornar o problema:
Na pasta de instalação do Firefox (que depende do Linux utilizado, por exemplo /opt/firefox/ ou /usr/lib/firefox/) localize a pasta distribution e nela crie um arquivo com o nome de policies.json com o seguinte conteúdo, apontando para o arquivo totvs_certificate_CA.crt da pasta de instalação do WebAgent:
 Bloco de código
language
xml
theme
RDark
title
Conteúdo do arquivo distribution\policies.json
{
"policies": {
"Certificates": {
    "ImportEnterpriseRoots": true,
    "Install" [
               "/opt/web-agent/totvs_certificate_CA.crt"
               ]
         }
    }
}
 Âncora
Arquitetura
Arquitetura
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:
 Informações
icon
false
title
Cenário 1
Utilizar o Windows 64 bits, porém ferramentas 32 bits, nesse caso será necessária a instalação do WebAgent 32 bits para integração com:
Pacote Microsoft Office 32bits;
DLLs 32 bits, para por exemplo, integração de equipamentos, como impressoras, balanças, caixas registradoras, etc.
 Informações
icon
false
title
Cenário 2
Utilizar o Windows 64 bits, o Office 32 bits e uma integração com DLLs 64 bits (o inverso pode ocorrer).
Neste caso é possível instalar as duas versões do WebAgent, 32 e 64 bits, e executá-las em portas diferentes, a partir da configuração da Tela de Parâmetros, usando, por exemplo, o WebAgent 32 bits na porta 21021 e o 64 bits na porta 21022:
Image Added
🚨 Para que este segundo cenário funcione será necessário abrir duas sessões distintas do WebApp no navegador.
      Mesmo procedimento adotado caso fosse necessário utilizar simultaneamente as versões do SmartClient Desktop 32 e 64 bits.
Mais alguns detalhes sobre arquitetura clique aqui.
 Nota
title
Importante
🚨 Para verificar a arquitetura de seu pacote Microsoft Office clique aqui ou acione o suporte da Microsoft.
🚨 Para verificar a arquitetura das DLLs de alguma ferramenta que utilize, acione o suporte do equipamento ou ferramenta em questão.
 Âncora
Sistemas
Sistemas

Sistemas Operacionais homologados (topo)
...
 Aviso
title
Não homologado para uso em Metaframes
O WebAgent não é homologado para navegadores utilizados a partir de Metaframes, RDPs ou Web enablers, como:
Citrix;
Windows Remote Desktop;
Go Global.
Devido à simplificação na montagem do ambiente com o  WebApp, nossa arquitetura não depende das ferramentas acima para utilização dos ERPs Protheus/Logix.
 Aviso
O WebAgent não é homologado para sistemas operacionais :
ChromeOS
iOS
iPadOs
Android
O WebAgent está disponível para os Sistemas Operacionais:
...
Image Added Window 32 e 64 bits: 
Windows 10 Pro/Enterprise ou superior
Windows 11 Pro/Enterprise ou superior

Linux 64 bits:
Image Modified Ubuntu 20.04 LTS 
...
ou superior
Image Added Red Hat Enterprise Linux Desktop 8.x

Image Added macOS x86_64 e Universal (ARM64 e x86_64) 
macOS 12.0 Monterey ou superior
A tentativa de utilizar a versão Universal em macOS anterior resultará no erro abaixo:
Image Added

 Âncora
Exemplos
Exemplos

Exemplos de uso (topo)
...
Nesta seção listamos alguns exemplos de integração possíveis através do WebAgent:

Integração com o Microsoft Excel, mais informações 
...
 aqui. (clique nas imagens para visualização full)
Image Modified

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

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

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

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