Start and Keep the Runner Session Active

When executing the BotCity Runner on Windows under Remote Desktop Connection it is important to pay attention to the fact that when the connection is closed the OS will make the screen go black.

When this happens, bots can no longer capture the screen and run the automation correctly if your automation requires graphical resources.

Over the following sections we describe some approaches to solve this issue.

BotCity Session Manager

Session Manager monitors the task queue in real-time, activating resources as the queue grows and deactivating them when demand decreases. It is optimized to provide timely resource allocation, reducing idle time and ensuring resource availability when necessary.

Session disconnect script

Tip

Session scripts are still supported, but we recommend using the BotCity Session Manager as a more robust and scalable solution.

This option consist into having a PowerShell script which moves the current RDP connection into a terminal connection and disconnects the current one without blocking the User Interface.

Inside the folder where the BotCity Studio SDK installation was carried out, we will find a folder with the name startup and inside a script called startup.bat with the following content:

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

Startup configuration

The BotCity Runner offers a hook to activate a startup script which is executed when the Runner is ready to process tasks.

This way, we can configure Runner to execute the startup.bat script and carry out the user disconnection process.

For that, go into your ./conf/conf.bcf file and add a new parameter to it called startup.

Your configuration file should look like this:

server=https://developers.botcity.dev
login=<login>
key=<key>
machineId=<Runner ID>
logScreen=true
logApplication=true
startup=./startup/startup.bat

Important

The next time you start BotCity Runner, it will run the script to close your RDP connection while keeping the session active automatically.

When using this approach, a user's disconnection must always be done in this way to ensure that access to the machine's graphical resources is enabled.

If you need to access this user and do not want to restart the Runner to disconnect the session, run the startup.bat script, and the session will be disconnected similarly.

Warning

Depending on the user's permission level, it may be necessary to launch Runner with administrator permission for the startup script to run correctly.

Environment configuration script

In addition to being able to configure a script to run as soon as Runner starts, we can also configure so that some action is done through a script before starting to execute a task.

Inside the folder where the BotCity Studio SDK installation was carried out, we will find a folder with the name scripts and inside a script called console_session.bat with the following content:

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

Attention

If you get an error when running the Set-DisplayResolution command, pay attention to the points below:

• For Server Windows 10 and 11 the command to define the resolution is Set-ScreenResolution. That is, it should be used like this: Set-ScreenResolution -Width 1600 -Height 900

• In some cases, the module DisplaySettings may not have been installed by default on PowerShell. In this way, it is necessary to make the installation using the command: Install-Module -Name DisplaySettings

This script basically has the same function as the startup script we saw above; it will move the current RDP connection to a terminal connection and disconnect the current one without blocking the user interface. Furthermore, we can define a specific resolution that will be used in this session that will be active.

Instead of running this script when Runner starts, let's configure it to run before Runner executes each task.

In the file ./conf/conf.bcf, we will add a new parameter called beforeTask, which will receive the path of this script that will be executed.

server=https://developers.botcity.dev
login=<login>
key=<key>
machineId=<Runner ID>
logScreen=true
logApplication=true
startup=./startup/startup.bat
beforeTask=./scripts/console_session.bat

Warning

Depending on the user's permission level, it may be necessary to launch Runner with administrator permission for the beforeTask script to run correctly.

Tip

This script is just a suggestion of the type of configuration that can be performed.

You can change and configure the script to configure the environment according to your needs.

Main RDP Machine

Tip

Session scripts are still supported, but we recommend using the BotCity Session Manager as a more robust and scalable solution.

This option consist into having a Windows machine with constant RDP connection with the other machines to keep the connection alive and running without the need to have an user connected to them.

Installing RDCMan

Remote Desktop Connection Manager is an application from Microsoft which allows you to manage multiple RDP connections. After installing it on the MAIN machine, connections are established with the HOST machines running the automations.

Here is a link to download the latest version of RDCMan.

After downloading the file, all you need to do is to extract it and run RDCMan.exe from the extracted folder.

Adding a new machine

Create a new file machines.rdg and save it on the same folder as RDCMan:

On the left panel, right-clickon the empty area and select Add Server.

Configure the access to the HOST machine:

Warning

The following steps are key to the proper functioning of the RDCMan.

