Saltar a contenido

Tareas

Las Tareas son instancias de una Automatización. En esta sección encontrarás información sobre cómo crear, manipular y obtener información de una tarea a través del SDK.

Orquestador BotCity

También puedes hacer uso de la funcionalidad de Tareas directamente en la plataforma del Orquestador BotCity.

Consulta más en:

Crear una tarea

Puedes crear una nueva tarea a través del BotCity Maestro SDK.

Para ello, necesitas la siguiente información:

  • Activity label: Identificador de la automatización
  • Parámetros: Diccionario con valores de parámetros
  • Prueba: (opcional) Define la tarea como tarea de prueba
  • Prioridad: (opcional) Valor de 0 a 10 para la gestión de la cola
  • Fecha de ejecución mínima: (opcional) Fecha mínima para que la ejecución ocurra

Aviso sobre zona horaria

Las zonas horarias de los servidores del Orquestador BotCity están en UTC.

Por lo tanto, recuerda considerar la diferencia entre las zonas horarias si utilizas el parámetro min_execution_date en la creación de la tarea.

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

Interrumpir una tarea

Para tareas de larga ejecución, como el procesamiento por lotes de ítems, puede ser conveniente permitir que los usuarios soliciten su interrupción.

En este contexto, puedes implementar en el código una forma de verificar si la tarea debe detenerse o continuar.

Puedes incluir el método para solicitar una interrupción para una determinada tarea.

Para ello, necesitas la siguiente información:

  • ID de la tarea: Identificador de la tarea en ejecución

¡Atención!

Ten en cuenta que la tarea solo se interrumpirá si se realiza la implementación correcta.

Es responsabilidad del desarrollador del código del robot verificar el retorno del método de solicitud de interrupción (verdadero o falso) y actuar en consecuencia para interrumpir la tarea.

maestro.interrupt_task(task_id=<TASK_ID>)

maestro.interruptTask(<TASK_ID>);

await maestro.InterruptTaskAsync(<TASK_ID>);

Sugerencia de implementación

Es responsabilidad del desarrollador del código del robot verificar el retorno del método de solicitud de interrupción (verdadero o falso) y actuar en consecuencia para interrumpir la tarea.

La lógica debe aplicarse para realizar una verificación durante la ejecución de la tarea, por ejemplo:

while not maestro.get_task(task_id=<TASK_ID>).is_interrupted():
    # Continuando el procesamiento de los ítems
    print("Procesando ítems")
    ...
print("Se ha solicitado una interrupción")

while(!maestro.getTask(<TASK_ID>).getInterrupted()) {
    // Continuando el procesamiento de los ítems
    System.out.println("Procesando ítems");
    ...
}
System.out.println("Se ha solicitado una interrupción.");

Consejo

Puedes implementarlo junto con la lectura de una lista de ítems a procesar y verificar la interrupción antes de que se procese el siguiente ítem.

La fuente de esta lista de ítems puede ser variada, como: archivos Excel, archivos CSV, lectura de base de datos, integración con Datapool, entre otras.

Finalizar tarea y reportar datos

El ciclo de vida básico de una tarea es:

  • Crear: La tarea es creada y encolada en el Orquestador BotCity (Iniciado).
  • Ejecutar: La tarea es ejecutada por el Runner en el entorno de producción (Ejecutando).
  • Finalizar: La tarea tiene su estado y datos reportados directamente en el código, conforme al flujo definido.

Definir estado final

El reporte del estado de finalización e información de datos de ejecución debe implementarse en el código, siguiendo las reglas de negocio para definir qué estado asignar al final de la tarea.

Es responsabilidad del desarrollador de la automatización informar al Orquestador BotCity a través del SDK sobre el estado final adecuado de una tarea.

Una tarea puede concluirse con uno de los siguientes estados:

  • SUCCESS: La tarea se completó con éxito.
  • FAILED: La tarea no se completó.
  • PARTIALLY_COMPLETED: La tarea completó parte de las etapas esperadas.

Definir datos

Además de reportar el estado de finalización de una tarea, también puedes reportar datos adicionales referentes a los ítems que fueron procesados durante la ejecución.

Este reporte permite un mejor control y también añade detalles sobre la conclusión de la tarea que pueden ser inspeccionados posteriormente por los equipos en el Orquestador BotCity. Este recurso es muy útil en los casos donde necesitas monitorear la cantidad de ítems procesados con éxito o fallo por la tarea.

Para finalizar una tarea de forma completa, necesitas la siguiente información:

  • ID de la tarea: Identificador de la tarea
  • Estado: Estado de finalización, definido con la clase AutomationTaskFinishStatus:
    • SUCCESS: La tarea se completó con éxito
    • FAILED: La tarea no se completó
    • PARTIALLY_COMPLETED: La tarea completó parte de las etapas esperadas
  • Mensaje: Texto personalizado para la finalización
  • Total de ítems: Número total de ítems ejecutados
  • Ítems procesados: Número de ítems procesados con éxito
  • Ítems con fallo: Número de ítems procesados con fallo

¿Qué es un ítem?

El concepto de ítem puede ser cualquier entidad referente a tu proceso de automatización.

De esta forma, puedes utilizar la lógica que sea necesaria para el proceso y definir cómo cada ítem será consumido, procesado y contabilizado en el código.

Al final, reportar estos datos a través del método finish_task del Maestro SDK.

maestro.finish_task(
    task_id=<TASK_ID>,
    status=AutomationTaskFinishStatus.SUCCESS,
    message="La tarea se completó con éxito.",
    total_items=100,
    processed_items=90,
    failed_items=10
)

maestro.finishTask(
    <TASK_ID>,
    "La tarea se completó con éxito.",
    FinishStatus.SUCCESS,
    100,
    90,
    10
);

