Ir para o conteúdo

Gerenciar Itens

O Datapool permite gerenciar de forma eficiente o processamento de itens em lote.

Os itens são as unidades de dados que serão processadas pela automação através do Datapool. Cada item é composto por um conjunto de campos definidos no Schema do Datapool, que representam as informações necessárias para o processamento.

Nas seções a seguir, você encontrará mais detalhes sobre o funcionamento de Datapools e como utilizar esses recursos em conjunto com seus processos de automação.

Captura de tela de visão geral de um Datapool. Na parte superior as informações gerais: Detalhes do datapool contendo seu status, quantidade de Itens Totais, tempo médio por item; Itens em Processamento contendo Itens Pendentes, Itens Processados e Itens concluidos; Casos de exceção contendo Itens com Erro, Itens em espera e Itens cancelados. Logo abaixo, barra de pesquisa, filtros e botões de Ações: Adicionar Itens, Importar CSV e ações em massa. Na parte inferior a seção de Itens do Datapool, exibindo uma tabela com os campos Entrada, Prioridade, Estado, Mensagem de finalização, Tipo de erro, Auto-retry, Tempo de processamento, Ciclo de vida de cada item.

Gerador de Snippet

As ações de manipulação dos itens do Datapool podem ser realizadas diretamente na plataforma do Orquestrador BotCity ou via código, utilizando o BotCity Maestro SDK ou a BotCity Orquestrador API.

Explore o botão Gerador de Snippet para obter exemplos de código que facilitam as manipulações de Datapool utilizando o SDK do BotCity Maestro. Gere trechos de código para as ações: Consumir itens do Datapool, Manipular um item do Datapool, Operações com Datapool e Adicionar novos itens.

Os snippets gerados estão disponiveis nas linguagens Python.

Imagem do botão Gerador de Snippet presente no Orquestrador BotCity

Adicionar novos itens ao Datapool

Você pode adicionar novos itens ao Datapool de diversas formas:

  • Item unitário: Preenchendo os valores manualmente, diretamente na plataforma.
  • Importar CSV: Múltiplos itens de uma só vez, através do upload de um arquivo .csv.
  • Via código: Itens por código:

Adicionar itens manualmente

Para casos excepcionais, você pode adicionar itens individualmente, preenchendo os valores diretamente na plataforma da seguinte maneira:

  • No painel principal do Datapool, clique em + Adicionar entrada
  • Defina a prioridade do item (0 menor a 10 maior)
  • Preencha os valores dos campos conforme o Schema definido
  • (opcional) Adicione novos campos ao item clicando em + Entrada, caso necessário
  • Clique em Salvar para dar entrada desse novo item

Captura de tela do formulário de adição manual de um novo item ao Datapool. Apresenta o campo de Prioridade com valor 0 selecionado; os campos do Schema exibindo seus respectivos labels e campos para preenchimento dos valores; o botão de Adicionar nova entrada para incluir novos campos ao item; o botão de cancelar ação; e o botão Salvar para salvar o novo item no Datapool.

Adicionar itens via CSV

Você pode incluir vários itens de uma só vez importando um arquivo .csv da seguinte maneira:

  • No painel principal do Datapool, clique no botão Importar CSV
  • Uma nova janela abrirá
  • Baixe o arquivo de exemplo disponibilizado no link
  • Preencha o arquivo com os dados dos itens que serão adicionados
  • Suba o arquivo preenchido
  • Veja um preview dos itens que serão adicionados
  • Clique no botão Adicionar para dar entrada desses novos itens

Atenção

Dependendo da configuração de valor único definida no Schema do Datapool, itens duplicados podem ser rejeitados durante a importação.

GIF apresentando o fluxo de adição de itens via CSV à fila do Datapool. Clica no botão Importar CSV; arrasta o arquivo CSV com os dados dos itens para o campo; visualiza o preview dos itens que serão adicionados; clica no botão Adicionar para carregar os itens automaticamente.

Adicionar itens via SDK

Para adicionar itens via código, você pode utilizar o BotCity Maestro SDK para criar uma automação que insira os itens no Datapool.

O SDK oferece métodos simples para interagir com o Datapool, essa funcionalidade está disponível nas linguagens Python e C#.

Maestro SDK

Para mais informações de como implementar a funcionalidade de Datapool em código, veja na seção Datapool do Maestro SDK.

Adicionar itens via API