Please follow them carefully.

• Under server name, you just need to use the machine IP address:

• Setup the resolution on the “Remote Desktop Settings” tab to 1600x900.

Info

Change this according to your project resolution. 1600x900 is BotCity’s recommended standard.

• Turn off “Clipboard” under the “Local Resources” tab

Configuring the MAIN machine to remain active

Configuration of the MAIN machine to keep RDP sessions active even if there are no active RDP connections to it.

Change the local computer registry settings

1. On your local computer, close all open Remote Desktop sessions.
2. Launch the Registry editor (regedit.exe).

3. Navigate to one of the following Registry keys, depending on whether you wish to modify the Remote Desktop settings only for the current user or for all users on the computer:

   HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client Change this one HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client

4. Create a DWORD value named RemoteDesktop_SuppressWhenMinimized and set it to 2 (hexadecimal or decimal):

5. Close the Registry Editor.

Now when you minimize the Remote Desktop Connection window on your computer, this will not affect the remote computer’s GUI and the GUI will be available to your automations.

Procedure to keep HOST machines active

1. Conect to the MAIN machine
2. Connect to all the HOST machines using RDPMan
3. Disconnect from the MAIN machine

Start the session and Runner automatically on the VM

Prefer the Session Manager

We recommend the BotCity Session Manager as the more robust and scalable solution. Use the configuration below when the Session Manager is not an option in your environment.

This option configures a Windows VM so that, when it is started or restarted, it opens a graphical user session on its own and starts the BotCity Runner inside it, with no manual intervention. The configuration uses two tasks in the Windows Task Scheduler:

• Start - RDP: runs when the machine starts (At startup) and opens a user session via RDP pointing to the machine itself (localhost).
• Start - Runner: runs at logon (At log on) and starts the Runner inside the session created by the previous task.

How the chaining works

The Start - RDP task does not start the Runner. It only opens the user session that provides the graphical interface the Runner needs. Opening that session generates a logon event in Windows, and that event is what triggers the Start - Runner task. This way, the Runner always starts inside a valid graphical session.

Combine with the disconnect scripts

This configuration handles starting the session when the VM is started or restarted. If someone connects to the machine later and closes the RDP connection, the screen goes black again. To keep the session active in that case, also use the session disconnect scripts.

Step 1: Create the start_rdp.bat script

Create the start_rdp.bat file with the content below, replacing username and password with the user and password used to access the VM:

cmdkey /generic:"localhost" /user:"username" /pass:"password"
mstsc /v:localhost
cmdkey /delete:localhost

The script stores the credential, opens the RDP connection to the machine itself, and then removes the credential.

Step 2: Create the Start - RDP task

In the Windows Task Scheduler, create a new task with the settings below:

• General:
  • Name: Start - RDP
  • When running the task, use the following user account: the VM administrator user (e.g. Administrator)
  • Run whether user is logged on or not: selected
  • Run with highest privileges: checked
• Triggers: At startup
• Actions: Start a program, pointing to the start_rdp.bat file (e.g. C:\Users\Administrator\Desktop\start_rdp.bat)

Keep the default values in the Conditions and Settings tabs.

Run with highest privileges

Make sure to check Run with highest privileges in this task and in the Step 3 task.

Step 3: Create the Start - Runner task

Create a second task with the settings below:

• General:
  • Name: Start - Runner
  • When running the task, use the following user account: the same user set in start_rdp.bat
  • Run only when user is logged on: selected
  • Run with highest privileges: checked
• Triggers: At log on, for the same user (e.g. At log on of <MACHINE>\Administrator)
• Actions: Start a program, pointing to the BotRunner.bat file in the BotCity Studio SDK installation folder
• Settings: uncheck all options:
  • Allow task to be run on demand
  • Run task as soon as possible after a scheduled start is missed
  • If the task fails, restart every
  • Stop the task if it runs longer than
  • If the running task does not end when requested, force it to stop
  • If the task is not scheduled to run again, delete it after

Step 4: Verify the configuration

Restart the VM and wait for it to start, without connecting to it.

Configuration complete

The VM opens a graphical user session on its own, the BotCity Runner starts inside that session and shows as online in the Orchestrator, ready to run automations that depend on visual resources.