Ir para o conteúdo

FAQ

Perguntas frequentes

Esta página reúne as dúvidas mais comuns de quem desenvolve, executa e orquestra automações com as ferramentas da BotCity. Cada entrada descreve um cenário específico, explica o que costuma causar aquele comportamento e apresenta a solução ou uma forma de contornar o problema.

As perguntas estão agrupadas por tema, da instalação e da configuração do ambiente até a execução pelo Runner, os cenários de conexão remota, o desenvolvimento das automações, o acesso à plataforma via SSO e as dúvidas sobre planos no Orquestrador. Clique em uma pergunta para expandir a resposta.

Compartilhar uma resposta específica

Cada entrada tem o seu próprio link, então você pode compartilhar uma resposta específica com outras pessoas do seu time. Para copiar esse link:

  1. Clique na pergunta para expandir a resposta.
  2. Passe o mouse sobre o título da pergunta e clique no ícone de link (¶) que aparece ao lado.
  3. Copie o endereço da barra do navegador, que agora aponta direto para aquela pergunta.

Não encontrou a sua pergunta?

Se o seu cenário não estiver listado aqui, escolha o canal de acordo com o tipo de dúvida:

  • Dúvida técnica, com plano contratado: abra um ticket no portal de suporte. O acesso ao portal é enviado por e-mail aos usuários da organização, e cada plano tem a sua regra de atendimento, descritas em contrato. Clientes Enterprise têm ainda um canal direto com o time de Automation Experience.
  • Dúvida técnica, sem plano contratado: pergunte no grupo do WhatsApp, onde o time da BotCity e outras pessoas usuárias respondem. Os demais canais abertos estão reunidos na página Comunidade.
  • Contrato, limites da conta ou upgrade de plano: fale com o seu representante comercial ou use o formulário de contato do site.

Instalação e configuração do ambiente

Como resolver o problema da instalação travada em 0%?

Como resolver o problema da instalação travada em 0%?

Esse tipo de problema é mais comum em casos onde existem bloqueios no ambiente da empresa onde as ferramentas estão sendo utilizadas. Entre os comportamentos observados, estão:

  • Instalação através do Wizard travada em 0%.
  • Erro ao iniciar o Runner.
  • Problema de autenticação ao tentar fazer login no BotCity Studio.

Antes de abrir a solicitação para o time de TI, confirme a origem do problema com a ferramenta de diagnóstico. O BotCity - Diagnostic acompanha o pacote do Wizard e valida a conectividade com a plataforma BotCity, além das versões de Java e Python instaladas na máquina:

  1. Execute o diagnostic.jar, que fica na mesma pasta do Wizard.
  2. Informe a URL do seu servidor e clique em Run Tests.
  3. Confira o retorno de cada verificação nas colunas Test, Result e Notes.

Um resultado FAIL em algum teste de conexão indica que a máquina está em um ambiente com bloqueios, e a coluna Notes mostra o que falhou em cada caso. Use o botão Export para gerar um arquivo CSV com os resultados e encaminhá-lo ao time de TI junto com o pedido de liberação.

A solução ideal nesse caso é solicitar para o time de TI da empresa algumas liberações de acesso. Veja mais detalhes sobre as URLs que precisam de liberação de acesso na seção Problemas com bloqueios do ambiente.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

O que fazer quando o Wizard exibe o erro Not a valid BotCity Orchestrator hostname.?

O que fazer quando o Wizard exibe o erro Not a valid BotCity Orchestrator hostname.?

Esse erro aparece na etapa de login do Wizard de instalação, depois que você informa a URL da Plataforma BotCity no campo Server:

Not a valid BotCity Orchestrator hostname.

Para validar o campo, o Wizard faz uma requisição GET para <url-do-orquestrador>/api/v2/maestro/version e só considera o servidor válido se a resposta trouxer a versão do Orquestrador. Qualquer falha nessa requisição gera a mesma mensagem, mesmo quando a URL está correta. As causas mais comuns são:

Causa Como resolver
URL digitada incorretamente Informe apenas o endereço do seu workspace, com https:// e sem caminhos adicionais, por exemplo https://suaempresa.botcity.dev.
Proxy corporativo Configure o proxy nas ferramentas BotCity.
Bloqueio de firewall Peça ao time de TI a liberação dos domínios da BotCity na porta 443.
Restrição de IP no workspace Se o workspace usa a Lista de IPs permitidos da Central de Segurança, confirme que o IP de saída da máquina está liberado.
Falha de DNS ou timeout Verifique se a máquina resolve o domínio do workspace e se a rede não está interrompendo a conexão.

Testar o acesso ao Orquestrador pela própria máquina

Na máquina onde o Wizard está sendo executado, abra no navegador o endereço https://<seu-workspace>.botcity.dev/. Se a página não carregar, o problema está no acesso da máquina a Plataforma BotCity, e não na instalação.

Se o erro continuar, execute a ferramenta de diagnóstico e veja se todos os requisitos e liberações estão sendo atendidos.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Por que a instalação funciona em uma máquina (ou VDI) e falha em outra?

Por que a instalação funciona em uma máquina (ou VDI) e falha em outra?

Quando a mesma versão do Wizard funciona em uma máquina e falha em outra, inclusive em versões anteriores, a causa costuma estar no ambiente de rede dessa máquina, e não na instalação. É comum que VDIs e servidores do mesmo ambiente tenham regras diferentes de proxy, firewall ou IP de saída.

Compare as duas máquinas nos seguintes pontos:

  • Proxy: se a máquina que falha usa um proxy diferente, ou um proxy que exige autenticação.
  • Firewall: se os domínios da BotCity estão liberados para essa máquina.
  • IP de saída: se o IP dessa máquina está liberado na Lista de IPs permitidos do workspace, quando ela estiver ativa.
  • Workspace: se as duas máquinas acessam o mesmo workspace. Ambientes de homologação e produção podem ter restrições de IP diferentes.

