Módulo Orquestrador

O CITSmart X Orquestrador é o servidor de gestão da plataforma e o painel de operação que o acompanha. Nesta funcionalidade é possível acompanhar a frota de máquinas, os robôs publicados, as execuções, as filas de trabalho e os alertas, além de configurar gatilhos, recursos compartilhados e o acesso de cada pessoa.

O Orquestrador guarda e controla:

O desenho dos robôs é feito no CITSmart X Studio (veja o módulo Studio). Os modelos de IA, os provedores e o assistente são tratados em o módulo IA.

O painel é acessado pelo navegador, no endereço do servidor (por padrão http://localhost:8080). O menu lateral agrupa as telas pela pergunta que cada uma responde:

O menu pode ser recolhido para uma coluna de ícones com o botão “Recolher”, no rodapé do menu. Ao lado do menu, no rodapé, aparecem a identidade de quem está conectado (nome, papel e pastas) e o botão “sair”.

A tela e a API usam palavras diferentes, de propósito. Use a palavra da tela no dia a dia; a tabela abaixo traduz para quem integra pela API.

Job é uma execução de um robô em uma máquina. Os estados que aparecem nas telas são Pending (aguardando uma máquina), Running, Suspended (parado esperando uma pessoa decidir), Successful, Faulted e Stopped.

Um job que não está rodando tem sempre um motivo registrado, como falta de capacidade na máquina, grupo incompatível ou recurso compartilhado em uso. A tela Operação mostra esse motivo na seção “Jobs esperando”.

Fila é uma lista de itens de trabalho que as máquinas consomem. Cada item passa por New, InProgress e termina em Successful, Failed ou Abandoned. Veja Filas.

Cofre é o local onde ficam as credenciais usadas pelos robôs. O valor é cifrado no servidor e nunca é exibido nas telas. Veja Cofre e credenciais.

Todo robô publicado nasce em DEV e só chega a PROD depois de passar por HOMOLOG, com a aprovação de outra pessoa. O pacote aprovado é exatamente o que executa em produção. Veja Ciclo de vida e promoção.

Pasta é a unidade de isolamento entre áreas ou clientes. Cada pessoa enxerga apenas os registros das pastas a que tem acesso. Veja Auditoria e segurança.

Nesta funcionalidade é possível subir o CITSmart X Orquestrador, ajustar sua configuração pelo arquivo .env e entrar no painel de operação com um token de identidade ou com a conta da empresa.

A tela de entrada é exibida ao abrir o endereço do servidor no navegador, sempre que o acesso exige identificação.

Para subir a plataforma completa em ambiente de trabalho é necessário:

npm run subir

O comando sobe, em ordem, as dependências em contêiner (quando o Docker está disponível), o Orquestrador, uma máquina com o agente e o Studio. Cada serviço só é considerado pronto depois de responder, e o log de cada um fica em .nexo-data/logs/. Serviços que já estão no ar não são iniciados novamente.

Opções úteis:

Para subir apenas o Orquestrador:

npm run orchestrator

O painel fica disponível em http://localhost:8080, ou na porta definida em NEXO_PORT.

Nenhuma variável é obrigatória para a primeira subida, mas os avisos exibidos pelo servidor devem ser lidos. As principais são:

O servidor decide qual caminho de entrada oferecer.

Em instalações sem provedor de identidade, a tela de entrada exibe o campo “Token de identidade”.

Para entrar com token é necessário:

O token é trocado por uma sessão e não fica guardado no navegador. Ele pode ser o token de bootstrap definido em NEXO_TOKENS ou o token de uma identidade criada pela administração.

O formato de NEXO_TOKENS é:

Quando o servidor tem um provedor de identidade configurado (OIDC, como o Keycloak ou o Microsoft Entra ID), a tela de entrada exibe um botão com o texto “Entrar com a conta da empresa”, ou o texto definido em NEXO_OIDC_LABEL. Nesse caso o campo de token não é exibido.

Para configurar o provedor é necessário definir:

Depois de entrar, o rodapé do menu lateral mostra o nome, o papel e o escopo de pastas da pessoa, por exemplo “docs · admin · todas as pastas”. Ao passar o ponteiro sobre o papel, a tela informa os grupos recebidos do provedor, o que ajuda quando o papel não é o esperado.

Para encerrar a sessão é necessário selecionar o botão “sair”. A sessão é encerrada no servidor, e não apenas apagada do navegador. Quem administra pode consultar as sessões abertas e encerrá-las pela API (GET /api/auth/sessions e POST /api/auth/sessions/:id/revoke).

Por padrão, os dados ficam em arquivos na pasta de dados, o que atende a uma instalação pequena. Para volume maior, defina NEXO_DATABASE_URL.

Para migrar uma instalação que já tem dados em arquivo para o PostgreSQL é necessário:

A migração confere os registros copiados antes de informar sucesso, e a pasta de dados original permanece intacta.

É possível subir dois servidores Orquestradores sobre o mesmo banco. Apenas um deles, o líder, executa os trabalhos de fundo (agendamentos, varredura de gatilhos e avanço das orquestrações), o que evita disparos duplicados. Se o líder para normalmente, o outro assume em segundos; se o líder cai de forma abrupta, a troca leva cerca de 18 segundos.

Esse modo exige PostgreSQL. Com armazenamento em arquivo, dois servidores não enxergam as gravações um do outro, e o servidor avisa na subida.

O endereço /health informa qual nó é o líder e não exige credencial, o que o torna adequado para balanceadores e monitoramento.

Nesta funcionalidade é possível acompanhar, em uma única tela, o que está acontecendo na plataforma: os alertas abertos, a situação da frota de máquinas, as execuções das últimas 24 horas, as filas de trabalho, os pedidos de aprovação pendentes e a integridade da trilha de auditoria.

A funcionalidade pode ser acessada através do menu de navegação: Agora > Operação.

A tela é atualizada sozinha a cada 5 segundos, e o horário da última atualização aparece no canto superior direito, ao lado do texto “atualizado”. A atualização é suspensa enquanto há um campo em edição na tela.

A seção “Alertas abertos” é a primeira da tela porque lista o que exige ação. Cada alerta mostra:

A faixa colorida à esquerda indica a severidade: vermelha para crítico e âmbar para aviso.

Para reconhecer um alerta é necessário:

O alerta reconhecido deixa de aparecer na lista. As regras que geram os alertas estão descritas em Alertas e webhooks.

Abaixo dos alertas pode aparecer uma faixa de aviso informando que máquinas online não conseguem automatizar interface, porque a tela está bloqueada ou a máquina está na Sessão 0 do Windows. Os jobs de desktop não são despachados para essas máquinas.

A seção “Frota” reúne os indicadores principais:

Os cartões mudam de cor quando exigem atenção: verde para situação saudável, âmbar para atenção e vermelho para problema.

O gráfico “Últimas 24 horas” mostra, hora a hora, as execuções com sucesso e as com falha. Ao passar o ponteiro sobre uma coluna, a tela informa a hora e as quantidades.

Quando há jobs pendentes, a seção “Jobs esperando” mostra, para cada robô, quanto tempo o job está esperando e por quê. Os motivos possíveis são:

As duas tabelas lado a lado resumem a última semana.

A tabela “Robôs (7 dias)” tem as colunas:

A tabela “Máquinas” tem as colunas Máquina (nome e computador), Estado, Jobs 24h (com o número de falhas entre parênteses) e Utilização (percentual com barra; acima de 85% a barra fica âmbar).

A seção “Filas” aparece quando existem filas e mostra, por fila: Pendentes, Em processo, Sucesso, Falha, Lead time, Vazão/h, Mais antigo e Esvazia em (estimativa de esvaziamento). Veja Filas.

Quando o histórico de execuções indica uma oportunidade ou um problema recorrente, a seção “O que o histórico sugere” lista o impacto (alto, médio ou baixo), o achado, a evidência e o que fazer.

A seção “Esperando uma pessoa” lista as tarefas humanas pendentes, com o robô de origem, a quem a tarefa é dirigida, os desfechos possíveis, o tempo de espera e o prazo. As tarefas atrasadas são destacadas. Quem responde as tarefas usa a tela Tarefas.

A seção “Ciclo de vida” mostra:

Quando há pacotes em PROD sem assinatura verificável, uma faixa de aviso os lista. Veja Ciclo de vida e promoção.

Aparece quando existe inventário de hosts. Mostra os hosts no inventário, os grupos, os hosts sem contato e os hosts com desvio. Um desvio é encontrado por uma execução de conferência, que não aplica nenhuma alteração: quem decide corrigir é uma pessoa.

Aparece quando há assinantes de evento ou chaves de API. Mostra os assinantes de evento, os desativados, as entregas na fila, as entregas desistidas, as chaves de API válidas, as chaves que atingiram a cota nos últimos 15 minutos e os tokens de máquina vencendo. Veja Alertas e webhooks.

Aparece quando há execuções de orquestração em andamento ou reprovadas nas últimas 24 horas. Mostra, para cada execução aberta, o início, a contagem de nós por situação e o que cada nó está esperando. Os detalhes estão em Orquestrações.

Aparece quando há provedores de IA cadastrados. Mostra, por provedor, o tipo, os modelos, se o dado sai da rede, o resultado da última sonda e o último uso, além de chamadas, tokens e custo estimado. O cadastro de provedores é tratado no módulo IA.

Mostra por quantos dias são mantidos o log de execução, o argumento de job e o payload de fila, se o log é mascarado na ingestão e quantos valores já foram mascarados. Quando existe uma varredura de retenção, a tela informa o que foi removido na última execução. A trilha de auditoria não tem retenção. Veja Auditoria e segurança.

Aparece para quem pode ler a trilha de auditoria. Mostra o número de entradas e informa que a corrente está íntegra, seguido das ações recentes (quando, quem, ação, alvo e desfecho).

A última seção lista as execuções mais recentes com o robô, o estado, a máquina, a duração, o horário e a mensagem de erro, quando há.

Nesta funcionalidade é possível consultar os robôs publicados no Orquestrador, executar um robô na máquina de um usuário com a autorização dele e remover a publicação de uma versão.

A funcionalidade pode ser acessada através do menu de navegação: Agora > Robôs.



Cada robô aparece em um cartão com:

A lista exibe somente a versão mais recente de cada nome. As versões anteriores continuam existindo e são contadas ao lado do nome.

Para localizar um robô é necessário:

Esta é a execução assistida: alguém está em contato com o operador e precisa que o robô execute no computador dela, naquele momento. Diferente de uma máquina registrada, que recebe trabalho de forma contínua e sem ninguém presente, a execução assistida só acontece com a autorização da pessoa, dada por um código.

O código é gerado pelo aplicativo CITSmart RPA Client, que a pessoa abre no computador. O código:

Ao final da execução, a sessão volta a aguardar com um código novo.

Para executar um robô na máquina de um usuário é necessário:

Quando a execução é despachada, a tela informa a máquina e o identificador do job. Para desistir, selecione o botão “Cancelar”.

Remover a publicação apaga a versão escolhida do catálogo. O histórico de execuções permanece, pois cada execução guarda o nome, a versão e o hash copiados.

Para editar um robô não é necessário remover nada: abra o robô no Studio, altere e publique uma nova versão. A versão anterior continua existindo.

Para remover a publicação de uma versão é necessário:

A remoção é recusada, com a indicação da saída para cada caso, quando:

Quando a remoção é possível, a tela pode exibir avisos, como o número de execuções do histórico que continuam registradas, ou que a versão está em HOMOLOG e alguém pode estar testando com ela.

Nesta funcionalidade é possível acompanhar as execuções de orquestração, isto é, o encadeamento de robôs com dependência entre eles. A tela mostra o estado de cada nó, o prazo projetado, o caminho crítico e permite simular o efeito de um atraso.

Uma orquestração descreve, por exemplo: “rodar o faturamento e a conciliação; quando os dois terminarem, emitir a nota; se o faturamento falhar, avisar o plantão; depois, de qualquer jeito, rodar a limpeza”. A orquestração é desenhada e publicada pelo Studio (veja o módulo Studio).

A funcionalidade pode ser acessada através do menu de navegação: Agora > Orquestrações.



Enquanto não houver execuções, a tela informa “Nenhuma execução de plano ainda” e indica o caminho para disparar uma, que é a chamada POST /api/plans/:id/run. A tela é atualizada a cada 5 segundos.

A lista “Execuções de plano” mostra as 25 execuções mais recentes. Cada linha traz:

Para abrir os detalhes de uma execução é necessário:

A faixa de prazo informa o veredito da execução:

A faixa mostra também o prazo, o horário projetado de término, a folga ou o atraso em minutos e o gargalo (o nó que mais pesa no caminho). Quando a orquestração não declara prazo, a tela informa o tempo que ainda falta e o gargalo.

A projeção usa a duração histórica de cada nó. Quando há nós sem histórico, uma faixa de aviso informa que a duração deles é um valor padrão e que a projeção vale menos por isso.

O grafo desenha os nós em colunas, cada um depois de todos os nós de que depende. Cada nó mostra o nome, o tipo (quando não é um robô), o estado e as marcas SEGURO e opcional. A cor da faixa à esquerda do nó indica o estado:

Os nós e as ligações do caminho crítico são destacados em roxo. Uma ligação tracejada em vermelho indica uma dependência por falha, isto é, um nó que só executa se o anterior falhar.

Para ver os detalhes de um nó é necessário:

O painel de detalhes mostra o identificador do nó, o tipo, o estado, onde o nó deveria executar e em qual máquina executou, os hosts afetados (quando o nó age sobre hosts), o job, a sub-execução, a tarefa humana (com link para Tarefas), a duração prevista e a origem dessa previsão, o início, o motivo (quando o nó está parado) e a intervenção feita por alguém, se houver.

A simulação responde “e se este nó atrasar 20 minutos?” sem alterar nada na execução.

Para simular um atraso é necessário:

A faixa de prazo e o caminho crítico passam a refletir o cenário, que aparece ao lado, por exemplo “cenário: emitir-nf +20min”. Para voltar à projeção real, selecione o botão “limpar”.

A tela não oferece botões de intervenção. Quem opera uma execução em andamento usa a API, com as permissões de operação:

A chamada de operação de nós aceita segurar, liberar, reexecutar, forcar-sucesso e contornar:

Exemplo, reexecutando todos os nós que falharam:

Nesta funcionalidade é possível responder às tarefas humanas, isto é, os pontos em que uma automação parou para esperar a decisão de uma pessoa, como a aprovação de um pagamento acima da alçada ou a conferência de um documento lido com baixa confiança.

A funcionalidade pode ser acessada através do menu de navegação: Agora > Tarefas.



A tela “Minhas tarefas” é separada do painel de operação porque o uso é diferente: o painel serve para acompanhar a frota, e esta tela serve para trabalhar. Ela tem cabeçalho próprio, com a identidade de quem está conectado e o botão “sair”, e exibe uma tarefa por vez em um cartão.

A tela lista as tarefas pendentes dirigidas à própria pessoa, ao papel dela ou a ninguém em particular. Quando não há nenhuma, informa “Nada esperando você agora”. A lista é atualizada a cada 15 segundos, exceto enquanto a pessoa digita em um campo.

Cada cartão mostra:

Para responder uma tarefa é necessário:

Se algum campo obrigatório estiver vazio, a tela informa “Preencha:” seguido do nome dos campos e não registra a resposta. Quando a resposta é aceita, a tela informa “Registrado:” com o desfecho, e o job volta para a fila e continua de onde parou.

Nota: a retomada não repete o que já foi concluído. Os passos anteriores do robô são reaplicados do diário de execução, e não executados de novo. O robô fica livre enquanto a tarefa espera, de modo que uma resposta que leve dias não ocupa nenhuma máquina.

Nota: a resposta é registrada na trilha de auditoria com quem decidiu, o desfecho e o que foi preenchido.

Importante: responder exige a permissão de responder tarefas, que os papéis operador, revisor e admin possuem. Para quem não a tem, a tela exibe a mensagem “O papel ... não tem a permissão task:answer. Você vê as tarefas, mas não pode respondê-las.” e os botões ficam desabilitados.

Uma tarefa tem prazo quando o autor do robô define um. Depois do prazo, o cartão recebe a marca “atrasada”, e a seção “Esperando uma pessoa” da tela Operação destaca a tarefa. A regra de alerta human-task-overdue avisa o canal configurado quando há tarefas fora do prazo. Veja Alertas e webhooks.

A tela não oferece o cancelamento. Quem tem a permissão de gerir tarefas (operador e admin) cancela pela API, com POST /api/human-tasks/:id/cancel. O cancelamento também devolve o job à fila, e na retomada ele termina como falha de negócio explicada, em vez de ficar suspenso para sempre.

Um robô que tem tarefas pendentes não pode ter a publicação removida. Veja Robôs.

Nesta funcionalidade é possível descobrir o que mais quebra na operação. A tela agrupa as falhas de execução que têm a mesma causa, mostra quantas vezes cada defeito ocorreu, em quais robôs e quando foi a última ocorrência, e permite pedir uma hipótese de causa à inteligência artificial.

A funcionalidade pode ser acessada através do menu de navegação: Entender > Falhas.

Tela Falhas com os defeitos mais frequentes do período

A mensagem de erro de um job quase nunca se repete literalmente, porque carrega identificadores, números de documento, datas e caminhos de arquivo. Para que doze ocorrências do mesmo defeito não apareçam como doze defeitos diferentes, o Orquestrador reduz cada mensagem à sua forma, a assinatura, e agrupa as falhas que têm a mesma assinatura.

Esse agrupamento é um cálculo sobre o histórico e não usa IA.

Para escolher o período de análise é necessário:

Dois cartões resumem o período:

A seção “O que mais quebra” lista os defeitos, do mais frequente ao menos frequente. Cada linha mostra:

Quando não há falhas, a tela informa “Nenhuma falha neste período.” A tela é atualizada a cada 15 segundos.

Para ver os detalhes é necessário:

A área aberta mostra a assinatura do defeito e a lista dos jobs que falharam, com o complemento “+N outros” quando há mais jobs do que os exibidos.

A IA lê o log da falha mais recente do grupo e propõe uma hipótese e um próximo passo. Ela não corrige, não reexecuta e não fecha alertas. Cada diagnóstico usa uma chamada ao modelo e, por isso, tem custo; o resultado fica guardado no job.

Para diagnosticar um defeito é necessário:

O diagnóstico mostra:

Para pedir uma nova opinião é necessário:

Nota: o diagnóstico depende de um provedor de IA e de uma rota para a finalidade diagnostico. Quando eles não existem, a tela informa “Não foi possível diagnosticar” e orienta o cadastro. A configuração de provedores e rotas é tratada no módulo IA.

Para falhas em nós de uma orquestração, o agente de remediação pode propor uma ação corretiva. Veja Agente.

Nesta funcionalidade é possível acompanhar o agente de remediação, que observa a operação, identifica problemas conhecidos e propõe uma ação corretiva. A pessoa aprova ou recusa cada proposta, a menos que a política da instalação autorize o agente a executar sozinho as ações de menor risco.

A funcionalidade pode ser acessada através do menu de navegação: Entender > Agente.

Tela Agente com a autonomia, as propostas e o catálogo de ações

A tela é atualizada a cada 15 segundos.

O agente segue quatro regras:

Um sintoma desconhecido vira “Avisar o plantão”, e não é ignorado.

A faixa no topo da tela mostra a política em vigor, por exemplo “Autonomia: nenhuma”, com o texto explicativo:

A autonomia é definida em remediacao na política da instalação, e pode ser definida por pasta em remediacaoPorPasta, porque as áreas não correm o mesmo risco. A política também aceita maxPorHora (teto de ações automáticas por hora e por pasta, padrão 6) e bloqueadas (ações que nunca rodam sozinhas naquela pasta). Para alterar a política é necessário usar PUT /api/policy, com o papel admin:

curl -X PUT http://localhost:8080/api/policy \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d '{"remediacao":{"autonomia":"seguras","maxPorHora":6}}'

Importante: ligar a autonomia é a mudança de política de maior efeito, porque a plataforma passa a agir em produção sem uma pessoa. A mudança fica registrada na trilha de auditoria. Recomenda-se ligar a autonomia somente depois de ler algumas propostas e concluir que elas fazem sentido.

A seção “Esperando você (N)” lista as propostas que aguardam decisão. Cada proposta mostra:

Para decidir uma proposta é necessário:

Nota: aprovar ou recusar exige a permissão de disparar jobs, que os papéis operador, autor e admin possuem. A recusa não conta como evidência de que a ação não funcionaria; ela só registra que uma pessoa preferiu outro caminho.

A seção “O que o agente fez” lista as últimas 30 propostas já decididas, com o resultado e quem decidiu (“o agente” ou o nome da pessoa). Os estados possíveis são aplicada, falhou, recusada e superada.

A seção “O que ele PODE fazer” mostra o catálogo completo de ações:

O agente tem três limites contra o excesso de propostas:

O agente observa a janela das últimas seis horas, inclusive execuções já terminadas com falha durante a madrugada.

Quando a ação “Avisar o plantão” é executada, o aviso sai pelo evento agente.proposta, entregue aos assinantes de webhook de saída: o agente não tem canal próprio. Veja Alertas e webhooks.

Nesta funcionalidade é possível medir quanto a automação devolve à organização. A tela calcula, para o período escolhido, a economia bruta (o trabalho manual que deixou de ser feito), o custo das execuções e o resultado líquido, por robô e por pasta, e mostra ao lado do número tudo o que ainda não foi declarado.

A funcionalidade pode ser acessada através do menu de navegação: Entender > Valor.

Tela Valor com economia líquida, lacunas e tarifas em uso

A tela é atualizada a cada 30 segundos.

Para escolher o período é necessário:

A faixa “O que este número ainda não cobre” lista o que impede o resultado de ser completo, por exemplo:

Cada item é uma tarefa pendente para quem administra. À medida que os dados são declarados, a lista diminui.

A tabela “Por processo” detalha cada robô:

Quando a instalação tem mais de uma pasta com execuções, a tabela “Por pasta” mostra, para cada pasta, o número de robôs, as execuções, o custo, a economia e o resultado, com uma barra proporcional. A divisão é feita somente por pasta, a mesma unidade usada para permissão e escopo.

A seção “Tarifas em uso” mostra a tarifa da “hora de máquina” e a da “hora de pessoa (com encargos)”. Enquanto elas não forem informadas, aparece um traço no lugar do valor.

O tempo manual é o tempo que uma pessoa levaria para executar o trabalho uma vez, em minutos. Para declará-lo é necessário usar a API, com um papel que pode publicar robôs (autor ou admin):

curl -X PUT http://localhost:8080/api/processes/$ROBO/manual-time \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d '{"minutosManuais":12,"pessoasPorExecucao":1}'

O campo pessoasPorExecucao é opcional e indica quantas pessoas o trabalho manual exigiria.

Importante: o campo é em minutos. Valores acima de um dia (1440 minutos) por execução são recusados, porque quase sempre são horas digitadas onde se pede minutos.

As tarifas ficam na política da instalação e podem ser alteradas sem reiniciar o servidor. Para informá-las é necessário usar a API, com o papel admin:

curl -X PUT http://localhost:8080/api/policy \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d '{"tarifas":{"horaDeRobo":35,"horaDePessoa":60,"moeda":"BRL"}}'

Nota: tarifa acima de 100 mil por hora é recusada, pelo mesmo motivo do tempo manual. A mudança de tarifa fica registrada na trilha de auditoria, porque dobrar a hora de pessoa dobra a economia declarada.

Nota: os mesmos dados estão disponíveis em formato JSON em GET /api/value?dias=30, para quem quiser montar um relatório próprio.

Nesta funcionalidade é possível consultar as máquinas que executam os robôs, verificar o estado e as capacidades de cada uma e gerar o código de instalação para conectar uma nova máquina.

Uma máquina é o computador onde o agente do CITSmart X está instalado. Ela mantém contato com o Orquestrador por batimentos periódicos e recebe os jobs compatíveis com as capacidades e os grupos dela.

A funcionalidade pode ser acessada através do menu de navegação: Configurar > Máquinas.

Tela Máquinas com a frota registrada

A tela é atualizada a cada 10 segundos.

Cada máquina aparece em um cartão com:

Para localizar uma máquina é necessário:

Nota: uma máquina que fica mais de 60 segundos sem enviar sinal passa a Offline. Os jobs que ela executava voltam para a fila. O alerta de máquina sem sinal está descrito em Alertas e webhooks.

O Orquestrador só entrega um job a uma máquina que atenda a todos os critérios, avaliados do mais simples ao mais custoso:

Quando nenhuma máquina serve, o motivo aparece na seção “Jobs esperando” da tela Operação.

Para adicionar uma máquina é necessário:

O código tem o formato ci_XXXX-XXXX, vale por 30 minutos e serve para uma única máquina. O procedimento completo na máquina está em Registrar máquina.

Os códigos gerados que ainda não foram usados aparecem na seção “Codigos esperando instalacao”, com o início do código e o tempo para vencer. Por segurança, o código completo só é exibido no momento da geração.

Para revogar um código é necessário:

Quem ainda não instalou o agente precisará de um novo código.

Os grupos de afinidade e o limite de jobs simultâneos de cada máquina são definidos pela API, porque a tela só exibe esses dados. Para isso é necessário ter a permissão de gerir máquinas (papéis operador e admin):

curl -X POST http://localhost:8080/api/robot-groups \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d '{"name":"financeiro"}' curl -X POST http://localhost:8080/api/robots/$MAQUINA/groups \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -d '{"groups":["financeiro"],"maxConcurrentJobs":2}'

Os grupos também podem ser informados no registro, com a opção --grupos.

Uma máquina em Draining termina o job em andamento e não recebe novos. O agente de remediação pode propor essa ação quando uma máquina falha tudo o que recebe. Veja Agente.

Nesta funcionalidade é possível conectar um computador ao Orquestrador para que ele passe a executar robôs. O registro troca o código de instalação por uma identidade exclusiva da máquina, de modo que revogar uma máquina não afeta as outras.

O procedimento começa no painel, na tela Máquinas, e termina na própria máquina, pela linha de comando do agente.

Para gerar o código é necessário:

O código vale por 30 minutos e serve para uma única máquina. Depois de usado, ou revogado, ou vencido, não funciona mais.

Na máquina que vai executar os robôs, é necessário:

npm run runner -- maquina registrar --orquestrador http://orquestrador.empresa:8080 --codigo ci_XXXX-XXXX --nome robo-sp-01 --grupos financeiro

As opções do comando são:

O agente detecta as capacidades da máquina (navegador, desktop, Excel e outras) e as informa no registro. A máquina passa a aparecer na tela Máquinas.

Nota: se uma máquina com o mesmo nome e o mesmo computador já existir, o registro a reaproveita: a identidade é renovada e o histórico é mantido. Quando o código foi gerado com nome ou grupos sugeridos, esses valores prevalecem sobre os informados no comando.

Importante: o agente guarda na máquina a identidade recebida no registro. Ela é renovada automaticamente a cada batimento, e a validade padrão é de 30 dias. Uma máquina que deixa de bater perde o acesso quando o prazo vence, e a tela Operação mostra, na seção Integração, quantos tokens de máquina estão vencendo.

Para que o agente inicie sozinho a cada logon no Windows é necessário:

npm run runner -- maquina instalar

Para remover o início automático, use maquina desinstalar. Para controlar o agente instalado, use maquina iniciar e maquina parar. Para consultar o registro e o início automático, use maquina estado.

Nota: o agente roda na sessão interativa do usuário, e não como serviço do Windows, porque os robôs que automatizam interface precisam de uma área de trabalho aberta. Tela bloqueada ou Sessão 0 impedem esse tipo de automação, e a tela Máquinas mostra a marca “tela bloqueada”.

Para verificar se a máquina opera sem assistência é necessário:

npm run runner -- maquina diagnostico

O diagnóstico lista as verificações com os resultados OK, AVISO ou ERRO, e indica o comando que corrige cada problema. As verificações incluem o registro, o início automático, a sessão, a área de trabalho e o navegador. Ao final, ele informa se a máquina está pronta para operação sem assistência.

Para que a máquina execute somente pacotes assinados por chaves conhecidas é necessário:

npm run runner -- maquina confiar SHA256:...

Sem argumentos, maquina confiar lista as chaves fixadas. Enquanto nenhuma chave estiver fixada, a máquina aceita pacotes sem assinatura.

Importante: fixar as chaves na máquina é o passo que protege contra um Orquestrador comprometido, e não apenas contra um pacote corrompido.

Nesta funcionalidade é possível cadastrar e acompanhar os gatilhos, que disparam um robô ou uma orquestração quando um evento acontece, em vez de depender de um horário. O Orquestrador oferece três tipos de gatilho:

A funcionalidade pode ser acessada através do menu de navegação: Configurar > Gatilhos.

Tela Gatilhos com o formulário Cadastrar gatilho

A tela é atualizada a cada 10 segundos. Quando não há nenhum gatilho, ela informa “Nenhum gatilho cadastrado” e lembra que a operação começa por relógio (agenda) ou por evento (gatilho).

Os gatilhos são agrupados na tela. Primeiro vêm os que têm problema, na seção “Com problema (N)”. Depois, os demais, nas seções “Filas de mensagem”, “Webhooks de entrada” e “Chegada de arquivo”, cada uma com a quantidade entre parênteses.

Cada gatilho aparece em um cartão com:

Os botões de cada cartão são “Desligar” (ou “Ligar”), “Esquecer arquivos” (somente em gatilhos de arquivo), “Editar” e “Remover”.

Para cadastrar um gatilho é necessário:

Se algum dado estiver inválido, a tela exibe a mensagem de erro ao lado do botão.

Nota: o cadastro de gatilhos exige a permissão de escrever agendamentos, que os papéis operador e admin possuem.

Como o gatilho de arquivo funciona:

Como o gatilho de fila funciona:

Importante: sem fila morta no AMQP, a mensagem que passa do limite de tentativas é apagada, e não há como investigar o que não entrou. O cartão exibe esse aviso. Também é exibido um aviso quando o endereço do corretor foi gravado no cadastro, e não no cofre: se ele tiver senha, a senha fica no registro.

Nota: o consumo de AMQP e de Kafka exige que os pacotes do corretor estejam instalados no servidor. Sem eles, o servidor informa o que instalar.

O gatilho de webhook recebe chamadas em POST /api/hooks/<token>. A chamada precisa ser assinada com o segredo do gatilho:

Os argumentos do disparo, definidos pela API no campo arguments do gatilho, podem usar o conteúdo do corpo JSON da chamada, com marcadores como {{ corpo.pedido.id }}. Uma chamada aceita responde 202 com o identificador do job (ou da execução, quando o alvo é uma orquestração). Uma chamada com assinatura inválida, fora da janela de tempo ou com o gatilho desligado é recusada; uma chamada repetida responde 200 e não dispara de novo; acima do limite por minuto, a resposta é 429.

Importante: o endereço e o segredo do webhook são entregues uma única vez, na resposta da criação pela API (POST /api/triggers), junto com um exemplo de chamada. A tela não os exibe. Guarde o segredo na hora. Para trocá-lo, use POST /api/triggers/:id/rotate: o segredo anterior deixa de valer imediatamente, e o sistema que chama precisa ser atualizado.

Para editar um gatilho é necessário:

Nota: não é possível remover a publicação de um robô que tem gatilhos apontando para ele. Veja Robôs.

Nota: quando um gatilho dispara em laço, o agente de remediação pode propor desligá-lo. Veja Agente.

Nota: todas as alterações de gatilho ficam registradas na trilha de auditoria.

Nesta funcionalidade é possível cadastrar e acompanhar os recursos globais, isto é, os limites que não pertencem a um robô nem a uma orquestração, e sim ao mundo lá fora. Exemplos: as 8 licenças de diálogo de um ERP, que são as mesmas para todos os robôs que falam com ele, ou o fechamento contábil, que não pode executar duas vezes ao mesmo tempo.

Limitar cada robô separadamente não impede a nona sessão de derrubar o ERP. O recurso global resolve isso: o job só entra em execução quando consegue reservar tudo o que pediu.

A funcionalidade pode ser acessada através do menu de navegação: Configurar > Recursos.

Tela Recursos com o formulário Cadastrar recurso

A tela é atualizada a cada 5 segundos. Enquanto não há recursos, ela informa “Nenhum recurso global cadastrado” e exibe somente o formulário de cadastro.

Para cadastrar um recurso é necessário:

Se algum dado estiver inválido, a tela exibe o motivo ao lado do botão. O nome e o tipo não mudam depois de criados.

Importante: o cadastro, a edição, o desligamento e a remoção de recursos exigem a permissão de gerir a política da instalação, que somente o papel admin possui. Os demais papéis com acesso de leitura só consultam a tela.

Com recursos cadastrados, a tela mostra o resumo “Recursos globais”:

Abaixo, a seção “Pools” traz um cartão por recurso, com:

Para alterar um recurso é necessário:

Para parar de aceitar novos usos sem perder a configuração, selecione o botão “desligar (drenar)”. O recurso fica marcado como desligado (drenando), e quem já o segura termina normalmente. Para reativá-lo, selecione “religar”.

Para remover, selecione o botão “remover” e confirme. Os robôs e os nós que pedem o recurso passam a ficar parados esperando um recurso que não existe mais.

Se um robô cai sem devolver a reserva, o Orquestrador a solta quando percebe que o dono já não está vivo. Para forçar a conferência imediata é necessário:

A tela informa quantas reservas sem dono vivo foram soltas, ou que nada precisou ser solto.

O pedido de recurso é declarado no robô ou no nó da orquestração, no Studio, com o nome do recurso e a quantidade. Quando o robô e o nó pedem o mesmo recurso, vale o pedido do nó, por ser mais específico. Veja o módulo Studio.

Nota: o agente de remediação pode propor a ação “Liberar o recurso preso” quando a reserva ficou com um dono que já terminou. Veja Agente.

Nesta funcionalidade é possível trabalhar com filas de itens de trabalho. Em vez de percorrer uma planilha, o robô consome itens de uma fila, um a um. Isso permite retomar o trabalho depois de uma falha, dividir o volume entre várias máquinas e rastrear cada item pela referência do sistema de origem, como o número de uma nota fiscal.

As filas não têm uma tela de cadastro. Elas nascem do uso, na primeira vez em que um item é enfileirado, e são acompanhadas na seção “Filas” da tela Operação, acessada pelo menu de navegação Agora > Operação.

Cada item de fila passa por estes estados:

Como o consumo funciona:

A seção “Filas” da tela Operação mostra, para cada fila: