Skip to content

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, BotCity CLI (command line interface), and Session Manager tools.

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

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

Download

The Wizard can be downloaded directly from the BotCity Orchestrator by accessing the Studio page.

This page can be found at:

On the Studio page, select the option compatible with your operating system:

  • Download for Windows
  • Download for Linux
  • Download for MacOS

Screenshot of the BotCity Studio page, showcasing the BotCity Studio tools: a tool for generating automatic code to interact with graphical elements; BotCity Runner: software responsible for executing tasks created in the Orchestrator; BotCity Diagnostic: a tool that validates the connection and SDK installation prerequisites. Links for downloading Windows, Linux, and macOS systems are highlighted at the bottom of the page.

After the download is complete, extract the files and you will have access to two tools: Diagnostic and Wizard.

Diagnostic Tool

The BotCity - Diagnostic tool is included in the Wizard package and is primarily designed to validate whether your environment meets the prerequisites for installing and using the BotCity Studio SDK.

With this tool, you can verify:

  • Connectivity with the BotCity Orchestrator
  • Installed Java version (Runtime and Development)
  • Installed Python version

To obtain the diagnostic of your environment, simply execute the diagnostic.jar, provide the requested credentials, and click on Run Tests. This will give you a detailed report in three columns: Test, Result, and Notes.

The test results should look similar to the example below:

Screenshot of the "BotCity Diagnostic" tool. The interface displays a server selector set to "Community" and a "Run Tests" button. Below, a results table with three columns (Test, Result, and Notes) lists connectivity and environment checks: Orchestrator server reach and login (both with SSL enabled marked as "PASS" and disabled as "SKIP"), as well as SDK download reach. The table also confirms the presence and versions of Java Runtime (17.0.3), Python Development (3.12.4), and Java Development (22.0.1), all with "PASS" status. At the bottom, there are buttons to export data and speak with a specialist.

Warning

If you receive a FAIL result in any connection test, it is likely that you are trying to install in a restricted environment. Check the description in the Notes column.

In this case, you need to request the necessary permissions from the responsible team as described in the prerequisites section.

You can also export the test results to a CSV file using the Export button and contact the support team by clicking the Talk to a Specialist button.

Info

This is an entirely optional tool, you can use it if necessary or if you notice any impediment in installing or using the BotCity tools.

Install with Wizard

For installation, use the file named wizard-X.Y.Z where X.Y.Z represents the Wizard 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 in an intuitive way, see the example below:

Choose where to install

Screenshot of the "BotCity Wizard" tool. The interface presents 4 steps, highlighting step 1: Setup. There is an installation path selector with a search button, as well as a button to proceed and a button to return. At the bottom, there is a link to learn more about the BotCity SDK.

Warning

Please be aware that installing at locations such as C:\... could cause permissions issues.

Try to avoid such locations or please make sure to fix the permissions accordingly.

Authenticating with BotCity Orchestrator

Screenshot of the "BotCity Wizard" tool. The interface presents 4 steps, highlighting step 2: Login. A server selector indicates the selected "Community" server, as well as a button to advance and a button to return. At the bottom, a link to learn more about the BotCity SDK.

Warning

For Server make sure to always use your BotCity Orchestrator URL.

If you have a custom subdomain it is very likely that your URL will be something like https://yourcompany.botcity.dev.

For the community version, please use https://developers.botcity.dev.

A new page will open in your browser, allowing you to log into your account. Screenshot showing the authentication confirmation with BotCity in the browser.

If you have multiple organizations under the same account, you will be prompted to select one. Screenshot of the "BotCity Wizard" tool. The interface has 4 steps, highlighting step 2: Login. There's an organization selector indicating the selected "Org" organization, as well as a button to advance and a button to return. At the bottom, there's a link to learn more about the BotCity SDK.

Almost there

Screenshot of the "BotCity Wizard" tool. The interface presents 4 steps, highlighting step 3: Download. A progress bar in the center indicates the percentage of progress in the download. At the bottom, a link to learn more about the BotCity SDK.

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

You are ready to go 🚀

Screenshot of the "BotCity Wizard" tool. The interface presents 4 steps, highlighting step 4: Finish. Indicating that the BotCity SDK configuration is complete; Two buttons are available: Go to Orchestrator and open SDK. At the bottom, a link to learn more about BotCity SDK.

Tip

A copy of the Wizard is now available on the folder in which the SDK was installed. You can always launch it from there and come back to this screen.

Configuring a BotCity Runner

After completing the SDK installation, you can configure a Runner in your execution environment using the Setup Runner option.

Screenshot of the "BotCity Wizard" tool (version 2.1.0), titled "Welcome BotCity SDK". The interface describes the SDK as a complete package for building, deploying, and running automations. It features three main action buttons with corresponding icons: 1. Launch Studio (terminal icon) to open the development environment; 2. Setup Runner (gear icon) for setting up the execution agent; and 3. SDK Folder (folder icon) to access local files. In the upper right corner, it indicates the current SDK version (v2.20.0) with an option to change it. At the bottom, there are buttons to navigate to the Orchestrator or speak with a specialist.

