Ir para o conteúdo

Tarefas

As Tarefas são instâncias de uma Automação, nessa seção você encontra informações de como criar, manipular e retornar informações de uma tarefa via SDK.

Orquestrador BotCity

Você também pode fazer uso da funcionalidade de Tarefas diretamente na plataforma do Orquestrador BotCity.

Veja mais em:

Criar uma tarefa

Você pode criar uma nova tarefa através do BotCity Maestro SDK.

Para isso, você precisa das seguintes informações:

  • Activity label: Identificador da automação
  • Parâmetros: Dicionário com valores de parâmetros
  • Teste:(opcional) Define como tarefa de teste
  • Prioridade:(opcional) Valor de 0 a 10 para gerenciamento da fila
  • Data de execução minima:(opcional) Data minima para que a execução aconteça

Aviso sobre timezone

Os fusos horários dos servidores do Orquestrador BotCity estão em UTC.

Portanto, lembre-se de considerar a diferença entre os fusos horários caso utilizar o parâmetro min_execution_date na criação da tarefa.

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

Interromper uma tarefa

Para tarefas de longa execução, como o processamento em lote de itens, pode ser sensato permitir que os usuários solicitem sua interrupção.

Nesse contexto, você pode implementar no código uma forma de verificação se a tarefa deve parar ou prosseguir.

Você pode incluir o método para solicitar uma interrupção para uma determinada tarefa.

Para isso, você precisa das seguintes informações:

  • ID da tarefa: Identificador da tarefa em execução

Atenção!

Por favor, note que a tarefa só será interrompida se for feita a implementação correta.

É responsabilidade do desenvolvedor do código do robô verificar o retorno do método de solicitação de interrupção (verdadeiro ou falso) e agir de acordo com ele para interromper a tarefa.

maestro.interrupt_task(task_id=<TASK_ID>)

maestro.interruptTask(<TASK_ID>);

await maestro.InterruptTaskAsync(<TASK_ID>);

Sugestão de implementação

É responsabilidade do desenvolvedor do código do robô verificar o retorno do método de solicitação de interrupção (verdadeiro ou falso) e agir de acordo com ele para interromper a tarefa.

A lógica deve ser aplicada para fazer uma verificação durante a execução da tarefa, por exemplo:

while not maestro.get_task(task_id=<TASK_ID>).is_interrupted():
    # Continuando o processamento dos itens
    print("Processando items")
    ...
print("Uma interrupção foi solicitada")

while(!maestro.getTask(<TASK_ID>).getInterrupted()) {
    // Continuando o processamento dos itens
    System.out.println("Processando items");
    ...
}
System.out.println("Uma interrupção foi solicitada.");

Dica

Você pode implementar em conjunto com a leitura de uma lista de itens a serem processados e verificar a interrupção antes que o próximo item seja processado.

A fonte dessa lista de itens pode ser variada como: aquivos excel, arquivos csv, leitura de banco de dados, integração com Datapool, entre outras.

Finalizar tarefa e reportar dados

O ciclo de vida básico de uma tarefa é:

  • Criar: A tarefa é criada e enfileirada no Orquestrador BotCity (Aguardando).
  • Executar: A tarefa é executada pelo Runner no ambiente de produção (Executando).
  • Finalizar: A tarefa tem seu estado e dados reportados diretamente no código, conforme o fluxo definido.

Definir estado final

O reporte do estado de finalização e informação de dados de execução deve ser implementado no código, seguindo as regras de negócio para definir qual estado atribuir ao final da tarefa.

É responsabilidade do desenvolvedor da automação informar ao Orquestrador BotCity através do SDK sobre o estado final adequado de uma tarefa.

Uma tarefa pode ser concluída com um dos seguintes estados:

  • SUCCESS: A tarefa foi concluída com sucesso.
  • FAILED: A tarefa não foi concluída.
  • PARTIALLY_COMPLETED: A tarefa concluiu parte das etapas esperadas.

Definir dados

Além de reportar o estado de finalização de uma tarefa, você também pode reportar dados adicionais referentes aos itens que foram processados durante a execução.

Esse reporte permite um melhor controle e também adiciona detalhes sobre a conclusão da tarefa que pode ser inspecionada posteriormente pelos times no Orquestrador BotCity. Esse recurso é muito útil nos casos onde você precisa monitorar a quantidade de itens processados com sucesso ou falha pela tarefa.

Para finalizar uma tarefa de forma completa, você precisa das seguintes informações:

  • ID da tarefa: Identificador da tarefa
  • Estado: Estado de finalização, definidos com a classe AutomationTaskFinishStatus:
    • SUCCESS: A tarefa foi concluída com sucesso
    • FAILED: A tarefa não foi concluída
    • PARTIALLY_COMPLETED: A tarefa concluiu parte das etapas esperadas
  • Mensagem: Texto customizado para a finalização
  • Total de itens: Número total de itens executados
  • Itens processados: Número de itens processados com sucesso
  • Itens com falha: Número de itens processados com falha

O que é um item?

O conceito de item pode ser qualquer entidade referente ao seu processo de automação.

Dessa forma, você pode utilizar a lógica que for necessária para o processo e definir como cada item será consumido, processado e contabilizado no código.

Ao final, reportar esses dados através do método finish_task do Maestro SDK.

maestro.finish_task(
    task_id=<TASK_ID>,
    status=AutomationTaskFinishStatus.SUCCESS,
    message="Tarefa foi concluída com sucesso.",
    total_items=100,
    processed_items=90,
    failed_items=10
)