Comparar os resultados da ferramenta de diagnóstico

Execute a ferramenta de diagnóstico nas duas máquinas e compare os testes de conectividade. A diferença entre os resultados costuma apontar a regra de rede que está bloqueando o acesso.

Depois de identificar a diferença, peça ao time de TI responsável pela máquina o ajuste necessário. Veja mais detalhes em Problemas com bloqueios do ambiente.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

O que fazer quando o Wizard.exe é bloqueado pelas políticas de segurança da empresa?

O que fazer quando o Wizard.exe é bloqueado pelas políticas de segurança da empresa?

Ao iniciar a instalação, a configuração ou a autenticação do BotCity Runner pelo Wizard em formato .exe, você pode não conseguir abrir o arquivo. Isso costuma acontecer por causa de políticas de segurança que bloqueiam a execução de arquivos executáveis, uma medida comum para evitar a propagação de malware e o uso de software não autorizado.

Para contornar a restrição, use a versão do Wizard distribuída para Linux, no formato .jar. Ela depende do Java Runtime Environment e costuma passar pelas políticas sem bloqueio:

  1. Baixe o Wizard no formato .jar, disponível na seção de downloads para Linux.
  2. Abra o arquivo .jar.
  3. Se o Wizard iniciar normalmente, siga com a instalação ou a configuração como de costume.

Se preferir continuar com o arquivo .exe, será necessário abrir uma solicitação para o time de segurança da sua empresa pedindo a liberação de execução de arquivos .exe no ambiente.

O Wizard .jar não tem limitação funcional

Usar o Wizard em .jar é perfeitamente válido e não compromete o funcionamento esperado das ferramentas. Se quiser evitar novas solicitações ao time de segurança, você pode seguir com a versão .jar sem nenhuma limitação.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como resolver o problema com a instalação das dependências ao executar a automação (ModuleNotFoundError)?

Como resolver o problema com a instalação das dependências ao executar a automação (ModuleNotFoundError)?

Ao executar a automação, o Python interrompe a execução logo no início e informa que não encontrou um pacote que você já instalou:

ModuleNotFoundError: No module named 'botcity'

Na maioria dos casos, isso significa que as dependências foram instaladas em um interpretador Python diferente daquele que executa o código. É comum que a própria IDE crie um ambiente virtual para o projeto: se as dependências forem instaladas nesse ambiente virtual, mas o código for executado com o Python "global" do sistema (ou o contrário), os pacotes não são encontrados.

Para resolver, use o mesmo interpretador nas duas etapas:

  1. Descubra qual interpretador está ativo no terminal com python -c "import sys; print(sys.executable)" e compare com o interpretador selecionado na sua IDE.
  2. Com o interpretador correto ativo, instale as dependências: pip install --upgrade -r requirements.txt.
  3. Execute a automação com esse mesmo interpretador.

Erro semelhante com outra dependência

Se você estiver tendo um problema parecido com alguma outra dependência ao executar sua automação usando o BotCity Runner, verifique se a dependência foi corretamente definida no arquivo requirements.txt do robô.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como resolver problemas de verificação do certificado SSL ao executar comandos utilizando o pip?

Como resolver problemas de verificação do certificado SSL ao executar comandos utilizando o pip?

Ao instalar dependências com o pip, manualmente ou pelo Runner, o comando falha porque o Python não consegue validar o certificado SSL da conexão com o PyPI. O erro aparece no log do Runner ou no próprio terminal:

WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] \
certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))': /simple/pip/

Could not fetch URL https://pypi.org/simple/pip/: There was a problem confirming the ssl certificate: HTTPSConnectionPool(host='pypi.org', port=443): \
Max retries exceeded with url: /simple/pip/ (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] \
certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))) - skipping

Esse cenário é comum em ambientes corporativos, onde o proxy ou o firewall da empresa intercepta a conexão e apresenta um certificado interno que o pip não reconhece. Enquanto isso não for tratado, nenhum pacote é instalado diretamente do PyPI (Python Package Index).

Para resolver, marque os domínios do PyPI como confiáveis na configuração global do pip:

pip config set global.trusted-host \
    "pypi.org files.pythonhosted.org pypi.python.org" \
    --trusted-host=pypi.python.org \
    --trusted-host=pypi.org \
    --trusted-host=files.pythonhosted.org

Com a configuração aplicada, a próxima instalação de dependências, inclusive a que o Runner faz antes de executar a tarefa, não deve mais falhar por causa do certificado.

Valide a configuração com o time de TI e segurança

Caso essa alternativa não seja suficiente, valide com o time de TI da sua empresa se essa é uma solução adequada para o seu ambiente.

Lembre-se também de verificar com o time de TI se é necessário realizar configurações adicionais com relação ao uso do pip.

Você pode encontrar mais detalhes sobre bloqueios do ambiente na seção de pré-requisitos da documentação.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como configurar um proxy autenticado para as ferramentas da BotCity?

Como configurar um proxy autenticado para as ferramentas da BotCity?

Em ambientes corporativos com proxy autenticado, que exige usuário e senha, liberar as URLs no firewall pode não ser suficiente. O Wizard, o Runner, o BotCLI, o BotCity Studio e as automações Python também precisam saber qual proxy usar e com quais credenciais para se comunicar com o Orquestrador e instalar dependências.

Para resolver, configure o proxy em dois pontos:

  • Ferramentas Java (Wizard, Runner, BotCLI e BotCity Studio): defina as propriedades de proxy da JVM, por aplicação ou pela variável de ambiente JAVA_TOOL_OPTIONS.
  • Automações Python: crie as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY no formato http://usuario:senha@host:porta. Elas são lidas pelo pip e pela biblioteca requests em qualquer ambiente virtual.