A API do Orquestrador BotCity também permite que você adicione itens ao Datapool fazendo requisições HTTP. Essa funcionalidade é útil para integrar sistemas externos que precisam inserir dados no Datapool ou utilizar outras linguagens de programação que não possuem suporte do SDK.

Maestro API

Para mais informações de como implementar a funcionalidade de Datapool via API, veja na seção Integrações com a API.

Manipular os itens do Datapool

O fluxo básico de um item consiste em:

  • Adicionar um novo item
  • O item é puxado para processamento
  • O item é finalizado com sucesso ou erro

Visualizar as informações

Cada item do Datapool possui diversas informações que podem ser visualizadas diretamente na plataforma do Orquestrador BotCity.

Na lista de itens do Datapool, você pode visualizar as seguintes informações em colunas:

  • Entrada: Valor dos campos que foram marcados no Schema para serem exibidos, caso nenhum campo tenha sido marcado, será exibido o ID do item. (Veja mais sobre criação do Schema).
  • Prioridade: A prioridade definida para o item, itens com prioridades mais altas serão processados primeiro.
  • Estado: O estado atual do item no Datapool.
  • Mensagem de finalização: A mensagem de finalização customizada reportada via código ao final do processamento.
  • Tipo de erro: O tipo de erro reportado via código ao final do processamento, caso o item tenha sido processado com falha.
    • SYSTEM: Sinaliza que o erro no processamento foi causado por um erro de sistema. Esse será o tipo padrão caso não seja especificado no reporte.
    • BUSINESS: Sinaliza que o erro no processamento foi causado por uma falha de negócio, ou seja, o item finalizou com erro devido a alguma regra de negócio específica.
  • Auto-retry: Representa o número da tentativa de processamento, em caso de itens que foram reprocessados.
  • Tempo de processamento: O tempo gasto no processamento do item.
  • Ciclo de vida: O tempo levado desde a criação do item no Datapool até a finalização do processamento.

Captura de tela de visão geral de um Datapool. Na parte superior as informações gerais: Detalhes do datapool contendo seu status, quantidade de Itens Totais, tempo médio por item; Itens em Processamento contendo Itens Pendentes, Itens Processados e Itens concluidos; Casos de exceção contendo Itens com Erro, Itens em espera e Itens cancelados. Logo abaixo, barra de pesquisa, filtros e botões de Ações: Adicionar Itens, Importar CSV e ações em massa. Na parte inferior a seção de Itens do Datapool, exibindo uma tabela com os campos Entrada, Prioridade, Estado, Mensagem de finalização, Tipo de erro, Auto-retry, Tempo de processamento, Ciclo de vida de cada item. A lista apresenta vários itens com diferentes informações de processamento.

Ao expandir os detalhes de um item clicando em ▼, você pode visualizar as seguintes informações adicionais:

  • Item: O identificador único do item.
  • Prioridade: A prioridade definida para o item.
  • Task ID: O identificador da tarefa responsável por acessar e consumir aquele item do Datapool.
  • Data de criação: A data em que o item foi adicionado ao Datapool.
  • Data de processamento: A data em que o item foi puxado para ser processado.
  • Estado: O estado atual do item no Datapool.
  • Tempo de processamento: O tempo gasto no processamento do item.
  • Runner: O Runner responsável pela execução da tarefa que consumiu o item.
  • Auto-retry: Representa o número da tentativa de processamento, em caso de itens que foram reprocessados.
  • Mensagem de finalização: A mensagem de finalização customizada reportada via código ao final do processamento.
  • Dados específicos do item: Os conjuntos de chave/valor definidos no Schema que compõem o item do Datapool.
  • Botão de Editar: Permite editar os valores do item, caso ele esteja no estado PENDENTE.
  • Histórico de reprocessamentos: Exibe o histórico de tentativas de processamento do item, caso ele tenha sido reprocessado.

Captura de tela de detalhes de um item no Datapool. Apresenta as informações detalhadas do item encontrado através do e-mail: ID do item; Prioridade; Task Id; Data de criação; Data de processamento; Estado; Tempo de processamento; Runner; Auto-retry; Mensagem de finalização; Dados específicos do item exibindo os campos e valores preenchidos.

Estados de processamento

Ao adicionar um item no Datapool, ele terá o estado inicial de PENDENTE. Esse estado pode alterar conforme o fluxo de processamento do item.

Veja quais são os estados possíveis de um item no Datapool:

PENDENTE: O item está aguardando o processamento, nesse ponto ele estará disponível para ser acessado e consumido.

PROCESSANDO: O item foi puxado para execução e está na fase de processamento.

