Tasks¶

Tasks are instances of an Automation. In this section you will find information on how to create, manipulate and retrieve information from a task via SDK.

BotCity Orchestrator

You can also use the Tasks feature directly on the BotCity Orchestrator platform.

See more at:

Create a task¶

You can create a new task through the BotCity Maestro SDK.

To do so, you need the following information:

Activity label: Automation identifier
Parameters: Dictionary with parameter values
Test: (optional) Defines the task as a test task
Priority: (optional) Value from 0 to 10 for queue management
Minimum execution date: (optional) Minimum date for the execution to take place

Timezone warning

The BotCity Orchestrator server timezones are in UTC.

Therefore, remember to account for the difference between time zones when using the min_execution_date parameter when creating a task.

PythonJavaJavascriptTypescriptC#

from datetime import datetime

date = datetime.strptime("09/03/2026 00:00", "%d/%m/%Y %H:%M")
params = {}
task = maestro.create_task(
    activity_label="automationLabel",
    parameters=params,
    test=False,
    priority=5,
    min_execution_date= date
)

Map<String, String> params = new HashMap<String, String>();
AutomationTask task = maestro.createTask("automationLabel", params, false);

const parameters = {}
const task = await maestro.createTask("automationLabel", parameters, false)

const parameters: object = {}
const task: Task = await maestro.createTask("automationLabel", parameters, false)

using Dev.BotCity.MaestroSdk.Model.AutomationTask;

Dictionary<string, object> parameters = new Dictionary<string, object>{};
AutomationTask task = await maestro.CreateTaskAsync("automationLabel", parameters, false);

Interrupt a task¶

For long-running tasks, such as batch item processing, it may be sensible to allow users to request their interruption.

In this context, you can implement in the code a way to check whether the task should stop or continue.

You can include the method to request an interruption for a given task.

To do so, you need the following information:

Task ID: Identifier of the running task

Attention!

Please note that the task will only be interrupted if the correct implementation is in place.

It is the responsibility of the robot code developer to check the return value of the interruption request method (true or false) and act accordingly to interrupt the task.

PythonJavaC#

maestro.interrupt_task(task_id=<TASK_ID>)

maestro.interruptTask(<TASK_ID>);

await maestro.InterruptTaskAsync(<TASK_ID>);

Implementation suggestion¶

It is the responsibility of the robot code developer to check the return value of the interruption request method (true or false) and act accordingly to interrupt the task.

The logic should be applied to perform a check during task execution, for example:

PythonJava

while not maestro.get_task(task_id=<TASK_ID>).is_interrupted():
    # Continuing to process items
    print("Processing items")
    ...
print("An interruption was requested")

while(!maestro.getTask(<TASK_ID>).getInterrupted()) {
    // Continuing to process items
    System.out.println("Processing items");
    ...
}
System.out.println("An interruption was requested.");

Tip

You can implement this together with reading a list of items to be processed and check for interruption before the next item is processed.

The source of this item list can vary, such as: Excel files, CSV files, database queries, Datapool integration, among others.

Finish task and report data¶

The basic lifecycle of a task is:

Create: The task is created and queued in the BotCity Orchestrator (Start).
Execute: The task is executed by the Runner in the production environment (Running).
Finish: The task has its state and data reported directly in the code, according to the defined flow.

Define final state¶

Reporting the completion state and execution data must be implemented in the code, following business rules to define which state to assign at the end of the task.

It is the responsibility of the automation developer to inform the BotCity Orchestrator through the SDK about the appropriate final state of a task.

A task can be completed with one of the following states:

SUCCESS: The task was completed successfully.
FAILED: The task was not completed.
PARTIALLY_COMPLETED: The task completed part of the expected steps.

Define data¶

In addition to reporting the completion state of a task, you can also report additional data regarding the items that were processed during execution.

This reporting allows better control and also adds details about the task completion that can be inspected later by teams in the BotCity Orchestrator. This feature is very useful in cases where you need to monitor the number of items processed with success or failure by the task.

To fully finish a task, you need the following information:

Task ID: Task identifier
State: Completion state, defined with the AutomationTaskFinishStatus class:
- SUCCESS: The task was completed successfully
- FAILED: The task was not completed
- PARTIALLY_COMPLETED: The task completed part of the expected steps
Message: Custom text for the completion
Total items: Total number of items executed
Processed items: Number of items processed successfully
Failed items: Number of items processed with failure

What is an item?

The concept of an item can be any entity related to your automation process.

This way, you can use whatever logic is necessary for the process and define how each item will be consumed, processed and counted in the code.

At the end, report this data through the finish_task method of the Maestro SDK.

