...
- Visão Geral
- Como cadastrar uma fórmula visual para executar em uma API
- Gatilhos disponibilizados para APIs
- Seleção e uso do contexto na Fórmula Visual
- Exemplos de Utilização
01.
...
VISÃO
...
GERAL
A partir da versão 12.1.29 é possível customizar APIs através de Formulas Visuais. Foram criados gatilhos específicos para esse tipo de FV, que mostraremos a seguir.
...
| Aviso |
|---|
| icon | false |
|---|
| title | Importante: |
|---|
|
Marcando a opção "Executa em API(Poco)", somente será permitido executar Fórmulas Visuais em API's contruidas construídas no padrão "POCO".
API's construídas no padrão "DataServerData Server" não aparecerão para serem usadas nesse modelo.
Portanto, Api's no padrão "DataServerData Server" continuam podendo ser usadas no modelo antigo (DataSet). |
02. COMO CADASTRAR UMA FÓRMULA VISUAL PARA EXECUTAR EM UMA API
A Fórmula Visual deve estar cadastrada com a opção "Executa em API (POCO)" habilitada, conforme exibido na imagem abaixo.
Image Removed
Image Added
Ao marcar a opção opção "Executa em API (POCO)", automaticamente o campo "Visível para todas as coligadas" será habilitado e não é possível desmarcá-lo.
...
Após salvar, será disponibilizada uma aba para configurar os Gatilhos da Fórmula Visual. Ao configurar um gatilho o sistema passa a executar a Fórmula Visual quando a API configurada é executada.
03.
...
GATILHOS DISPONIBILIZADOS PARA
...
APIS
Com os gatilhos disponibilizados, a Fórmula Visual pode ser executada antes ou depois dos dos métodos da API, como Get, Post, Put, Patch ou Delete.
Abaixo estão todos os gatilhos para API:
Image Removed
Image Added
Os gatilhos Antes/Depois de recuperar todos (get) correspondem ao GetAll e os gatilhos Antes/Depois de recuperar (Get), correspondem ao GetOne.
...
Utilizando os gatilhos Depois de algum dos métodos, a Fórmula Visual será executada depois de chamar a execução do endpoint.
04. SELEÇÃO E USO DO CONTEXTO NA FÓRMULA VISUAL
É possível selecionar como contexto em uma Fórmula Visual de API, um controller de API (POCO).
...
Veja no exemplo abaixo, uma Fórmula Visual onde foi selecionado o contexto da API de usuários (Controller de usuários) para que seja gerada uma exceção com o valor do campo userName.
- Primeiro: Selecionar o contexto para a Fórmula Visual:
Image Removed
Image Added
- Segundo: Adicionar a atividade de Gerar exceção, clicar em Ligações, na propriedade
...
...
- ", clicar em reticências.
Será exibido o Editor de Ligações, ao expandir a propriedade '"Fields'", serão listados todos os campos da API que podem ser usados no contexto. Basta selecionar um campo/valor desejado. No exemplo abaixo será a propriedade userName.
Obs.: As propriedades das APIs serão sempre listadas abaixo da hierarquia de _Items.
Image Removed
Image Added
- Terceiro: Adicionar um gatilho para essa Fórmula Visual.
Importante: Os valores de contexto estarão disponíveis no sistema depois que a requisição da API for feita. Então, para usar o contexto com valores, é necessário utilizar gatilhos de Depois dos métodos.
Isso porque se forem usados gatilhos de antes, o sistema ainda não terá executado o endpoint e não terá os valores das propriedades.
- Quarto: Adicionar um gatilho para a Fórmula Visual. Neste exemplo, adicionamos o gatilho
...
- "Depois de recuperar (Get)
...
No Postman, aplicativo que usamos para realizar testes de APIs, chamamos o endpoint de usuários, buscando o usuário mestre.
Image Removed
Image Added
Veja que o retorno foi uma exceção, contendo na mensagem o valor do campo userName (do contexto) e o nome da Fórmula Visual.
Com a Fórmula Visual é possível fazer inúmeras implementações, como disparar um e-mail sempre que algum usuário for deletado, alterado ou criado, por exemplo. Alterar o valor de uma propriedade específica da API antes de incluir o registro no banco, criar condições e comportamentos diferentes para determinados registros, entre outros.
05. EXEMPLOS DE UTILIZAÇÃO
No primeiro exemplo, vamos utilizar as atividade de "Foreach" e "Expression" para percorrer os resultados da API (Controller de Usuários), e concatenar uma string qualquer a propriedade "familyName". A string será adicionada pela atividade de expressão antes do valor do campo.
| Informações |
|---|
|
| Deck of Cards |
|---|
| | Card |
|---|
| Ao cadastrar uma Fórmula Visual com a opção Executa em API (POCO) habilitada (como mostrado anteriormente) é necessário adicionar os objetos que serão utilizados ao gatilho. Para nosso exemplo, vamos utilizar a API de Usuários (Controller de Usuários) nos gatilhos "Depois de recuperar todos (get)" e "Depois de recuperar (get)".  Image Added
|
| Card |
|---|
| Em seguida na estrutura da fórmula, vamos adicionar as atividades "Para Cada Iteração (API)" e "Expression" no Fluxo de Trabalho Sequencial da fórmula, como mostra imagem abaixo: | Aviso |
|---|
É necessário que seja preenchido o contexto (Controller de Usuário) da fórmula para capturar ou manipular os valores das propriedades da API utilizada. |
 Image Added
