Tasks¶

As covered so far, tasks are instances of an Automation and one of the most important concepts in the BotCity Maestro platform.

Here we will cover how to create, interrupt, finish and retrieve tasks.

Creating a task¶

We can create a new task via the BotMaestro SDK using the following code:

params = {}
task = maestro.create_task(
    activity_label="automationLabel",
    parameters=params,
    test=False
)

Map<String, Object> params = new HashMap<>();
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)

Interrupting a task¶

For long running tasks such as batch processing of items, it may be wise to allow users to request its interruption.

Here is how to request an interruption for a given task:

maestro.interrupt_task(task_id=task.id)

maestro.interruptTask(task.id);

// Not implemented yet

// Not implemented yet

Checking for interrupt request¶

It is responsability of the bot code developer to check the interrupt requested flag and act on it accordingly to stop the task.

Here is how you can do that:

while not maestro.get_task(task_id=task.id).is_interrupted():
    # Keep processing items
    print("Processing items")
    ...
print("An interruption was requested.")

while(!maestro.getTask(task.id).getInterrupted()) {
    // Keep processing items
    System.out.println("Processing items");
    ...
}
System.out.println("An interruption was requested.");

// Not implemented yet

// Not implemented yet

Finishing a task and reporting data¶

Once tasks are created, they are queued on the BotCity Maestro and collected for execution by the BotCity Runner.

The tasks that are collected for execution move forward to the Running state.

It is the bot developer responsibility to inform the BotCity Maestro via the SDK of the proper final status of a task.

This allow for better control and also to add details about the task completion that can later be inspected by users via the BotCity Maestro portal.

A task can be finished with one of the following status:

• SUCCESS: The task finished successfully.
• FAILED: The task failed to finish.
• PARTIALLY_COMPLETED: The task completed part of the expected steps.

In addition to reporting the finish status of a task, we can also report additional data related to the items that were processed during the execution.

This feature will be very useful in cases where we need to monitor the number of items processed successfully or failed by the task.

maestro.finish_task(
    task_id=task.id,
    status=AutomationTaskFinishStatus.SUCCESS,
    message="Task Finished with Success.",
    total_items=100, # Total number of items processed
    processed_items=90, # Number of items processed successfully
    failed_items=10 # Number of items processed with failure
)

maestro.finishTask(
    task.id,
    "Task Finished with Success.",
    FinishStatus.SUCCESS,
    100, // Total number of items processed
    90, // Number of items processed successfully
    10 // Number of items processed with failure
);

await maestro.finishtTask(
    task.id,
    "Task finished with Success.",
    "SUCCESS",
)

await maestro.finishtTask(
    task.id,
    "Task finished with Success.",
    "SUCCESS"
)

Retrieving a task¶

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

Using the ID of a specific task¶

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

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

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

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

Getting the current execution reference¶

As we saw previously, the Maestro SDK has a special method to obtain the reference of the current task being executed by the Runner.

This way, we can access execution information more practically.

# Getting 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 {
        ...

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

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

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

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

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

Accessing task parameters¶

One of the pieces of information we can access from a task is the input parameters it receives.

The parameters of a task are treated as a dictionary; to access a value, we can pass the label that was used to create the parameter in BotCity Maestro as a key.

See more details on how to parameterize automation in Maestro through the Automations section.

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

# Getting parameter by label
parameter = execution.parameters.get("<PARAMETER_LABEL>")

public void action(BotExecution botExecution) {

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

        // Getting parameter by label
        Object parameter = botExecution.getParams().get("<PARAMETER_LABEL>");
    ...

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

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

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

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

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

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