PythonJavaJavascriptTypescriptC#

maestro.finish_task(
    task_id=<TASK_ID>,
    status=AutomationTaskFinishStatus.SUCCESS,
    message="Task was completed successfully.",
    total_items=100,
    processed_items=90,
    failed_items=10
)

maestro.finishTask(
    <TASK_ID>,
    "Task was completed successfully.",
    FinishStatus.SUCCESS,
    100,
    90,
    10
);

await maestro.finishtTask(
    <TASK_ID>,
    "Task was completed successfully.",
    "SUCCESS",
    100,
    90,
    10
)

await maestro.finishtTask(
    <TASK_ID>,
    "Task was completed successfully.",
    "SUCCESS",
    100,
    90,
    10
)

await maestro.FinishTaskAsync(
    <TASK_ID>,
    FinishStatusEnum.SUCCESS,
    "Task was completed successfully.",
    100,
    90,
    10
);

Important

It is important that the quantification data of processed items is reported at the end of each task. The step of reporting data in the automation code is essential for high-level information to be generated in the BotCity Insights module.

BotCity Insights is a dedicated module for reporting and displaying data related to your automation initiative.

See more at:

BotCity Insights.

Return information from a task¶

You can retrieve information about a task using its ID or through the current execution reference.

Use the ID of a specific task¶

You can retrieve general information about a task through its ID, regardless of its state, using the following method:

PythonJavaJavascriptTypescriptC#

task = maestro.get_task("<TASK_ID>")

AutomationTask task = maestro.getTask("<TASK_ID>");

const task = await maestro.getTask("<TASK_ID>")

const task: Task = await maestro.getTask("<TASK_ID>")

AutomationTask task = await instance.GetTaskAsync("<TASK_ID>");

Return example

AutomationTask(
    id=<TASK_ID>, 
    state='<STATUS>', 
    parameters={}, 
    input_file=None, 
    agent_id='<DEMO>, 
    user_email=None, 
    user_creation_name='SDK', 
    organization_label='<ORGANIZATION>', 
    date_creation='<DATE>', 
    date_last_modified='<DATE>', 
    finish_status=None, 
    finish_message=None, 
    test=True, 
    machine_id=None, 
    activity_label='<DEMO>', 
    interrupted=False, 
    min_execution_date='<DATE>', 
    killed=False, 
    date_start_running=None, 
    priority=5, 
    repository_label='<REPOSITORY>', 
    processed_items=None, 
    failed_items=None, 
    total_items=None, 
    activity_name='<DEMO>'
    )

Get the current task ID¶

The Maestro SDK has a special method that returns the information of a task running on the Runner.

This method makes it easy to retrieve the task ID and its current parameters. See the example:

PythonJavaJavascriptTypescriptC#

# Fetching the details of the task currently 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}")

Info

The BotExecution object is by default already configured in the BotCity Java project template.

public void action(BotExecution botExecution) {

    try {
        ...

        // 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

// Fetching the details of the task currently 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

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

using Dev.BotCity.MaestroSdk.Model.Execution;

// Fetching the details of the task currently 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));

Return example

Task ID is: <TASK_ID>
Task Parameters are: {'<PARAM_LABEL>': '<VALUE>'}

Task parameters¶

Each task can provide different values for processing. Parameters can be used to add this dynamism to processes.

How to create parameters?

Parameters can be configured directly in Automations within the BotCity Orchestrator.

Access the parameters of a task¶

When creating a task from an automation with parameters, you can retrieve these dynamic values directly in the code.

To do so, you need the following information:

Task ID: Task identifier
Label: Label of the parameters registered in the Automation

PythonJavaJavascriptTypescriptC#

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

# Getting parameter by label
parameter1 = execution.parameters.get("<PARAMETER_LABEL1>")
parameter2 = execution.parameters.get("<PARAMETER_LABEL2>")

Info

The BotExecution object is by default already configured in the BotCity Java project template.

public void action(BotExecution botExecution) {

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

        // Getting parameter by label
        Object parameter1 = botExecution.getParams().get("<PARAMETER_LABEL1>");
        Object parameter2 = botExecution.getParams().get("<PARAMETER_LABEL2>");
    ...

// 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 task currently 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 task currently being executed
const executionTask: Task = await maestro.getTask(taskid)

using Dev.BotCity.MaestroSdk.Model.Execution;

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

// Getting parameter by label
var parameter1 = execution.Parameters["<PARAMETER_LABEL>1"];
var parameter2 = execution.Parameters["<PARAMETER_LABEL>2"];

Return example

<PARAMETER_VALUE1>
<PARAMETER_VALUE2>