O passo a passo completo, incluindo o tratamento de caracteres especiais na senha, está no guia Configurar Proxy Autenticado nas Ferramentas BotCity.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como confiar em um certificado SSL corporativo (SSL Inspection) nas ferramentas Java e Python da BotCity?

Como confiar em um certificado SSL corporativo (SSL Inspection) nas ferramentas Java e Python da BotCity?

Em ambientes com proxy de inspeção SSL (SSL Inspection), a empresa substitui o certificado original dos servidores por um certificado emitido por uma CA interna. As ferramentas Java e Python não reconhecem essa CA e rejeitam a conexão, com erros como PKIX path building failed no Java ou CERTIFICATE_VERIFY_FAILED no Python.

Nesse cenário, configurar o trusted-host do pip não resolve o problema por completo, porque isso só afeta a instalação de pacotes. O Wizard, o Runner e o BotCity Studio continuam rejeitando o certificado.

Para resolver, registre o certificado raiz da CA interna no truststore de cada tecnologia:

  • Java (Wizard, Runner e BotCity Studio): importe o certificado no cacerts da JVM usada pelas ferramentas, com o keytool.
  • Python (requests): crie um bundle customizado a partir do certifi, com o certificado da CA interna, e aponte a variável de ambiente REQUESTS_CA_BUNDLE para ele.

O passo a passo completo está no guia Configurar Certificado SSL Corporativo.

Certificado fornecido pelo time de segurança

O certificado raiz da CA interna normalmente é fornecido pelo time de infraestrutura ou de segurança da sua empresa. Solicite o arquivo (.crt, .cer ou .pem) antes de começar a configuração.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Execução pelo Runner

Como instalar múltiplos Runners em um único ambiente de execução?

Como instalar múltiplos Runners em um único ambiente de execução?

Cada Runner executa uma tarefa por vez. Para processar mais de uma tarefa ao mesmo tempo na mesma máquina, você pode instalar vários Runners no mesmo ambiente de execução. Não há limite de quantidade, mas cada Runner precisa da sua própria instalação do BotCity Studio SDK, em uma pasta separada, e de um identificador (machineId) exclusivo.

Para configurar os Runners:

  1. Crie no Orquestrador um Runner para cada instância que será instalada, cada um com o seu próprio Label.
  2. Execute o Wizard e, na etapa Escolha onde instalar, informe uma pasta diferente para cada Runner, por exemplo BotCity\runner-01 e BotCity\runner-02.
  3. Ao final de cada instalação, clique em Setup Runner e selecione o Runner correspondente àquela pasta.
  4. Confira, no arquivo conf.bcf da pasta conf de cada instalação, se o machineId aponta para o Runner esperado.
  5. Inicie cada Runner a partir da sua própria pasta, com o script BotRunner ou BotRunner-gui.

Se preferir automatizar a configuração, use a instalação silenciosa do Wizard, repetindo o comando com os parâmetros --dir e --runner diferentes para cada instância:

wizard-x.y.z.exe install --dir "D:\BotCity\runner-01" --email "user@server.com" --runner "runner-01"
wizard-x.y.z.exe install --dir "D:\BotCity\runner-02" --email "user@server.com" --runner "runner-02"

Como cada instalação tem as suas próprias pastas bots, venvs e logs, os Runners não disputam o mesmo ambiente virtual nem misturam os registros de execução.

Automações com interface gráfica não executam em paralelo

Automações que manipulam a tela, o mouse ou o teclado compartilham a mesma sessão gráfica e entram em conflito quando executam ao mesmo tempo. Combine no máximo uma automação desse tipo com automações que rodam em segundo plano, como Web headless, integrações com APIs e processamento de arquivos. Para paralelizar automações com interface gráfica, use máquinas ou sessões separadas.

Dimensione os recursos da máquina

Cada Runner em execução consome CPU e memória RAM. Veja as referências de dimensionamento para execuções paralelas no Dimensionamento de Máquina para execução de processo via Runner.

Runners em contêineres

Se o ambiente usa Docker, você também pode subir várias instâncias do Runner com o Docker Compose, cada uma com o seu MACHINE_ID.

Veja mais em:

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como resolver o erro Python environment preparation failed ao executar uma automação pelo Runner?

Como resolver o erro Python environment preparation failed ao executar uma automação pelo Runner?

Antes de executar uma tarefa, o Runner prepara o ambiente Python do robô. Quando essa etapa falha, a tarefa não chega a ser executada e o log registra Python environment preparation failed. Três causas respondem pela maioria dos casos, e o próprio log do Runner indica qual é a sua.

1. O Runner não alcança o PyPI

No log aparecem tentativas de conexão com o pypi.org que terminam em timeout:

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ReadTimeoutError("HTTPSConnectionPool(host='pypi.org', port=443): Read timed out. (read timeout=15)")': /simple/pip/
...
Python environment preparation failed.
Error executing task: Python environment preparation failed...

Sem acesso ao PyPI, o pip install não consegue baixar os pacotes do robô. Isso é comum em ambientes corporativos com bloqueio de saída. Peça ao time de infraestrutura as liberações de firewall listadas na seção Utilizando Python no desenvolvimento.

2. O Python não está instalado corretamente na máquina

O log traz a mensagem abaixo logo após a tentativa de criar o ambiente virtual:

execAndWait - Error: Cannot invoke "java.lang.Process.waitFor()" because "this.process" is null

Nesse caso, o Python não está instalado, não está no PATH do sistema ou está sem os pacotes que o Runner usa para montar o ambiente virtual. Confirme a instalação:

