BotCity Studio SDK¶

O BotCity Studio SDK é um pacote completo, que contém todas as ferramentas necessárias para construir, implantar e executar suas automações BotCity.

Inclui as ferramentas BotCity Studio, BotCity Runner, BotCity CLI (interface de linha de comando) e Session Manager.

O procedimento de instalação do BotCity Studio SDK é muito simples e consiste em apenas duas etapas principais:

Baixar e descompactar o BotCity Wizard
Siga as instruções na tela

Download¶

O Wizard pode ser baixado diretamente do BotCity Orquestrador, acessando a página do Studio.

Essa página pode ser encontrada em:

Com a página do Studio aberta, selecionar a opção compatível com o seu sistema operacional.

Download para Windows
Download para Linux
Download para MacOS

Após o download ser concluído, faça a extração dos arquivos e você terá acesso a duas ferramentas: Diagnostic e Wizard.

Ferramenta de Diagnóstico¶

A ferramenta BotCity - Diagnostic acompanha o pacote do Wizard e tem como objetivo principal validar se o seu ambiente atende aos pré-requisitos para a instalação e utilização do BotCity Studio SDK.

Com essa ferramenta é possivel verificar:

Conectividade com o BotCity Orquestrador
Versão do Java (Runtime e Development) instalada
Versão do Python instalada

Para obter o diagnóstico do seu ambiente, basta executar o diagnostic.jar, fornecer as credenciais solicitadas e clicar em Run Tests. Com isso, você terá um retorno detalhado em tres colunas: Test, Result e Notes.

O resultado dos testes deve ser parecido com o abaixo:

Aviso

Caso receba o resultado FAIL em algum teste de conexão, possivelmente você deve estar tentando fazer a instalação em um ambiente de bloqueio, verifique a descrição na coluna Notes.

Neste caso, é necessário solicitar ao time responsável as liberações descritas na seção pré-requisitos.

Você também pode exportar os resultados dos testes para um arquivo CSV, através do botão Export e falar com o time de suporte clicando no botão Talk to a Specialist.

Informação

Essa é uma ferramenta completamente opcional, você pode utilizá-la caso ache necessário, ou caso perceba algum impedimento na instalação ou utilização das ferramentas BotCity.

Instalar com Wizard¶

Para a instalação, utilize o arquivo chamado wizard-X.Y.Z onde X.Y.Z representa a versão do Wizard.

A instalação pode ser feita de duas formas:

Instalar via GUI (interface gráfica)
Instalar via linha de comando (instalação silenciosa)

Instalando via GUI (interface gráfica)¶

Através da interface gráfica, o Wizard irá guiá-lo por cada etapa do processo de instalação de forma intuitiva, veja o exemplo abaixo:

Escolha onde instalar¶

Aviso

Esteja ciente de que a instalação em locais como C:\... pode causar problemas de permissão.

Tente evitar esses locais ou certifique-se de corrigir as permissões conforme necessário.

Autenticando com o BotCity Orquestrador¶

Aviso

Para Server, certifique-se de sempre usar a sua URL do BotCity Orquestrador.

Se você tiver um subdomínio personalizado, é muito provável que sua URL seja algo como https://suaempresa.botcity.dev.

Para a versão da comunidade, use https://developers.botcity.dev.

Uma nova página será aberta no seu navegador, permitindo que você faça login na sua conta.

Se você tiver várias organizações sob a mesma conta, será solicitado a selecionar uma.

Quase pronto¶

Aguarde enquanto o download termina e o SDK está sendo configurado.

Finalizado 🚀¶

Dica

Uma cópia do Wizard agora está disponível na pasta em que o SDK foi instalado. Você pode sempre iniciá-lo a partir daí e voltar a esta tela.

Configurando um BotCity Runner¶

Após finalizar a instalação do SDK, você poderá configurar um Runner no seu ambiente de execução através da opção Setup Runner.

É possível escolher um Runner que já existe no seu workspace do Orquestrador ou criar um novo.

Se esta é a primeira vez que você está instalando, recomendamos criar um novo Runner para que você possa executar suas automações.

Dica

Veja mais detalhes na seção Configurando um Runner.

Ações do BotCity Wizard¶

Aqui estão algumas ações que você pode executar a partir da tela inicial do Wizard:

