Setup

In this section you will find how to configure the BotCity Maestro SDK and how to establish a connection with the BotCity Orchestrator platform via code.

Installation¶

PythonJavaJavascriptTypescriptC#

BotCity Maestro SDK is available as a Python package on PyPI.

You can install it with:

pip install botcity-maestro-sdk

BotCity Maestro SDK is available as a Java dependency in the Nexus repository.

The dependency will be installed automatically after being added to your pom.xml:

<repositories>
    <repository>
        <id>nexus-botcity-public</id>
        <url>https://devtools.botcity.dev:8081/repository/botcity-public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <!-- Your other dependencies -->
    <dependency>
        <groupId>dev.botcity</groupId>
        <artifactId>maestro-sdk</artifactId>
        <version>2.0.3</version>
    </dependency>
</dependencies>

BotCity Maestro SDK is available as a Javascript package on NPM.

You can install it with:

npm i @botcity/botcity-maestro-sdk

BotCity Maestro SDK is available as a Javascript package on NPM.

You can install it with:

npm i @botcity/botcity-maestro-sdk

BotCity Maestro SDK is available as a C# package on NuGet.

You can install it with:

dotnet add package BotCity.Maestro.SDK

Import the SDK¶

PythonJavaJavascriptTypescriptC#

You can import the SDK into your code with:

# Importing the package
from botcity.maestro import *

You can import the SDK into your code with:

// Importing the package
import dev.botcity.maestro_sdk.*;

You can import the SDK into your code with:

// Importing BotMaestroSdk class
const maestro = require("@botcity/botcity-maestro-sdk")

You can import the SDK into your code with:

// Importing BotMaestroSdk class
import { BotMaestroSdk } from '@botcity/botcity-maestro-sdk'

You can import the SDK into your code with:

// Importing the package
using Dev.BotCity;

Create a new Maestro client¶

BotMaestroSDK is the main class to be used when interacting with the BotCity Orchestrator features.

You can create a new Maestro client with:

PythonJavaJavascriptTypescriptC#

# Instantiating a Maestro SDK client
maestro = BotMaestroSDK()

// Instantiating a Maestro SDK client
BotMaestroSDK maestro = new BotMaestroSDK();

// Instantiating a Maestro SDK client
const maestro = new BotMaestroSdk()

// Instantiating a Maestro SDK client
const maestro: BotMaestroSdk = new BotMaestroSdk()

// Instantiating a Maestro SDK client
BotMaestroSDK maestro = new BotMaestroSDK();

Establish a connection with the Orchestrator¶

There are basically two ways to establish a connection with the BotCity Orchestrator via code.

Local execution authentication
Authentication via Runner

Local execution¶

During the development phase, you can connect to the BotCity Orchestrator to test features.

To authenticate in code, you need your workspace information:

Server:
- Community: https://developers.botcity.dev
- Dedicated: https://your-company.botcity.dev
Login: Authentication code
Key: Authentication key

Authentication

Find the authentication credentials directly in your BotCity Orchestrator workspace, in the Settings section in the side menu.

See more at:

Developer environment

Attention!

This method should be used in local testing contexts. It is not recommended to deploy code with this type of authentication.

PythonJavaJavascriptTypescriptC#

maestro.login(
    server="<SERVER>", 
    login="<LOGIN>", 
    key="<KEY>"
)

maestro.login("<SERVER>", "<LOGIN>", "<KEY>");

await maestro.login("<SERVER>", "<LOGIN>", "<KEY>")

await maestro.login("<SERVER>", "<LOGIN>", "<KEY>")

await maestro.LoginAsync("<SERVER>", "<LOGIN>", "<KEY>");

Execution via Runner¶

Once the robot is complete and ready for deployment, authentication must be done dynamically via arguments passed by the Runner that will execute the tasks.

Tutorial

You can use BotCity's project templates with base code snippets already ready for the first run.

See more at:

Tutorials

PythonJavaJavascriptTypescriptC#

# Getting the arguments passed by the Runner
maestro = BotMaestroSDK.from_sys_args()

public void action(BotExecution botExecution) {

    try {
        // Maestro SDK instance
        // The BotExecution object contains the information passed by the Runner
        BotMaestroSDK maestro = new BotMaestroSDK();
        maestro.login(botExecution);
    ...

// Not yet implemented

// Not yet implemented

// Getting the arguments passed by the Runner
BotMaestroSDK maestro = BotMaestroSDK.FromSysArgs();

Get the current execution reference¶

During the execution of a task, you can retrieve important information about a running execution, such as the task ID or parameters of that task.

PythonJavaJavascriptTypescriptC#

# Maestro SDK instance
maestro = BotMaestroSDK.from_sys_args()
# Fetching the details of the current task being executed
execution = maestro.get_execution()

# Information about the task being executed
print(f"Task ID is: {execution.task_id}")
print(f"Task Parameters are: {execution.parameters}")

public void action(BotExecution botExecution) {

    try {
        // Maestro SDK instance
        // The BotExecution object contains the information passed by the Runner
        BotMaestroSDK maestro = new BotMaestroSDK();
        maestro.login(botExecution);

        // Information about the task being executed
        System.out.println(botExecution.getTaskId());
    ...

// Getting parameters passed by the Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Instantiating the Maestro SDK
const maestro = new BotMaestroSdk()
maestro.login(<SERVER>, "<LOGIN>", "<KEY>")

// Fetching the details of the current task being executed
const executionTask = await maestro.getTask(taskid)

// Getting parameters passed by the Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Instantiating the Maestro SDK
const maestro: BotMaestroSdk = new BotMaestroSdk()
maestro.login("<SERVER>", "<LOGIN>", "<KEY>")

// Fetching the details of the current task being executed
const executionTask: Task = await maestro.getTask(taskid)

using Dev.BotCity.MaestroSdk.Model.Execution;

// Maestro SDK instance
BotMaestroSDK maestro = BotMaestroSDK.FromSysArgs();
// Fetching the details of the current task being executed
Execution execution = await maestro.GetExecutionAsync(maestro.GetTaskId());

// Information about the task being executed
Console.WriteLine("Task ID is: " + execution.TaskId);
Console.WriteLine("Task Parameters are: " + string.Join(", ", execution.Parameters));

All set¶

With the setup complete, you can securely exchange information between the Runner execution and the BotCity Orchestrator.

All information generated during the execution of a task can be stored in the BotCity Orchestrator, but to do so you need to explicitly use the methods in your code.

BotCity Orchestrator

The BotCity Orchestrator does not access or assume any value generated during task execution. Only basic information is automatically recorded: queue time markers, execution time, and the name of the Runner that executed the task.