python --version
where python

Se os comandos responderem, instale os pacotes necessários:

python -m pip install --upgrade pip setuptools virtualenv

3. O Runner chama o comando errado do Python

Quando a máquina tem mais de uma versão instalada, cada uma costuma responder por um comando diferente. Teste py e python no terminal para descobrir qual deles chama a versão que o robô precisa. Se for o py, informe isso ao Runner no arquivo conf.bcf, dentro da pasta conf onde o SDK da BotCity foi instalado:

pythonBinary=py

Você também pode apontar o caminho completo do executável no mesmo parâmetro, por exemplo pythonBinary=C:\\Python312\\python.exe.

Use barras duplas no caminho do Python

Ao informar o caminho completo em pythonBinary, escreva-o com barras duplas, para que a barra simples não seja interpretada como caractere de escape durante a execução.

Veja todos os parâmetros aceitos pelo conf.bcf na seção Personalizar a configuração do Runner.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como tratar o erro No pyenv.cfg file nos logs do Runner?

Como tratar o erro No pyenv.cfg file nos logs do Runner?

Esse erro aparece nos logs do Runner quando a criação do ambiente virtual do robô não é concluída: o arquivo pyenv.cfg, que identifica o ambiente, não foi gerado ou ficou incompleto.

Comece sempre pelo log do Runner para confirmar a mensagem. Se ele não for suficiente para identificar a causa, inclua debugEnabled=true no arquivo conf.bcf para gerar uma saída de log mais detalhada e reproduza o problema. O parâmetro está disponível a partir da versão 2.7.0 do Runner e é descrito na seção Personalizar a configuração do Runner.

Com o log em mãos, verifique as causas mais comuns:

Causa provável O que verificar
Arquivo setup.py na pasta do projeto Renomeie o setup.py e execute a tarefa novamente.
Criação do ambiente interrompida por falta de memória RAM, falta de espaço em disco, timeout ou falta de permissão Confira os recursos da máquina e a permissão de escrita na pasta de destino. Nesses casos, a pasta do ambiente virtual pode até ser criada, mas com arquivos pendentes.
Bloqueio por antivírus ou EDR Crie o ambiente virtual manualmente na pasta de destino para confirmar se existe algum bloqueio.
Limpeza da pasta por outra ferramenta Verifique se alguma ferramenta de limpeza atua sobre a pasta de destino.
Dois Runners criando o ambiente na mesma pasta Garanta que apenas um Runner trabalhe sobre o mesmo ambiente virtual.
Ambiente criado com uma versão do Python diferente da atual Confirme se a versão do Python em uso na máquina é a mesma que gerou o ambiente virtual.

Onde ficam os ambientes virtuais

Os ambientes virtuais são criados no diretório de instalação do SDK, dentro da pasta venvs. Se o SDK foi instalado em Documentos, por exemplo, o caminho será C:\Users\{nome_usuario}\Documents\BotCity\venvs\. Veja a estrutura completa de pastas na seção Explorando o Conteúdo.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

O que fazer quando o Runner parece ficar travado após puxar uma tarefa para execução?

O que fazer quando o Runner parece ficar travado após puxar uma tarefa para execução?

Em situações esporádicas, o Runner puxa uma nova tarefa, mas a execução não começa: o status fica em Executing task... até que o Runner seja reiniciado.

Na maior parte dos casos, a causa são recursos da execução anterior que não foram finalizados corretamente. Quando o código tenta usar esses recursos de novo, o sistema operacional os considera "em uso" e a nova execução não avança. O exemplo mais comum é o WebDriver em automações Web: sem o encerramento adequado, ele continua em execução mesmo depois que o processo termina e afeta as execuções seguintes.

Para resolver, garanta no código que todo recurso alocado pelo robô seja liberado ao final da execução, inclusive quando ocorre uma exceção. Em automações Web, isso significa encerrar o navegador com bot.stop_browser(), conforme a seção Pare o navegador, de preferência dentro de um bloco finally, para que a limpeza aconteça mesmo quando o robô falha no meio do processo.

Sempre verifique se todos os recursos usados na execução foram devidamente encerrados, com ambiente limpo ao fim de cada execução, o Runner consegue iniciar a tarefa seguinte sem conflito com os recursos anteriores.

Consultando o log.txt do Runner

Você também pode sempre consultar o arquivo log.txt gerado pelo Runner para verificar eventuais exceções lançadas durante a preparação do ambiente e a execução do processo.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como corrigir uma tarefa que ficou com o status incorreto no Orquestrador?

Como corrigir uma tarefa que ficou com o status incorreto no Orquestrador?

A tarefa continua no Orquestrador com um status que não corresponde à realidade, normalmente Executando, mesmo sem nenhuma execução em andamento no Runner.

O Runner tem um tratamento interno que finaliza a tarefa em estado de erro quando a falha não é reportada pelo código ou quando há um cancelamento forçado. Esse tratamento não é acionado quando o Runner é encerrado de forma abrupta, por exemplo em um reinício ou desligamento da máquina sem fechar o Runner antes. É nesse cenário que o status fica desatualizado.

O status incorreto não afeta as execuções seguintes, o impacto é apenas visual e administrativo. Para corrigi-lo, finalize a tarefa pelo BotCLI, que acompanha o BotCity Studio SDK:

  1. Abra um terminal na pasta onde o SDK foi instalado.
  2. Copie o ID da tarefa no Orquestrador, disponível em Informações da tarefa.
  3. Execute o comando abaixo, trocando 123 pelo ID copiado e número de tarefas processadas:
./BotCLI task finish -taskId "123" -totalItems 1 -processedItems 1 -failedItems 0