|
| Card |
|---|
| - Configurando a Atividade Para Cada Iteração (API)
Nas propriedades da atividade, clique em Ligações ( Image Added) e selecione o lookup do campo "Lista de Items". Na tela "Editor de Ligações", selecione a seguinte ligação: "RMSWorkflow | [] Fields | _Items". Essa configuração é necessária, por que temos que selecionar o objeto ao qual queremos percorrer. No nosso exemplo, selecionamos o "_items", por que queremos percorrer todos os resultados da API.  Image Added
Leia mais sobre Atividade Para cada Iteração e Para cada Iteração API |
| Card |
|---|
| - Configurando a Atividade de Expression
Nas propriedades da atividade, selecione o lookup do campo "Expressões" e adicione a seguinte expressão: "'Teste FV: ' + rmsForEachApiActivity1._Items.Name.FamilyName". Essa expressão irá concatenar a string "Teste FV:" com o campo "familyName" depois de executar o método "GetAll" ou "GetOne" na API.  Image Added
Em seguida, é necessário configurar o valor calculado, pois é ele quem vai receber a expressão criada acima. Para realizar a configuração, clique em Ligações (Image Added) e selecione o lookup do campo "Valor Calculado". Na tela "Editor de Ligações", selecione a seguinte ligação: "rmsForEachApiActivity1 | [] Fields | _Items | Name | Formatted | AsString".  Image Added
|
| Card |
|---|
| Após realizar todas as configurações necessárias na formula, acessamos o Postman (aplicativo que usamos para realizar testes de APIs), e chamamos o endpoint de usuários. Verifique que ao executar o "GetAll", o campo "familyName" está sendo concatenado corretamente com a string "Teste FV" (condição criada na expressão da formula).  Image AddedNa execução do "GetOne", foi passado como parâmetro o usuário "mestre", verifique que regra também é aplicada corretamente.
 Image Added
|
|
|
No segundo exemplo, vamos utilizar as atividades de "Se/Senão" e "Expression" para criar uma condição, que será executada somente se o "UserName" de um usuário for "Teste_01" Depois de executar o método "POST" ( no postman aplicativo que usamos para realizar testes de APIs) na API de Usuário.
| Informações |
|---|
|
| Deck of Cards |
|---|
| | Card |
|---|
| Ao cadastrar uma Fórmula Visual com a opção Executa em API (POCO) habilitada (como mostrado anteriormente) é necessário adicionar os objetos que serão utilizados ao gatilho. Para nosso exemplo, vamos utilizar a API de Usuários (Controller de Usuários) no gatilho "Depois do método (post)".  Image Added
|
| Card |
|---|
| Em seguida na estrutura da fórmula, vamos adicionar as atividades "Se/Senão" e "Expression" no Fluxo de Trabalho Sequencial da fórmula, como mostra imagem abaixo: | Aviso |
|---|
É necessário que seja preenchido o contexto (Controller de Usuário) da fórmula para capturar ou manipular os valores das propriedades da API utilizada. |
 Image Added
|
| Card |
|---|
| - Configurando a Atividade Se/Senão
Nas propriedades da atividade: - Selecione a Condition "Condição de Regra Declarativa";
- Selecione o lookup do campo "ConditionName" e clique em "Novo" para criar uma nova condição;
- Na tela "Editor de Condição de Regra" crie a seguinte condição: this.ApiService.GetViewModelValue("_Items.UserName").ToString() == "Teste_01"
- Ao selecionar a condição criada o campo "Expression" será preenchido automaticamente pela condição criada.
Imagem explicativa abaixo:  Image Added
|
| Card |
|---|
| - Configurando a Atividade de Expression
Nas propriedades da atividade, selecione o lookup do campo "Expressões" e adicione a seguinte expressão: "'Teste: ' + RMSWorkflow._Items.ExternalId". Essa expressão irá adicionar a string "Teste:" ao campo "ExternalId" depois de executar o método "Post" na API. (A expressão será aplicada somente se entrar na condição criada anteriormente).  Image Added
Em seguida, é necessário configurar o valor calculado, pois é ele quem vai receber a expressão criada acima. Para realizar a configuração, clique em Ligações (Image Added) e selecione o lookup do campo "Valor Calculado". Na tela "Editor de Ligações", selecione a seguinte ligação: "RMSWorkflow| [] Fields | _Items | ExternalId | AsString".  Image Added
|
| Card |
|---|
| Após realizar todas as configurações necessárias na formula, acessamos o Postman (aplicativo que usamos para realizar testes de APIs), e chamamos o endpoint de usuários. Verifique que ao executar o "Post", onde o usuário possui o "UserName" = "Teste_01", o campo "externalId" está sendo atualizado corretamente com a string "Teste:" (condição criada na expressão da formula). | Aviso |
|---|
Quando utilizado o gatilho "Antes do método post (post)" a alteração é salva no banco, quando utilizado o gatilho "Depois do método post (post)" a atualização é feita somente no retorno da API. |
 Image Added
|
|
|
