#Evento de Ação Personalizada

#Introdução

O NocoBase possui ações de dados comuns integradas (adicionar, excluir, editar, visualizar, etc.). Quando essas ações não conseguem atender a necessidades de negócios complexas, você pode usar o evento de ação personalizada em um fluxo de trabalho e vincular esse evento ao botão "Acionar fluxo de trabalho" de um bloco de página. Quando o usuário clicar no botão, um fluxo de trabalho de ação personalizada será acionado.

#Criar um fluxo de trabalho

Ao criar um fluxo de trabalho, selecione "Evento de Ação Personalizada":

#Configuração do acionador

#Tipo de contexto

v1.6.0+

O tipo de contexto determina em quais botões de bloco o fluxo de trabalho pode ser vinculado:

• Sem contexto: Um evento global que pode ser vinculado a botões de ação em painéis de ações e blocos de dados;
• Registro único: Pode ser vinculado a botões de ação em blocos de dados, como linhas de tabela, formulários e detalhes;
• Múltiplos registros: Pode ser vinculado a botões de operação em massa em uma tabela.

#Coleção

Quando o tipo de contexto é Registro único ou Múltiplos registros, você precisa selecionar a coleção à qual o modelo de dados será vinculado:

#Dados de associação a serem usados

Se você precisar usar os dados de associação da linha de dados acionadora no fluxo de trabalho, poderá selecionar campos de associação profundos aqui:

Esses campos serão automaticamente pré-carregados no contexto do fluxo de trabalho após o evento ser acionado, para que possam ser usados no fluxo de trabalho.

#Configuração da ação

A configuração dos botões de ação em diferentes blocos varia de acordo com o tipo de contexto configurado no fluxo de trabalho.

#Sem contexto

v1.6.0+

No painel de ações e em outros blocos de dados, você pode adicionar o botão "Acionar fluxo de trabalho":

Após adicionar o botão, vincule o fluxo de trabalho sem contexto criado anteriormente. Tomando como exemplo o botão no painel de ações:

#Registro único

Em qualquer bloco de dados, um botão "Acionar fluxo de trabalho" pode ser adicionado à barra de ações para um único registro, como em formulários, linhas de tabela, detalhes, etc.:

Após adicionar o botão, vincule o fluxo de trabalho criado anteriormente:

Depois disso, clique neste botão para acionar o evento de ação personalizada:

#Múltiplos registros

v1.6.0+

Na barra de ações de um bloco de tabela, ao adicionar um botão "Acionar fluxo de trabalho", haverá uma opção adicional para selecionar o tipo de contexto: "Sem contexto" ou "Múltiplos registros":

Quando "Sem contexto" é selecionado, trata-se de um evento global e só pode ser vinculado a fluxos de trabalho do tipo sem contexto.

Quando "Múltiplos registros" é selecionado, você pode vincular um fluxo de trabalho do tipo múltiplos registros, que pode ser usado para operações em massa após a seleção de dados (atualmente suportado apenas por tabelas). O intervalo de fluxos de trabalho selecionáveis é limitado àqueles configurados para corresponder à coleção do bloco de dados atual:

Ao clicar no botão para acionar, você deve ter selecionado algumas linhas de dados na tabela; caso contrário, o fluxo de trabalho não será acionado:

#Exemplo

Por exemplo, temos uma coleção de "Amostras". Para amostras com o status "Coletado", precisamos fornecer uma ação de "Enviar para inspeção". O envio verificará primeiro as informações básicas da amostra, gerará um dado de "Registro de inspeção" e, em seguida, alterará o status da amostra para "Enviado". Essa série de processos não pode ser concluída com cliques simples em botões de CRUD; nesse caso, você pode usar eventos de ação personalizada.

Primeiro, crie uma coleção de "Amostras" e uma coleção de "Registros de inspeção", e insira dados de teste básicos na tabela de amostras:

Em seguida, crie um fluxo de trabalho de "Evento de Ação Personalizada". Se você precisar de um feedback imediato do processo de operação, poderá escolher o modo síncrono (no modo síncrono, você não pode usar nós de tipo assíncrono, como processamento manual):

Na configuração do acionador, selecione "Amostras" para a coleção:

Organize a lógica no fluxo de acordo com as necessidades do negócio. Por exemplo, o envio para inspeção só é permitido quando o parâmetro do indicador for maior que 90; caso contrário, uma mensagem de problema relacionado será exibida:

Após configurar e habilitar o fluxo, retorne à interface da tabela e adicione o botão "Acionar fluxo de trabalho" na coluna de ações da tabela:

Em seguida, no menu de configuração do botão, escolha vincular o fluxo de trabalho e abra o pop-up de configuração:

Adicione o fluxo de trabalho habilitado anteriormente:

Após enviar, altere o texto do botão para o nome da operação, como "Enviar para inspeção", e o processo de configuração estará concluído.

Ao usar, selecione qualquer dado de amostra na tabela e clique no botão "Enviar para inspeção" para acionar o evento de ação personalizada. Conforme a lógica organizada anteriormente, se o parâmetro do indicador da amostra for menor que 90, o seguinte aviso aparecerá após o clique:

Se o parâmetro do indicador for maior que 90, o fluxo será executado normalmente, gerando os dados de "Registro de inspeção" e alterando o status da amostra para "Enviado":

Com isso, um evento de ação personalizada simples está concluído. Da mesma forma, para negócios com operações complexas, como processamento de pedidos, envio de relatórios, etc., você pode usar eventos de ação personalizada para implementá-los.

#Chamada externa

O acionamento de eventos de ação personalizada não se limita a operações na interface do usuário; ele também pode ser acionado por meio de chamadas de API HTTP. Especificamente, os eventos de ação personalizada fornecem um novo tipo de operação para todas as operações de coleção para acionar fluxos de trabalho: trigger, que pode ser chamado instalando a API de operação padrão do NocoBase.

#Sem contexto

Fluxos de trabalho sem contexto precisam ser acionados para o recurso workflows:

curl -X POST -H 'Authorization: Bearer <seu token>' -H 'X-Role: <nomeDaFunção>' \
  "http://localhost:3000/api/workflows:trigger?triggerWorkflows=workflowKey"

#Registro único

Semelhante ao fluxo de trabalho acionado por botão no exemplo, você pode chamá-lo assim:

curl -X POST -H 'Authorization: Bearer <seu token>' -H 'X-Role: <nomeDaFunção>' \
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Como esta operação é para um único dado, ao chamar para dados existentes, você precisa especificar o ID da linha de dados, substituindo a parte <:id> na URL.

Se for chamado para um formulário (como adição ou atualização), o ID pode não ser passado para o formulário de novos dados, mas os dados enviados precisam ser passados como o contexto de execução:

curl -X POST -H 'Authorization: Bearer <seu token>' -H 'X-Role: <nomeDaFunção>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger?triggerWorkflows=workflowKey"

Para formulários de atualização, você precisa passar o ID da linha de dados e os dados atualizados:

curl -X POST -H 'Authorization: Bearer <seu token>' -H 'X-Role: <nomeDaFunção>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Se o ID e os dados forem passados simultaneamente, a linha de dados correspondente ao ID será carregada primeiro e, em seguida, as propriedades do objeto de dados passado serão usadas para sobrescrever a linha de dados original para obter o contexto de dados do acionador final.

Além disso, o parâmetro de URL triggerWorkflows é a chave (key) do fluxo de trabalho, e múltiplos fluxos de trabalho são separados por vírgulas. Essa chave pode ser obtida passando o mouse sobre o nome do fluxo de trabalho no topo da tela de edição do fluxo de trabalho:

Após o sucesso da chamada acima, o evento de ação personalizada da coleção samples correspondente será acionado.

#Múltiplos registros

Semelhante ao método de chamada de registro único, mas os dados passados precisam apenas de múltiplos parâmetros de chave primária (filterByTk[]) e não há necessidade de passar a parte data:

curl -X POST -H 'Authorization: Bearer <seu token>' -H 'X-Role: <nomeDaFunção>' \
  "http://localhost:3000/api/samples:trigger?filterByTk[]=1&filterByTk[]=2&triggerWorkflows=workflowKey"

Esta chamada acionará o evento de ação personalizada no modo de múltiplos registros e usará os dados com IDs 1 e 2 como os dados no contexto do acionador.