CONCLUÍDO: O processamento do item foi concluído com sucesso.

ERRO: O processamento do item foi concluído com erro.

  • SYSTEM: Indica que o erro no processamento foi causado por um erro de sistema.
  • BUSINESS: Indica que o erro no processamento foi causado por uma falha nas regras de negócio. Erros do tipo BUSINESS não são considerados nos cenários de Auto-retry e Abortar em casos de erro.

CANCELADO: O item foi cancelado e não será puxado para processamento.

TIMEOUT: O tempo de processamento do item passou do limite definido.

Entendendo o estado de TIMEOUT

O estado de TIMEOUT é baseado no tempo que foi definido na propriedade Tempo de processamento ao criar o Datapool.

Caso o processamento de um item exceda o tempo máximo definido, automaticamente o Datapool indicará que aquele item entrou em um estado de TIMEOUT.

Esse tempo pode exceder por diversos motivos como por falta do reporte indicando o estado final do item ou algum travamento na execução do processo que impeça que o reporte seja feito.

Esse estado não significa necessariamente um erro, pois um item ainda pode sair do estado de TIMEOUT para um estado de CONCLUÍDO ou ERRO. Porém, caso o processo não se recupere (em caso de eventuais travamentos) e o reporte do estado do item não seja feito, o Datapool automaticamente vai considerar o estado daquele item como ERRO após um período de 24 horas em TIMEOUT.

Editar valores de itens

Os itens que estão com estado PENDENTE, ou seja, ainda não foram processados, podem ser editados, alterando os valores preenchidos e adicionar novos campos.

Para editar um item, siga os passos abaixo:

  • No painel principal do Datapool, localize o item que deseja editar
  • Expanda os detalhes do item clicando em ▼
  • Clique em Editar
  • Altere os valores desejados
  • (opcional) Adicione novos campos ao item clicando em + Entrada, caso necessário
  • Clique em Salvar para salvar as alterações

GIF apresentando o fluxo de edição de valores de um item adicionado à fila do Datapool. Seleciona um item, expande os detalhes do item clicando no ícone de expansão; clica no botão Editar; adiciona um novo campo ditando o label e o valor; clica no botão Salvar; visualiza os novos valores nos detalhes do item.

Consumir os itens da fila

Para processar os itens do Datapool, é necessário que a automação consuma os itens pendentes através do código.

Maestro SDK

Para mais informações de como implementar a funcionalidade de Datapool em código, veja na seção Datapool do Maestro SDK.

Captura de tela de visão geral de um Datapool. Na parte superior as informações gerais: Detalhes do datapool contendo seu status, quantidade de Itens Totais, tempo médio por item; Itens em Processamento contendo Itens Pendentes, Itens Processados e Itens concluidos; Casos de exceção contendo Itens com Erro, Itens em espera e Itens cancelados. Logo abaixo, barra de pesquisa, filtros e botões de Ações: Adicionar Itens, Importar CSV e ações em massa. Na parte inferior a seção de Itens do Datapool, exibindo uma tabela com os campos Entrada, Prioridade, Estado, Mensagem de finalização, Tipo de erro, Auto-retry, Tempo de processamento, Ciclo de vida de cada item. Os itens estão com estado Pendente e apenas um com estado Processando.

Reportar o estado de um item

A etapa de reportar o estado de finalização de um item é crucial para que os estados e contadores do Datapool sejam atualizados corretamente.

Para isso, é necessário que o estado final de processamento de cada item (CONCLUÍDO ou ERRO) seja reportado via código dentro da lógica do processo.

Caso o estado de processamento do item não seja reportado por algum motivo, podem ocorrer dois cenários:

  1. Processando: O item permanecerá no estado de PROCESSANDO, mesmo que tenha finalizado o processamento.

  2. Timeout: Caso o tempo de processamento ultrapasse o valor definido na propriedade Tempo de processamento durante a configuração do Datapool, isso fará com que o Datapool atribua automaticamente um estado de TIMEOUT para aquele item.

Maestro SDK

Para mais informações de como implementar a funcionalidade de Datapool em código, veja na seção Datapool do Maestro SDK.

Datapool <> BotCity Insights

O reporte de itens no Datapool NÃO possui impacto direto nas métricas calculadas pelo BotCity Insights.

Para ter as métricas atualizadas, é estritamente necessário:

  • Garantir que os dados financeiros das automações estejam devidamente configurados na seção Entrada de Dados dentro do Insights.
  • Garantir que o reporte dos itens processados esteja sendo feito corretamente na finalização da tarefa, ao final da execução.

