Python Custom Bot¶

Minimum Requirements¶

In order to be able to orchestrate an existing Python project or script, we will basically need two requirements:

bot.py: A file named bot.py that will serve as an entry point for BotCity Runner. This file can be considered as the 'main' file of the project. You can leave your Python code directly in this file or simply use it to import the scripts you want to run.
requirements.txt: A file containing all the dependencies that are used in the code. This file serves as a reference for the Runner to know all the Python packages that must be installed when running the code.

Creating the `bot.py` file¶

In this tutorial we will create a bot.py file containing a simple Python script that uses pure Selenium. After entering the code, the file will look like this:

# This bot will access BotCity's Youtube channel and collect the number of subscribers.

# Importing the Selenium package
from selenium import webdriver

# Setting to use Chrome
driver = webdriver.Chrome(executable_path="<chromedriver.exe path>")

# Accessing the Google homepage
driver.get("https://google.com")

# Searching for BotCity Youtube channel in the search bar
search_bar = driver.find_element_by_name("q")
search_bar.send_keys("BotCity RPA Youtube")

# Clicking on the "I'm Feeling Lucky" button
feeling_lucky_button = driver.find_element_by_xpath("/html/body/div[1]/div[3]/form/div[1]/div[1]/div[3]/center/input[2]")
feeling_lucky_button.click()

# Collecting the number of subscribers from the Youtube page
subscribers = driver.find_element_by_id("subscriber-count").text
print(f"Subscribers Count: {subscribers}")

# Closing the browser
driver.quit()

Info

You can also use the bot.py file just to import your scripts.

Defining the requirements file¶

Now, let's create our requirements file containing the dependencies we are using in the code.

requirements.txt:

# Setting to use this specific version of the package
selenium==3.141.0

Zipping all files¶

With the necessary files configured, now we just need to create a .zip file containing all these files. The folder structure will look like this:

CustomBot.zip
├── bot.py <- File containing code or importing other python scripts.
└── requirements.txt <- File describing the python dependencies for your bot.

Important

In this example we are only using the main files, but if you have a structure with several python scripts, for example:

CustomBot
├── bot.py
├── script.py
├── my_functions.py
├── utils.py
└── requirements.txt

You can use bot.py just to call your other scripts and create the .zip file in the same way. The most important thing is to consider bot.py as the 'main' of the project and define all dependencies used in the requirements.txt file.

With the .zip file in hand, we can now deploy this bot and run it through Maestro and Runner normally. The steps will be exactly the same as when using a project template. See more details about send your bot to Maestro.

Using the BotCity Maestro SDK¶

Only the steps above would be enough to run our automation using Maestro and Runner. However, in some cases it may be necessary to use the integration with Maestro to be able to send alerts and finish tasks, for example.

For this, we can easily import the Maestro SDK in the code and use the methods normally. The only necessary step is to do a treatment to get the parameters that are passed by the Runner at the time of execution.

Accessing parameters passed by Runner¶

When we run an automation through BotCity Maestro, BotCity Runner passes some information per parameter when starting the execution, such as the server, the task id being executed and also the access token.

To access these values, we can check if these parameters are being passed and then use them to instantiate and interact with the Maestro SDK. The from_sys_args method is responsible for checking the parameters and returning an instance of BotMaestroSDK.

# Importing the BotCity Maestro SDK
from botcity.maestro import *

...

# Runner passes the server url, the id of the task being executed, 
# the access token and the parameters that this task receives (when applicable).
maestro = BotMaestroSDK.from_sys_args()

# Task parameters are passed as a dictionary
# Use the parameter label that was defined to access its value
task_info = maestro.get_task(maestro.task_id)
parameter1 = task_info.parameters.get("PARAM_LABEL_1")
parameter2 = task_info.parameters.get("PARAM_LABEL_2")
...

Now that we've collected this information, we can use it to interact with Maestro, such as marking the task as finished.

...

maestro.finish_task(
    task_id=maestro.task_id, 
    status=AutomationTaskFinishStatus.SUCCESS, 
    message="Task Finished!"
)
...

Complete code¶

Including these changes, our files would look like this:

bot.py:

# This bot will access BotCity's Youtube channel and collect the number of subscribers.

# Importing the Selenium package
from selenium import webdriver

# Importing the BotCity Maestro SDK
from botcity.maestro import *

# Treatment to collect the parameters passed by the Runner
maestro = BotMaestroSDK.from_sys_args()
# This property prevents exceptions from being thrown when trying to use the BotMaestroSDK while running locally.
maestro.RAISE_NOT_CONNECTED = False

# Setting to use Chrome
driver = webdriver.Chrome(executable_path="<chromedriver.exe path>")

# Accessing the Google homepage
driver.get("https://google.com")

# Searching for BotCity Youtube channel in the search bar
search_bar = driver.find_element_by_name("q")
search_bar.send_keys("BotCity RPA Youtube")

# Clicking on the "I'm Feeling Lucky" button
feeling_lucky_button = driver.find_element_by_xpath("/html/body/div[1]/div[3]/form/div[1]/div[1]/div[3]/center/input[2]")
feeling_lucky_button.click()

# Collecting the number of subscribers from the Youtube page
subscribers = driver.find_element_by_id("subscriber-count").text
print(f"Subscribers Count: {subscribers}")

# Closing the browser
driver.quit()

# Using the SDK to finish the task on Maestro
maestro.finish_task(
    task_id=maestro.task_id, 
    status=AutomationTaskFinishStatus.SUCCESS, 
    message="Task Finished!"
)

requirements.txt:

# Setting to use this specific version of the package
selenium==3.141.0

# Including BotCity Maestro SDK dependencie
botcity-maestro-sdk

Only with the above changes is it possible to interact with the BotCity Maestro functionalities. Note that these steps are not mandatory to be able to execute the automation, it is only necessary if we want to integrate with the orchestrator.

Info

See more details about BotCity Maestro SDK usage and features.

Conclusion¶

Under this tutorial you learned:

The minimum requirements needed to orchestrate a custom Python project.
The basic configuration you need to do using the bot.py and requirements.txt files.
How to use the BotCity Maestro SDK to integrate with the orchestrator through your custom project.