O comando finaliza a tarefa e atualiza os indicadores de itens totais, processados com sucesso e com falha, de forma que ela deixe de aparecer como Executando na fila.

Outros argumentos do comando

O task finish também aceita uma mensagem de finalização e o tipo de conclusão (SUCCESS, FAILED ou PARTIALLY_COMPLETED). Veja todos os argumentos na seção task finish e a sintaxe geral da ferramenta em Primeiros Passos.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Ambientes remotos e sessões RDP

O que fazer ao receber o erro OSError: screen grab failed ao executar uma automação utilizando o Runner em um ambiente remoto?

O que fazer ao receber o erro OSError: screen grab failed ao executar uma automação utilizando o Runner em um ambiente remoto?

O erro aparece quando a automação usa visão computacional para encontrar elementos na tela, mas a conexão remota com a máquina de execução já foi encerrada. Sem ninguém conectado, o sistema operacional deixa a tela preta, e o robô não consegue capturar a tela para procurar os elementos gráficos.

A saída é garantir que a máquina tenha uma sessão gráfica ativa no momento da execução. Você tem duas opções.

1. Scripts de sessão do BotCity SDK

A BotCity distribui dois scripts que desconectam a sessão atual do usuário e a redirecionam para uma sessão de terminal, mantendo a sessão e a interface gráfica ativas para o Runner. Eles ficam na pasta do SDK e são indicados no arquivo de configuração do Runner: use o parâmetro startup para executá-los quando o Runner inicia, ou beforeTask para executá-los antes de cada tarefa.

Script Onde fica O que faz
startup.bat Pasta startup Desconecta a sessão atual e a redireciona para uma sessão de terminal.
console_session.bat Pasta scripts Faz o mesmo redirecionamento e ainda define uma resolução de tela específica para a nova sessão.

Veja o uso e a implementação de cada um na seção Mantendo a sua sessão remota ativa.

2. BotCity Session Manager

Em vez de manter a sessão aberta o tempo todo, o Session Manager ativa a sessão na máquina remota conforme as tarefas entram na fila do Orquestrador e a desativa quando não há mais nada para executar. A interface gráfica fica disponível durante a execução, sem sessão ociosa depois dela, o que também reduz o custo das máquinas e atende às políticas de segurança que limitam sessões de usuário ativas.

Veja o que a ferramenta faz em BotCity Session Manager e como configurá-la em Primeiros Passos.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como encontrar elementos usando visão computacional em conexões remotas?

Como encontrar elementos usando visão computacional em conexões remotas?

Por motivos de segurança, é comum que o cliente não permita o acesso direto ao ambiente, e a automação precise ser construída através de uma conexão remota. Nesse cenário, o robô encontra os elementos em uma conexão e deixa de encontrá-los na seguinte.

O motivo é que a imagem capturada muda de uma conexão para outra. Se a resolução da sessão RDP for adaptativa, ou se a qualidade da conexão for definida automaticamente pela velocidade da rede, cada sessão apresenta a tela de um jeito um pouco diferente, e as imagens capturadas no BotCity Studio deixam de corresponder ao que aparece na tela.

Para que as capturas sejam constantes entre as conexões, configure a sessão RDP antes de mapear os elementos:

  1. No cliente de conexão remota, clique em Mostrar opções.
  2. Na aba Exibir, defina uma resolução fixa, em vez de uma opção adaptativa como tela cheia.
  3. Na aba Experiência, escolha um parâmetro fixo de qualidade, em vez de deixar a detecção automática pela velocidade da conexão.

Recapture os elementos após alterar a conexão

Qualquer mudança nas configurações de resolução ou experiência altera a imagem da tela. Sempre atualize os elementos visuais no BotCity Studio capturando-os novamente depois de ajustar o acesso remoto, caso contrário as imagens antigas não serão encontradas.

Com a resolução fixa, você consegue capturar a tela pelo BotCity Studio e usar os métodos de visão computacional do Framework Desktop para manipular uma aplicação que está executando no ambiente remoto.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

O que fazer quando o script de startup retorna Session not found?

O que fazer quando o script de startup retorna Session not found?

O script que deveria desconectar a sessão do usuário e redirecioná-la para o console falha com a mensagem Session not found, e a sessão continua como estava.

A causa costuma ser um nome de usuário com espaços, como USER NAME. O script console_session.bat, que fica na pasta scripts do BotCity Studio SDK, localiza a sessão ativa pelo nome do usuário:

FOR /F "skip=1 tokens=3 usebackq" %%X in (`query session %USERNAME%`) DO tscon %%X /dest:console
powershell.exe -Command Set-DisplayResolution -Width 1600 -Height 900 -Force

Com um nome composto, o espaço quebra a consulta do query session e não sobra nenhum ID de sessão para o tscon redirecionar.

Para resolver, troque %USERNAME% pelo coringa %User*Name% na primeira linha do script, mantendo o restante como está:

FOR /F "skip=1 tokens=3 usebackq" %%X in (`query session %User*Name%`) DO tscon %%X /dest:console
powershell.exe -Command Set-DisplayResolution -Width 1600 -Height 900 -Force

O coringa localiza a sessão mesmo quando o nome tem espaços ou outros caracteres especiais. O trecho skip=1 tokens=3 continua extraindo o ID da sessão, e o tscon a redireciona para o console.

Variação para o startup.bat

O startup.bat, que fica na pasta startup do SDK, faz o mesmo redirecionamento por PowerShell:

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "$sessionid=((quser $env:USERNAME | select -Skip 1) -split '\s+')[2]; tscon %sessionname% /dest:console"

Nesse script, o tscon usa a variável %sessionname%, e não o resultado do quser, então um nome de usuário com espaços não impede o redirecionamento. A consulta do quser alimenta apenas a variável $sessionid, que o script não chega a utilizar.