await maestro.finishtTask(
    <TASK_ID>,
    "La tarea se completó con éxito.",
    "SUCCESS",
    100,
    90,
    10
)

await maestro.finishtTask(
    <TASK_ID>,
    "La tarea se completó con éxito.",
    "SUCCESS",
    100,
    90,
    10
)

await maestro.FinishTaskAsync(
    <TASK_ID>,
    FinishStatusEnum.SUCCESS,
    "La tarea se completó con éxito.",
    100,
    90,
    10
);

Importante

Es importante que los datos de cuantificación de ítems procesados sean reportados al final de cada tarea. La etapa de reportar los datos en el código de la automatización es esencial para que la información de alto nivel sea generada en el módulo BotCity Insights.

BotCity Insights es un módulo dedicado a reportar y mostrar datos referentes a tu iniciativa de automatización.

Consulta más en:

Obtener información de una tarea

Puedes buscar la información de una tarea utilizando el ID o a través de la referencia de la ejecución actual.

Utilizar el ID de una tarea específica

Puedes buscar información general de una tarea a través de su ID, independientemente de su estado, utilizando el siguiente método:

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

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

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

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

AutomationTask task = await instance.GetTaskAsync("<TASK_ID>");
Ejemplo de retorno 
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>'
    )

Obtener el ID de la tarea actual

El Maestro SDK tiene un método especial que devuelve la información de una tarea en ejecución en el Runner.

Este método facilita la obtención del ID de la tarea y sus parámetros actuales, como se muestra en el ejemplo:

# Obteniendo los detalles de la tarea actual en ejecución
execution = maestro.get_execution()

# Información de la tarea que está siendo ejecutada
print(f"Task ID is: {execution.task_id}")
print(f"Task Parameters are: {execution.parameters}")

Info

El objeto BotExecution por defecto ya viene configurado en la plantilla de proyecto Java de BotCity.

public void action(BotExecution botExecution) {

    try {
        ...

        // Información de la tarea que está siendo ejecutada
        System.out.println(botExecution.getTaskId());
    ...

// Obteniendo los parámetros pasados por el Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Obteniendo los detalles de la tarea actual en ejecución
const executionTask = await maestro.getTask(taskid)

// Obteniendo los parámetros pasados por el Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Obteniendo los detalles de la tarea actual en ejecución
const executionTask: Task = await maestro.getTask(taskid)

using Dev.BotCity.MaestroSdk.Model.Execution;

// Obteniendo los detalles de la tarea actual en ejecución
Execution execution = await maestro.GetExecutionAsync(maestro.GetTaskId());

// Información de la tarea que está siendo ejecutada
Console.WriteLine("Task ID is: " + execution.TaskId);
Console.WriteLine("Task Parameters are: " + string.Join(", ", execution.Parameters));
Ejemplo de retorno 
Task ID is: <TASK_ID>
Task Parameters are: {'<PARAM_LABEL>': '<VALUE>'}

Parámetros de una tarea

Cada tarea puede informar valores diferentes para el procesamiento. Los parámetros pueden utilizarse para agregar esta dinamicidad a los procesos.

¿Cómo crear parámetros?

Los parámetros pueden configurarse directamente en las Automatizaciones dentro del Orquestador BotCity.

Acceder a los parámetros de una tarea

Al crear una tarea de una automatización con parámetros, puedes obtener estos valores dinámicos directamente en el código.

Para ello, necesitas la siguiente información:

  • ID de la tarea: Identificador de la tarea
  • Label: Label de los parámetros registrados en la Automatización
# Instanciando el Maestro SDK
maestro = BotMaestroSDK.from_sys_args()
# Obteniendo los detalles de la tarea actual en ejecución
execution = maestro.get_execution()

# Obteniendo parámetro a través del label
parametro1 = execution.parameters.get("<PARAMETER_LABEL1>")
parametro2 = execution.parameters.get("<PARAMETER_LABEL2>")

Info

El objeto BotExecution por defecto ya viene configurado en la plantilla de proyecto Java de BotCity.

public void action(BotExecution botExecution) {

    try {
        // Instanciando el Maestro SDK
        // El objeto BotExecution contiene la información que es pasada por el Runner
        BotMaestroSDK maestro = new BotMaestroSDK();
        maestro.login(botExecution);

        // Obteniendo parámetro a través del label
        Object parametro1 = botExecution.getParams().get("<PARAMETER_LABEL1>");
        Object parametro2 = botExecution.getParams().get("<PARAMETER_LABEL2>");
    ...

// Obteniendo los parámetros pasados por el Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Instanciando el Maestro SDK
const maestro = new BotMaestroSdk()
maestro.login("<SERVER>", "<LOGIN>", "<CLAVE>")

// Obteniendo los detalles de la tarea actual en ejecución
const executionTask = await maestro.getTask(taskid)

// Obteniendo los parámetros pasados por el Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Instanciando el Maestro SDK
const maestro: BotMaestroSdk = new BotMaestroSdk()
maestro.login("<SERVER>", "<LOGIN>", "<CLAVE>")

// Obteniendo los detalles de la tarea actual en ejecución
const executionTask: Task = await maestro.getTask(taskid)

using Dev.BotCity.MaestroSdk.Model.Execution;

// Instanciando el Maestro SDK
BotMaestroSDK maestro = BotMaestroSDK.FromSysArgs();
// Obteniendo los detalles de la tarea actual en ejecución
Execution execution = await maestro.GetExecutionAsync(maestro.GetTaskId());

// Obteniendo parámetro a través del label
var parameter1 = execution.Parameters["<PARAMETER_LABEL>1"];
var parameter2 = execution.Parameters["<PARAMETER_LABEL>2"];
Ejemplo de retorno 
<PARAMETER_VALUE1>
<PARAMETER_VALUE2>