Veja mais detalhes na seção BotCity Insights.

Operações com itens do Datapool

Além de visualizar as informações, podemos realizar algumas operações ao acessar o menu de ações de cada item.

Captura de tela de visão geral de um Datapool. Na parte superior as informações gerais: Detalhes do datapool contendo seu status, quantidade de Itens Totais, tempo médio por item; Itens em Processamento contendo Itens Pendentes, Itens Processados e Itens concluidos; Casos de exceção contendo Itens com Erro, Itens em espera e Itens cancelados. Logo abaixo, barra de pesquisa, filtros e botões de Ações: Adicionar Itens, Importar CSV e ações em massa. Na parte inferior a seção de Itens do Datapool, exibindo uma tabela com os campos Entrada, Prioridade, Estado, Mensagem de finalização, Tipo de erro, Auto-retry, Tempo de processamento, Ciclo de vida de cada item. Destaca o menu de ações de um item específico com as opções Reiniciar, Cancelar e Deletar.

  • Reiniciar: Reinsere na fila o item que já foi processado e está com estado de CONCLUÍDO ou ERRO.
  • Duplicar: Cria uma cópia do item com estado CANCELADO para ser processado.
  • Cancelar: Cancela um item PENDENTE. Nesse caso, o item será ignorado durante o consumo da fila.
  • Deletar: Remove o item da fila e do histórico do Datapool. Não é possível excluir itens no estado de PROCESSANDO ou TIMEOUT.

Reiniciando itens que possuem campos de ID único

Caso você esteja utilizando campos com função de ID único, não será possível reiniciar ou duplicar um item que já tenha sido processado.

Nesse caso, é necessário que o item existente seja excluído para que um novo item que utiliza o mesmo ID único possa ser inserido no Datapool.

Dica

Através do recurso Ações em massa também é possível cancelar ou deletar múltiplos itens, caso você precise realizar essas operações para um grande volume de entradas.

Filtrar itens na fila

O Datapool possui um recurso de filtro, que permite a busca por itens da fila filtrando pela data de inserção ou estado atual do item.

Além disso, também é possível buscar por um item específico utilizando os valores da coluna Entrada como filtros.

Importante

Para que um campo possa ser usado na busca, é necessário que a opção Exibir valor esteja marcada na configuração do campo dentro do Schema.

Captura de tela de visão geral de um Datapool. Na parte superior as informações gerais: Detalhes do datapool contendo seu status, quantidade de Itens Totais, tempo médio por item; Itens em Processamento contendo Itens Pendentes, Itens Processados e Itens concluidos; Casos de exceção contendo Itens com Erro, Itens em espera e Itens cancelados. Logo abaixo, barra de pesquisa, filtros e botões de Ações: Adicionar Itens, Importar CSV e ações em massa. Na parte inferior a seção de Itens do Datapool, exibindo uma tabela com os campos Entrada, Prioridade, Estado, Mensagem de finalização, Tipo de erro, Auto-retry, Tempo de processamento, Ciclo de vida de cada item. Destaca a seção de filtros, exibindo os filtros de Estado do item, valor de entrada e data de criação combinados.

Exportar dados dos itens

É possível exportar os dados dos itens do Datapool para análise externa ou integração com outras plataformas.

Para exportar os dados, siga os passos abaixo:

  • Filtre os itens que deseja exportar, caso necessário
  • Clique no botão de Exportar
  • Escolha o formato desejado: CSV, Excel ou JSON
  • Baixe o arquivo gerado com os dados dos itens

Ao exportar os dados, todas as informações visíveis na lista de itens do Datapool são incluidas, bem como os detalhes adicionais de processamento.

Limite de exportação

O limite máximo de itens que podem ser exportados de uma única vez pelo Orquestrador BotCity é de 30.000 itens. Se desejar exportar uma quantidade maior, utilize a BotCity Orquestrador API para realizar a extração dos dados em lotes.

Captura de tela de visão geral de um Datapool. Na parte superior as informações gerais: Detalhes do datapool contendo seu status, quantidade de Itens Totais, tempo médio por item; Itens em Processamento contendo Itens Pendentes, Itens Processados e Itens concluidos; Casos de exceção contendo Itens com Erro, Itens em espera e Itens cancelados. Destaca o menu de exportação de itens do Datapool, exibindo as opções de formato CSV, Excel e JSON para exportar os dados dos itens.