Se você adaptou o startup.bat para usar o $sessionid

Um nome de usuário composto ocupa duas colunas na saída do quser e desloca as posições do -split. Nesse caso, o índice [2] deixa de apontar para o ID da sessão e precisa ser ajustado conforme a saída do comando na sua máquina.

Veja o conteúdo original dos scripts e como indicá-los na configuração do Runner nas seções Script de desconexão de sessão e Script de configuração do ambiente.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como configurar a codificação para evitar problemas na digitação de caracteres em sessões RDP no MacOS?

Como configurar a codificação para evitar problemas na digitação de caracteres em sessões RDP no MacOS?

O robô digita o texto na VM, mas os caracteres maiúsculos e os caracteres especiais saem errados ou simplesmente não aparecem. O caso típico é o método kb_type() do Framework Desktop, usado em um processo que roda em uma VM acessada pelo MacOS.

A causa está na codificação de teclado que o Microsoft Remote Desktop do MacOS usa por padrão na sessão RDP: ela não corresponde ao que a VM espera receber, e parte das teclas enviadas pelo robô se perde no caminho.

Para corrigir, altere a codificação no aplicativo do Microsoft Remote Desktop:

  1. Acesse a aba Connections.
  2. Marque a opção Keyboard Mode > Unicode.

Tela de configurações do Microsoft Remote Desktop no MacOS com a opção Keyboard Mode definida como Unicode.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Desenvolvimento de automações

O que fazer quando a tecla Print Screen não faz a captura da screenshot no BotCity Studio?

Você pressiona Print Screen para trazer a tela da aplicação para a guia UI do Studio, como descrito em Trazendo tela de interação para o BotCity Studio, mas a captura não é carregada.

Na maioria das vezes, outra aplicação em execução está interceptando a tecla Print Screen e o BotCity Studio não chega a receber a imagem.

Comece verificando a própria tecla:

  • Confirme que o Print Screen está ativo e funcional em outras aplicações da máquina.
  • Feche ou desabilite programas que capturam a tela e podem estar interceptando a tecla.

Se a tecla continuar indisponível, use uma das alternativas de captura:

Alternativa Descrição
Botão de captura no Studio Além do Print Screen, você também pode capturar a tela pelo botão no menu superior direito do BotCity Studio.
Atalho de teclado personalizado O Studio permite configurar outra tecla ou combinação para a captura. Veja como em Atalho de captura personalizado.
Extensão para o VSCode O BotCity Studio também está disponível como extensão para instalar direto no VSCode. Veja mais em Studio para Visual Studio Code.

No macOS a tecla é outra

No macOS, a captura não é feita com o Print Screen, e sim com a tecla F9, por limitação do próprio sistema operacional.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Por que o navegador Edge não inicia quando a automação é executada pelo Orquestrador?

Por que o navegador Edge não inicia quando a automação é executada pelo Orquestrador?

A automação Web com o Microsoft Edge executa normalmente na execução local, mas falha quando o robô é executado pelo Orquestrador. O navegador não chega a abrir e a execução para com a seguinte mensagem no log:

Message: session not created: probably user data directory is already in use, please specify a unique value for --user-data-dir argument, or don't use --user-data-dir

Apesar do texto apontar para o diretório de perfil, o comportamento vem de um bug do Selenium, reportado na issue #15340 do repositório oficial: o Edge tenta relançar os próprios processos pela camada de compatibilidade, e o relançamento é que falha. Por isso o erro aparece nas execuções controladas pelo Runner e não no ambiente local.

Versões em que o problema foi reportado

A issue foi aberta com o Selenium na versão 4.29.0, o Edge e o msedgedriver na versão 133.0.3065.82, em Windows 10. Até o momento não há uma versão do Selenium indicada como correção, então mantenha o argumento aplicado mesmo depois de atualizar o navegador ou o driver. Acompanhe a issue para verificar se a situação mudou.

Para contornar, adicione o argumento --edge-skip-compat-layer-relaunch às opções do navegador, seguindo o mesmo formato da seção Personalizando as opções do navegador:

def_options = default_options(
    headless=bot.headless,
    download_folder_path=bot.download_folder_path,
    user_data_dir=None,  # Informar 'None' aqui irá gerar um diretório temporário
)

# Impede que o Edge relance os processos pela camada de compatibilidade
def_options.add_argument("--edge-skip-compat-layer-relaunch")

bot.options = def_options

Com o argumento aplicado, os robôs voltam a executar no ambiente orquestrado, sem precisar alterar configurações locais ou políticas de execução da máquina.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Como resolver o erro de certificado SSL ao conectar ao Orquestrador pelo código Python?

Como resolver o erro de certificado SSL ao conectar ao Orquestrador pelo código Python?

O robô falha ao se conectar ao Orquestrador pelo BotMaestroSDK porque o Python não reconhece o certificado SSL apresentado na conexão. Normalmente o log mostra um SSLError com a mensagem CERTIFICATE_VERIFY_FAILED.

Esse cenário é comum em ambientes corporativos, onde o servidor usa um certificado autoassinado ou o proxy da empresa intercepta o tráfego e apresenta um certificado emitido por uma CA interna.

Para contornar, desative a validação do certificado logo depois de instanciar o SDK, antes de qualquer chamada ao Orquestrador:

from botcity.maestro import BotMaestroSDK

maestro = BotMaestroSDK.from_sys_args()
maestro.VERIFY_SSL_CERT = False  # Ignora a validação do certificado

Versão mínima do SDK

Para que a flag VERIFY_SSL_CERT funcione corretamente, a dependência botcity-maestro-sdk precisa estar na versão 0.7.0 ou superior.

Desativar a validação reduz a proteção da conexão

