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:

PythonJavaJavascriptTypescript

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:

PythonJavaJavascriptTypescript

maestro.interrupt_task(task_id=task.id)

maestro.interruptTask(task.id);

// Not implemented yet

// Not implemented yet

Important

Please not that it is not a guarantee that the task will be interrupted.

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

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:

PythonJavaJavascriptTypescript

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.

Tip

Basically, an item can be any entity related to your automation process.

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

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

PythonJavaJavascriptTypescript

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"
)

Info

The feature of reporting data is also part of the BotCity Insights, which is a module dedicated to reporting and displaying data related to your RPA initiative.

The step of reporting the data in the automation code is essential for the high-level information to be generated.

See more details about this module by accessing the BotCity Insights documentation.

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¶

PythonJavaJavascriptTypescript

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.

PythonJavaJavascriptTypescript

# 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}")

Info

By default, the BotExecution object is 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 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.

PythonJavaJavascriptTypescript

# 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>")

Info

By default, the BotExecution object is already configured in the BotCity Java project template.

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)