Change version: Alterar a versão para uma versão mais recente ou anterior, bem como para uma versão de desenvolvimento
Launch Studio: Iniciar o BotCity Studio
Setup Runner: Configurar um BotCity Runner
Runner - GUI: Iniciar o BotCity Runner como um aplicativo visual (GUI)
Launch Runner: Iniciar o BotCity Runner como um processo em segundo plano
Folder sdk: Abrir a pasta em que o SDK foi instalado
Go to Orquestrador: Abrir o BotCity Orquestrador no navegador padrão
Talk to a Specialist:: Abrir o canal de suporte da BotCity

Instalando via linha de comando (instalação silenciosa)¶

Outra forma de instalar o SDK é por linha de comando, informando os parâmetros necessários para a instalação.

Comandos de instalação¶

Podemos fazer a instalação, usando o comando wizard install e informando alguns parâmetros.

O comando mais simples possível é aquele que informamos apenas os parâmetros obrigatórios email e password, os quais são utilizados para autenticação no Orquestrador BotCity.

wizard install 
  --email "user@server.com"
  --password "bot32r$3usr74"

Dica

Pode ser necessário informar a versão do wizard no comando, caso ele não seja encontrado. wizard-X.Y.Z install ...
Para sistemas Linux e macOS adicionar o comando java -jar antes do comando wizard. java -jar wizard-X.Y.Z.jar install ...

Para fazer a instalação completa, com todos os parâmetros, podemos usar o seguinte comando:

wizard install 
  --dir "C:\BotCity"
  --server "https://developers.botcity.dev"
  --email "user@server.com"
  --password "bot32r$3usr74"
  --organization "superbots"
  --runner "vm-01"

Tabela de parâmetros para o comando de instalação:

Opção	Obrigatório	Definição	Valor Padrão
dir	Não	Pasta onde o SDK será instalado	Depende do sistema operacional
server	Não	URL do Orquestrador BotCity Orquestrador	https://developers.botcity.dev
email	Sim	Email da conta de usuário
password	Sim	Senha da conta de usuário
organization	Não	Organization a ser usada (label)	Primeira organization da lista
runner	Não	Runner a ser configurado (machineId)	Vazio

Comandos de atualização¶

Para atualizar as configurações do SDK, podemos usar o comando wizard update informando sempre o parâmetro password, os demais parâmetros são opcionais. Além dos parâmetros de instalação, podemos informar o parâmetro version para atualizar a versão do SDK.

Aviso

Quando o parâmetro version não for informado, sempre será atualizado para a versão mais recente do SDK.

Podemos informar apenas um parâmetro opcional como no exemplo abaixo (inclui a atualização de versão):

wizard update
  --password "bot32r$3usr74"
  --runner "vm-01"

Ou fazer uma atualização completa, com todos os parâmetros como no seguinte exemplo:

wizard update 
  --server "https://developers.botcity.dev"
  --email "user@server.com"
  --password "bot32r$3usr74"
  --organization "superbots"
  --runner "vm-01"
  --version "v2.16.5"

Dica

A versão do SDK pode ser verificada no arquivo setup.json na pasta onde o SDK foi instalado.

Com esse comando não podemos alterar o local de instalação do SDK, para isso é necessário refazer a instalação.

Tabela de parâmetros para o comando de atualização:

Opção	Obrigatório	Definição	Valor Padrão
server	Não	URL do Orquestrador BotCity Orquestrador	Mantém o instalado
email	Não	Email da conta de usuário	Mantém o instalado
password	Sim	Senha da conta de usuário
organization	Não	Organization a ser usada (label)	Mantém o instalado
runner	Não	Runner a ser configurado (machineId)	Mantém o instalado
version	Não	Versão a ser instalada	Versão mais recente

Explorando o Conteúdo¶

Depois de finalizar a instalação do SDK utilizando uma das formas acima, você encontrará a seguinte estrutura de pastas:

WindowsLinux e MacOS

.
├── bin
├── bots
├── conf
│   ├── conf.bcf
│   └── properties.json
├── logs
├── probes
├── run
├── scripts
├── startup
├── venvs
├── win32
│   └── java
├── .cookieCli
├── .workspaceCli
├── BotCLI.bat
├── BotRunner.bat
├── BotRunnerBackgroundWrapper.bat
├── BotRunner-gui.bat
├── BotStudio.exe
├── diagnostic.jar
├── install.log
├── setup.json
└── wizard-X.Y.Z.exe

.
├── .cookieCli
├── .workspaceCli
├── bin
├── BotCLI.sh
├── BotRunner-gui.sh
├── BotRunner.sh
├── bots
├── BotStudio.sh
├── conf
│   ├── conf.bcf
│   └── properties.json
├── diagnostic.jar
├── install.log
├── logs
├── probes
├── run
├── scripts
├── setup.json
├── startup
├── venvs
└── wizard-X.Y.Z.jar

Na pasta raiz do SDK, você encontrará os seguintes arquivos:

.cookieCli: arquivo de cookie de sessão do BotCity CLI.
.workspaceCli: arquivo de workspace utilizado pelo CLI.
bin: pasta contendo os arquivos binários .jar referentes ao BotCity SDK.
BotCLI.bat/BotCLI.sh: atalho para utilizar o BotCity CLI (ferramenta de interface de linha de comando).
BotRunner-gui.bat/BotRunner-gui.sh: atalho para iniciar o BotCity Runner no modo gráfico.
BotRunner.bat/BotRunner.sh: atalho para iniciar o BotCity Runner no modo headless (background).
bots: pasta de cache de bots (uso interno do BotCity Runner).
BotStudio.exe/BotStudio.sh: atalho para iniciar o BotCity Studio.
conf: pasta contendo os arquivos de configuração.
- conf.bcf: arquivo de configuração do BotCity Studio.
- properties.json: arquivo de propriedades do BotCity Studio (use o menu de 'Preferências' para editar os valores ao invés de alterar diretamente este arquivo).
diagnostic.jar: ferramenta para validar os pré-requisitos do ambiente para utilizar as ferramentas BotCity.
install.log: arquivo de log da instalação produzido pelo Wizard.
logs: pasta de armazenamento de logs do BotCity Runner.
probes: pasta com informações de horário de comunicação do Runner com o Orquestrador.
run: pasta utilizada pelo BotCity Runner durante a execução.
scripts: pasta para armazenar scripts que podem ser executados pelo BotCity Runner.
setup.json: arquivo contendo as informações da instalação, como a versão do SDK instalada e as credenciais de acesso utilizadas.
startup: pasta contendo um script que pode ser executado pelo BotCity Runner ao ser inicializado.
venvs: pasta utilizada pelo BotCity Runner para gerenciar os ambientes virtuais das automações Python.
win32: pasta contendo a versão do Java utilizada pelo SDK.
wizard-X.Y.Z.exe/wizard-X.Y.Z.jar: cópia do BotCity Wizard criada dentro da pasta de instalação.

Configuração¶

A configuração do BotCity Studio SDK é feita através do arquivo conf.bcf localizado no diretório "conf".

Usando o Wizard, esse arquivo é gerado automaticamente para você, mas você ainda pode personalizá-lo de acordo com suas próprias necessidades.

Vamos dar uma olhada no conteúdo do arquivo conf.bcf:

server=https://developers.botcity.dev
workspace=<Your Workspace Here>
key=<Your Key Here>
login=<Your Login Here>
machineId=<Your Machine ID Here>
logScreen=true
logApplication=true

server: URL do servidor do BotCity Orquestrador.
workspace: Espaço de trabalho do BotCity Orquestrador.
key: Chave da API do BotCity Orquestrador localizada na página Amb. Desenvolvedor.
login: Usuário da API do BotCity Orquestrador localizado na página Amb. Desenvolvedor.
machineId: ID do Runner atual. Veja a página Runners.
logScreen: Opção booleana que define se as capturas de tela são ou não enviadas periodicamente ao BotCity Orquestrador.
logApplication: Opção booleana que define se os logs do BotCity Runner são ou não enviados periodicamente ao BotCity Orquestrador.

Testando seu SDK do BotCity Studio¶

A maneira mais fácil de testar seu SDK do BotCity Studio é usar a ferramenta BotCity CLI.

Para isso, abra um terminal na pasta que contém o BotCity Studio SDK e execute o seguinte comando:

WindowsLinux e MacOS

BotCLI.bat bot list

./BotCLI.sh bot list

Se o seu SDK do BotCity Studio estiver configurado corretamente, você deverá ver a seguinte saída:

...
 SUCCESS  List of bots successfully returned!

Observação

Se você ver uma mensagem de SUCCESSO seguida de uma mensagem de ERRO, significa que seu BotCity Studio SDK está configurado corretamente, mas você provavelmente ainda não possui robôs implantados.

Próximos Passos¶

O ambiente do BotCity Studio SDK está agora instalado e configurado. Esse ambiente pode ser utilizado para desenvolver e executar automações BotCity.

Você também pode separar os ambientes de desenvolvimento e execução, para isso, siga os mesmos passos de instalação e configuração em máquinas diferentes.

Como próximos passos, veja a seção Desenvolvendo primeiro Bot, aonde você aprenderá a criar sua primeira automação utilizando ferramentas como BotCity Studio e frameworks BotCity: