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¶

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.

Here is how we finish the task created on the previous step:

PythonJavaJavascriptTypescript

maestro.finish_task(
    task_id=task.id,
    status=AutomationTaskFinishStatus.SUCCESS,
    message="Task Finished with Success."
)

maestro.finishTask(task.id, "Task Finished with Success.", FinishStatus.SUCCESS);

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¶

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)