Com VERIFY_SSL_CERT = False, o robô deixa de validar o certificado apresentado pelo servidor. Valide com o time de segurança da sua empresa se essa solução é adequada para o seu ambiente. A alternativa mais segura é fazer a máquina de execução confiar no certificado interno, como mostra o guia Configurar Certificado SSL Corporativo.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Acesso, SSO e gestão de usuários

A Plataforma BotCity suporta SSO?

A Plataforma BotCity suporta SSO?

Sim. Com o SSO (Single Sign-On) habilitado, os usuários acessam a plataforma com as credenciais que já usam no provedor de identidade (IdP) da empresa, sem precisar de uma senha separada para a Plataforma BotCity.

Você pode configurar um ou mais provedores, entre as opções:

  • IdPs sociais: Microsoft e Google.
  • IdPs definidos pelo usuário: SAML v2.0 e OpenID Connect v1.0, que atendem provedores como Microsoft Entra ID, Okta e Google Workspace.

A configuração é feita em Central de Segurança > SSO > Configuração de provedor.

Veja o passo a passo de cada provedor na seção SSO (Single Sign-On).

Somente administradores configuram o SSO

Apenas usuários com o papel de Administrador dentro de Organização têm acesso às configurações de SSO.

SSO e contas locais podem coexistir

Na aba Contas locais, você define se os usuários cadastrados com e-mail e senha continuam acessando a plataforma junto com o SSO. Ao desabilitar as contas locais, quem acessava exclusivamente por e-mail e senha perde o acesso. O mesmo vale ao desabilitar o SSO para quem acessava exclusivamente por ele.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Qual opção de SSO usar com o Microsoft Entra ID?

Qual opção de SSO usar com o Microsoft Entra ID?

Você pode integrar o Microsoft Entra ID de três formas, todas configuradas em Central de Segurança > SSO:

Opção Descrição
Microsoft (IdP social) Integração nativa. Exige um App Registration no Azure, com ID do Cliente e Segredo do Cliente.
OpenID Connect v1.0 Integração via OIDC, com a Discovery Endpoint URL e o arquivo .json de configuração do IdP.
SAML v2.0 Integração via SAML, com o arquivo .xml de configuração do IdP. Exige atenção ao mapeamento do claim de e-mail.

Qualquer uma delas faz a autenticação dos usuários. A opção Microsoft é a mais simples de configurar, porque dispensa o mapeamento manual de claims.

Veja como fazer a configuração de provedor.

Autenticação, não autorização

Nenhuma das opções define papéis ou grupos na plataforma.

Veja mais em:

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Preciso cadastrar o usuário na plataforma antes do primeiro login via SSO?

Preciso cadastrar o usuário na plataforma antes do primeiro login via SSO?

Sim. Hoje não há provisionamento automático de usuários, então o usuário precisa existir na plataforma antes do primeiro acesso via SSO.

A BotCity associa a conta do IdP à conta da plataforma pelo e-mail. Por isso, o e-mail cadastrado na BotCity precisa ser idêntico ao e-mail que o IdP envia na autenticação.

Para liberar o acesso:

  1. Acesse Organização > Usuários e Grupos e clique em Convidar usuário.
  2. Informe o e-mail do usuário, defina os papéis e habilite a opção SSO.
  3. Peça ao usuário para fazer o login via SSO.

Veja mais em:

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

O que fazer quando o login via SSO redireciona para a página user-not-found?

O que fazer quando o login via SSO redireciona para a página user-not-found?

Esse comportamento indica que a autenticação no IdP funcionou, mas a BotCity não encontrou um usuário com o e-mail recebido. A plataforma encerra a sessão no IdP (no Microsoft Entra ID, aparece a tela de Sign Off Redirect) e redireciona para um endereço como:

https://<seu-workspace>.botcity.dev/sso/user-not-found

As causas mais comuns são:

  • Usuário não cadastrado: o usuário ainda não existe na plataforma.
  • E-mail vazio na asserção: o IdP não está enviando o atributo de e-mail.
  • E-mail diferente: o IdP envia outro valor, como o UPN (usuario@empresa.onmicrosoft.com) ou um alias, em vez do e-mail cadastrado na BotCity.

Se você usa SAML v2.0 com o Microsoft Entra ID, abra o Enterprise Application em Single sign-on > Attributes & Claims e verifique se:

  1. O Unique User Identifier (Name ID) está mapeado para user.mail, ou para o atributo que contém exatamente o e-mail cadastrado na BotCity.
  2. O claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress existe e está mapeado para user.mail.
  3. O atributo mail do usuário está preenchido no Entra ID e é igual ao e-mail cadastrado na BotCity, incluindo domínio e alias.
  4. O usuário está atribuído ao Enterprise Application, em Users and groups.

Veja mais em:

Conferir quais atributos chegam na asserção SAML

Se o erro continuar, capture o login com a extensão SAML-tracer e confira o e-mail enviado na SAML Response.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

O SSO da BotCity controla os papéis e grupos de acesso dos usuários?

O SSO da BotCity controla os papéis e grupos de acesso dos usuários?

Não. Hoje, o SSO (OpenID Connect v1.0, SAML v2.0 ou os IdPs sociais Microsoft e Google) faz apenas a autenticação do usuário. A autorização continua sendo administrada manualmente dentro da plataforma, com três recursos que funcionam em conjunto:

  • Papéis: definem o que o usuário pode fazer na Organização e em cada produto da Plataforma BotCity, como o Orquestrador e o Insights. Os papéis disponíveis variam por módulo, entre Administrador, Gerente, Desenvolvedor e Operador.
  • Grupos: reúnem os usuários de um mesmo time, setor ou área. Um usuário pode pertencer a vários grupos e acumula os acessos de cada um deles.
  • Repositórios: agrupam recursos do Orquestrador, como automações, robôs, credenciais e logs de execução. Cada repositório dá acesso a um ou mais grupos, e somente os usuários desses grupos visualizam e operam os recursos vinculados a ele.

Na prática, o papel define o que o usuário pode fazer, e a combinação entre grupos e repositórios define sobre quais recursos ele pode fazer. Papéis e grupos são atribuídos em Organização > Usuários e Grupos, e o acesso dos grupos aos repositórios é configurado em Organização > Repositórios.

Veja mais em:

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

É possível usar os grupos do provedor de identidade (IdP) para atribuir papéis e acessos na BotCity?

É possível usar os grupos do provedor de identidade (IdP) para atribuir papéis e acessos na BotCity?

Ainda não. Se o seu IdP (Microsoft Entra ID, Okta, Google Workspace etc.) enviar um claim de grupos no token ou na asserção SAML, esse atributo é ignorado. Ele não define o papel nem os grupos do usuário na plataforma BotCity.

A plataforma passará a aceitar os grupos do IdP como fonte de verdade para papéis e acessos, de duas formas complementares:

  • Sincronização no login: a cada autenticação, o IdP informa os grupos do usuário e a BotCity aplica o papel e os acessos correspondentes, conforme um mapeamento definido pela sua empresa. Alterações feitas no IdP passam a valer no login seguinte.
  • Provisionamento automático via SCIM: criação, alteração e remoção de usuários, assim como a associação entre usuários e grupos, são replicadas na Plataforma BotCity em tempo real, sem depender de um novo login.

Para usar esse recurso, será preciso:

  1. No IdP, habilitar o envio dos grupos do usuário no token de autenticação e, para SCIM, configurar a conexão de provisionamento com a BotCity.
  2. Na BotCity, definir o mapeamento entre os grupos do IdP e os papéis e grupos da plataforma.

Previsão de disponibilidade

O recurso está em desenvolvimento e estará disponível em breve. Até lá, gerencie papéis e grupos em Usuários e Grupos.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

A BotCity suporta SCIM 2.0?

A BotCity suporta SCIM 2.0?

Ainda não. O provisionamento automático via SCIM está em desenvolvimento e estará disponível em breve.

Com o SCIM, a criação, a alteração e a remoção de usuários e a associação entre usuários e grupos no IdP passarão a ser replicadas na BotCity em tempo real. Na prática, desligamentos e mudanças de área serão refletidos de imediato nos acessos à plataforma.

Previsão de disponibilidade

O recurso está em desenvolvimento e estará disponível em breve. Até lá, gerencie papéis e grupos em Usuários e Grupos.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Existe API para gerenciar usuários e papéis na BotCity?

Existe API para gerenciar usuários e papéis na BotCity?

Não. Hoje a Plataforma BotCity não tem rota de API para criar, desativar ou remover usuários, nem para atribuir papéis por produto. A administração de usuários e permissões é feita manualmente, em Organização > Usuários e Grupos.

Para automatizar a concessão e a revogação de acessos a partir da sua ferramenta de gestão de identidade, o caminho previsto é o provisionamento via SCIM, que estará disponível em breve.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Orquestrador e planos

Quais são os recursos e limitações de uma conta Community no Orquestrador BotCity?

Quais são os recursos e limitações de uma conta Community no Orquestrador BotCity?

Uma nova conta criada no Orquestrador BotCity tem acesso total às funcionalidades da plataforma durante os primeiros 30 dias, o período de trial. Encerrado esse prazo, parte das funcionalidades é desabilitada e outra parte passa a ter limite de uso.

Funcionalidades desabilitadas:

Recursos que passam a ter limite de uso:

Os valores desses limites dependem do seu contrato, então não existe um número único que valha para todas as contas. Para consultar os limites que se aplicam à sua organização, acesse a página Conta e Planos no Orquestrador, que mostra o plano vinculado e os limites de automações e Runners.

Para confirmar as condições do seu contrato, ou avaliar um upgrade, fale com o seu representante comercial.

As limitações valem apenas para a orquestração

As limitações de uma conta Community são voltadas para a parte de orquestração.

A etapa de desenvolvimento das automações não possui nenhum tipo de limitação com relação ao uso dos frameworks e plugins open source da BotCity, nem ao uso das ferramentas do BotCity Studio para visão computacional e inspector Web e Windows.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Por quanto tempo os dados históricos das automações ficam armazenados?

Por quanto tempo os dados históricos das automações ficam armazenados?

O período de retenção vale para os dados históricos que as automações geram na plataforma:

Por quanto tempo esses dados continuam disponíveis depende do contrato da sua organização, então não existe um período único que valha para todas as contas.

Para confirmar a retenção que se aplica a você, consulte o plano vinculado à sua organização na página Conta e Planos do Orquestrador e valide o período contratado com o seu representante comercial. É essa conversa que vale também quando a operação precisa de um histórico mais longo por exigência regulatória ou de auditoria.

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.

Aprendizado e conteúdos

Onde posso encontrar conteúdos para aprender mais sobre o uso da BotCity?

Onde posso encontrar conteúdos para aprender mais sobre o uso da BotCity?

O material de aprendizado está distribuído entre cursos, tutoriais e canais da comunidade. O melhor ponto de partida depende do que você precisa no momento.

Para o primeiro contato com a plataforma, faça os cursos do Academy. Eles são gratuitos e só exigem uma conta BotCity.

Para construir uma automação do começo ao fim, siga os tutoriais do portal de documentação:

Para acompanhar novidades e trocar experiências, use os canais abertos:

Ainda precisa de ajuda?

Se isso não resolver o seu caso ou sua pergunta não está listada aqui, abra um chamado com o time de suporte.