maestro.finishTask(
    <TASK_ID>,
    "Tarefa foi concluída com sucesso.",
    FinishStatus.SUCCESS,
    100,
    90,
    10
);

await maestro.finishtTask(
    <TASK_ID>,
    "Tarefa foi concluída com sucesso.",
    "SUCCESS",
    100,
    90,
    10
)

await maestro.finishtTask(
    <TASK_ID>,
    "Tarefa foi concluída com sucesso.",
    "SUCCESS",
    100,
    90,
    10
)

await maestro.FinishTaskAsync(
    <TASK_ID>,
    FinishStatusEnum.SUCCESS,
    "Tarefa foi concluída com sucesso.",
    100,
    90,
    10
);

Importante

É importante que os dados de quantificação de itens processados seja reportado ao final de cada tarefa. A etapa de reportar os dados no código da automação é essencial para que as informações de alto nível sejam geradas no módulo BotCity Insights.

BotCity Insights é um módulo dedicado para reportar e exibir dados referentes à sua iniciativa de automação.

Veja mais em:

Retornar informações de uma tarefa

Você pode buscar as informações de uma tarefa utilizando o ID ou através da referência da execução atual.

Utilizar o ID de uma tarefa específica

Você pode buscar informações gerais de uma tarefa através do seu ID, independente de seu estado, utilizando o seguinte método:

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

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

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

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

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

Obter o ID da tarefa atual

O Maestro SDK possui um método especial que retorna as informações de uma tarefa em execução no Runner.

Esse método facilita o retorno do ID da tarefa e seus parametros atuais, veja o exemplo:

# Buscando os detalhes da tarefa atual sendo executada
execution = maestro.get_execution()

# Informações da tarefa que está sendo executada
print(f"Task ID is: {execution.task_id}")
print(f"Task Parameters are: {execution.parameters}")

Info

O objeto BotExecution por padrão já vem configurado no template de projeto Java da BotCity.

public void action(BotExecution botExecution) {

    try {
        ...

        // Informações da tarefa que está sendo executada
        System.out.println(botExecution.getTaskId());
    ...

// Obtendo parâmetros passados pelo Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Buscando os detalhes da tarefa atual sendo executada
const executionTask = await maestro.getTask(taskid)

// Obtendo parâmetros passados pelo Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

// Buscando os detalhes da tarefa atual sendo executada
const executionTask: Task = await maestro.getTask(taskid)

using Dev.BotCity.MaestroSdk.Model.Execution;

// Buscando os detalhes da tarefa atual sendo executada
Execution execution = await maestro.GetExecutionAsync(maestro.GetTaskId());

// Informações da tarefa que está sendo executada
Console.WriteLine("Task ID is: " + execution.TaskId);
Console.WriteLine("Task Parameters are: " + string.Join(", ", execution.Parameters));
Exemplo de retorno 
Task ID is: <TASK_ID>
Task Parameters are: {'<PARAM_LABEL>': '<VALUE>'}

Parâmetros de uma tarefa

Cada tarefa pode informar valores diferentes para o processamento, os parâmetros podem ser utilizados para adicionar essa dinamicidade nos processos.

Como criar parâmetros?

Os parâmetros podem ser configurados diretamente nas Automações dentro do Orquestrador BotCity.

Acessar os parâmetros de uma tarefa

Ao criar uma tarefa de uma automação com parâmetros, você pode retornar esses valores dinâmicos diretamente no código.

Para isso, você precisa das informações:

  • ID da tarefa: Identificador da tarefa
  • Label: Label dos parâmetros cadastrados na Automação
# Instanciando o Maestro SDK
maestro = BotMaestroSDK.from_sys_args()
# Buscando os detalhes da tarefa atual sendo executada
execution = maestro.get_execution()

# Obtendo parâmetro através do label
parametro1 = execution.parameters.get("<PARAMETER_LABEL1>")
parametro2 = execution.parameters.get("<PARAMETER_LABEL2>")

Info

O objeto BotExecution por padrão já vem configurado no template de projeto Java da BotCity.

public void action(BotExecution botExecution) {

    try {
        // Instanciando o Maestro SDK
        // O objeto BotExecution contém as informações que são passadas pelo Runner
        BotMaestroSDK maestro = new BotMaestroSDK();
        maestro.login(botExecution);

        // Obtendo parâmetro através do label
        Object parametro1 = botExecution.getParams().get("<PARAMETER_LABEL1>");
        Object parametro2 = botExecution.getParams().get("<PARAMETER_LABEL2>");
    ...

// Obtendo parâmetros passados pelo Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

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

// Buscando os detalhes da tarefa atual sendo executada
const executionTask = await maestro.getTask(taskid)

// Obtendo parâmetros passados pelo Runner
const args = process.argv.slice(2)
const [server, taskid, token] = args

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

// Buscando os detalhes da tarefa atual sendo executada
const executionTask: Task = await maestro.getTask(taskid)

using Dev.BotCity.MaestroSdk.Model.Execution;

// Instanciando o Maestro SDK
BotMaestroSDK maestro = BotMaestroSDK.FromSysArgs();
// Buscando os detalhes da tarefa atual sendo executada
Execution execution = await maestro.GetExecutionAsync(maestro.GetTaskId());

// Obtendo parâmetro através do label
var parameter1 = execution.Parameters["<PARAMETER_LABEL>1"];
var parameter2 = execution.Parameters["<PARAMETER_LABEL>2"];
Exemplo de retorno 
<PARAMETER_VALUE1>
<PARAMETER_VALUE2>