You can choose a Runner that already exists in your Orchestrator workspace or create a new one.

Screenshot of the "BotCity Wizard" tool (version 2.1.0). The interface for Runner configuration in two steps: Credentials and Runner Configuration. It features two main action buttons: 1. I already have a Runner; 2. Create a new Runner. At the bottom, a back button.

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

Tip

See more details in the section Configuring a Runner.

BotCity Wizard Actions

Screenshot of the "BotCity Wizard" tool (version 2.1.0), titled "Welcome BotCity SDK". The interface describes the SDK as a complete package for building, deploying, and running automations. It features five main action buttons with corresponding icons: 1. Launch Studio (terminal icon) to open the development environment; 2. Setup Runner (gear icon) for setting up the execution agent; 3. Runner - GUI (screen icon) to open the Runner with a graphical interface; 4. Launch Runner (layers icon) to open the Runner in a terminal; and 5. Folder SDK (folder icon) to access local files. In the upper right corner, it indicates the current SDK version (v2.20.0) with the option to change it. At the bottom, there are buttons to navigate to the Orchestrator or speak with a specialist.

Here are some actions you can perform on the Wizard home screen:

  • Change version: Change the version to a newer or older version, as well as to a development version
  • Launch Studio: Launch BotCity Studio
  • Setup Runner: Set up a BotCity Runner
  • Runner - GUI: Launch the BotCity Runner as a visual application (GUI)
  • Launch Runner: Launch the BotCity Runner as a background process
  • Folder sdk: Open the folder where the SDK was installed
  • Go to Orchestrator: Open the BotCity Orchestrator in your default browser
  • Talk to a Specialist:: Open the BotCity support channel

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 Orchestrator.

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

Tip

  • It may be necessary to inform the version of the wizard in the command, if it is not found. wizard-X.Y.Z install...
  • For Linux and macOS systems, add the java -jar command before the wizard command. java -jar wizard-X.Y.Z.jar install ...

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:

Option Required Definition Standard value
dir No Folder where the SDK will be installed Depends on operating system
server No BotCity Orchestrator URL https://developers.botcity.dev
email Yes User account email
password Yes User account password
organization No Organization to be used (label) First organization on the list
runner No Runner to be configured (machineId) Empty

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.

Warning

When the version parameter is not informed, it will always be updated to the latest version of the SDK.

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"

Tip

The SDK version can be checked in the setup.json file in the folder where the SDK was installed.

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:

Option Required Definition Standard value
server No BotCity Orchestrator URL Keeps the installed
email No User account email Keeps the installed
password Yes User account password
organization No Organization to be used (label) Keeps the installed
runner No Runner to be configured (machineId) Keeps the installed
version No Version to be installed Latest version

Exploring the Contents

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

.
├── 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

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

  • .cookieCli: File for the BotCity CLI session cookie.
  • .workspaceCli: Workspace file used by the CLI.
  • bin: Folder containing the binary .jar files of the BotCity SDK
  • BotCLI.bat/BotCLI.sh: Shortcut to use 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.
  • bots: Bot cache folder (internal use of BotCity Runner).
  • BotStudio.exe/BotStudio.sh: Launcher for the BotCity Studio tool.
  • 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).
  • diagnostic.jar: Tool to validate the environment prerequisites for using BotCity tools.
  • install.log: File produced by the Wizard containing installation log information.
  • logs: BotCity Runner log storage folder.
  • probes: Folder containing information about the Runner's communication time with the Orchestrator.
  • run: Runtime folder for the BotCity Runner.
  • scripts: Folder for storing scripts that can be executed by BotCity Runner.
  • setup.json: File containing installation information, such as the SDK version installed and the access credentials used.
  • startup: Folder containing a script that can be executed by BotCity Runner at initialization.
  • venvs: Folder used by BotCity Runner to manage virtual environments for Python automations.
  • win32: Folder containing the Java version used by the SDK.
  • 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.

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

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: BotCity Orchestrator server URL.
  • workspace: BotCity Orchestrator workspace.
  • key: BotCity Orchestrator API key located on the Dev. Environment page.
  • login: BotCity Orchestrator 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  List of bots successfully returned!

Note

If you see a SUCCESS message followed by an ERROR message, it means that your BotCity Studio SDK is properly configured, but you probably have no bots deployed yet.

Next Steps

The BotCity Studio SDK environment is now installed and configured. This environment can be used to develop and run BotCity automations.

You can also separate the development and execution environments; to do this, follow the same installation and configuration steps on different machines.

For next steps, see the Developing Your First Bot section, where you will learn how to create your first automation using tools like BotCity Studio and BotCity frameworks: