BotCity Studio SDK¶

The BotCity Studio SDK is an all-in-one package containing all necessary tools to build, deploy and run your BotCity automations.

It includes the BotCity Studio, BotCity Runner and BotCity CLI (command line interface) tools.

Setup¶

The installation procedure for the BotCity Studio SDK is very simple and consist of only two steps:

1. Download and Unpack the BotCity Wizard
2. Follow the instructions on the screen

Download¶

In order to download the Wizard, just log in on your Maestro workspace and click on Download BotCity Studio, in the Developer section.

On the new page that opens, download the version compatible with your operating system.

Diagnostic Tool¶

The diagnostic tool accompanies the Wizard package, and its main objective is to validate whether your environment meets the prerequisites for using the BotCity Studio SDK.

This way, the tool will validate whether it is possible to install in your environment and also whether the BotCity tools will be able to establish a successful connection with the Orchestrator.

To diagnose your environment, run diagnostic.jar, provide the requested credentials, and press Run. With this, you will have a return similar to the one below:

In addition to connection information, diagnostic also checks the Python and Java versions of your environment.

If you observe a failure in one of these tests, check whether your environment meets the prerequisites to use the BotCity tools.

You can also export test results to a CSV file using the Export button.

Installing¶

After the download is completed, extract the downloaded archive. There will be a file called wizard-X.Y.Z where X.Y.Z are the Wizard's version.

For the installation, we can choose between two options:

• Install via GUI (graphical interface)
• Install via command line (silent installation)

Installing via GUI (graphical interface)¶

Through the graphical interface, the Wizard will guide you through each step of the installation process.

Choose where to install¶

Authenticating with BotCity Maestro¶

Configuring a BotCity Runner (optional step)¶

During this step you can optionally pick an existing Runner or create a new one.

If this is the first time that you are installing it, we strongly recommend creating one so you can run your automations.

Almost there¶

Please wait while the download finishes and the SDK is being configured.

You are ready to go 🚀¶

Here are some actions which you can perform from this screen:

• Change the version to a newer or previous version as well as to a development version
• Configure a BotCity Runner
• Launch BotCity Studio
• Launch BotCity Runner as a background process or as a visual application (GUI)
• Open the folder in which the SDK was installed

Installing via command line (silent install)¶

Other way to install the SDK is by command line, informing the necessary parameters for the installation.

Installation commands¶

We can install it using the wizard install command and entering some parameters.

The simplest possible command is the one that informs only the required parameters email and password, which are used for authentication in the BotCity Maestro Orchestrator.

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

To carry out the complete installation, with all parameters, we can use the following command:

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

Parameter table for the install command:

Update commands¶

For update the SDK settings, we can use the wizard update command always informing the password parameter, the other parameters are optional. In addition to the installation parameters, we can inform the version parameter to update the SDK version.

We can inform only one optional parameter as in the example below (includes version update):

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

Or do a complete update, with all parameters as in the following example:

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

With this command we cannot change the installation location of the SDK, for this it is necessary to redo the installation.

Parameter table for the update command:

Exploring the Contents¶

After finishing the SDK installation using one of the ways above, you will find the following folder structure:

.
├── bin
├── conf
│   ├── conf.bcf
│   └── properties.json
├── lib
│   └── tesseract
├── run
├── scripts
│   └── console_session.bat
├── startup
│   └── startup.bat
├── venvs
├── win32
│  └── java
├── BotCLI.bat
├── BotRunner.bat
├── BotRunner-gui.bat
├── BotStudio.exe
├── install.log
├── setup.json
└── wizard-X.Y.Z.exe

.
├── bin
├── conf
│   ├── conf.bcf
│   └── properties.json
├── lib
│   └── tesseract
├── run
├── scripts
├── startup
├── venvs
├── wizard-X.Y.Z.jar
├── setup.json
├── install.log
├── BotCLI.sh
├── BotRunner-gui.sh
├── BotRunner.sh
└── BotStudio.sh

On the root folder of the SDK, you will find the following files:

• BotCLI.bat/BotCLI.sh: Wrapper for the BotCity CLI (command line interface) tool.
• BotRunner-gui.bat/BotRunner-gui.sh: Launcher for the BotCity Runner tool in graphical mode.
• BotRunner.bat/BotRunner.sh: Launcher for the BotCity Runner tool in headless mode.
• BotStudio.exe/BotStudio.sh: Launcher for the BotCity Studio tool.
• bin: Folder containing the binary jar files of the BotCity SDK.
• conf: Folder containing the configuration files.
  • conf.bcf: BotCity Studio configuration file.
  • properties.json: BotCity Studio properties file (Use the Preferences menu to edit values, not directly on the file).
• lib: Support libraries for the BotCity Studio.
• run: Runtime folder for the BotCity Runner.
• venvs: Runtime folder for the BotCity Runner's Python virtual environments.
• scripts: Folder to store scripts that can be executed by BotCity Runner. More details here.
• startup: Folder containing a script that can be executed by BotCity Runner upon startup. More details here.
• setup.json: File containing installation information, such as the SDK version installed and the access credentials used.
• install.log: File produced by the Wizard containing installation log information.
• wizard-X.Y.Z.exe/wizard-X.Y.Z.jar: Copy of BotCity Wizard created inside the installation folder.

Configuration¶

The configuration for the BotCity Studio SDK is done via the conf.bcf file located in the "conf" directory.

Using the Wizard this file is automatically generated for you but you can still customize it to your own needs.

Exploring the conf.bcf file¶

Let's take a look at the content of the conf.bcf file:

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

• server: BotCity Maestro server URL.
• workspace: BotCity Maestro workspace.
• key: BotCity Maestro API key located on the Dev. Environment page.
• login: BotCity Maestro API User located on the Dev. Environment page.
• machineId: Machine ID of the current machine. See Machines.
• logScreen: Boolean option defining whether or not screenshots are periodically sent to the BotCity Studio.
• logApplication: Boolean option defining whether or not BotCity Runner logs are periodically sent to the BotCity Studio.

Testing Your BotCity Studio SDK¶

The easiest way to test your BotCity Studio SDK is to use the BotCity CLI tool.

For that, open a terminal on the folder containing the BotCity Studio SDK and run the following command:

./BotCLI.bat bot list

./BotCLI.sh bot list

If your BotCity Studio SDK is properly configured, you should see the following output:

SUCCESS:
...

Next Steps¶

You are now ready to start developing your BotCity automations.

Let's go to the next step and start developing your first bot.