Integração de APIs externas com o Editor de regras visuais no Forms dos Componentes principais

O Editor de Regras Visuais em um Formulário Adaptável oferece suporte ao recurso Chamar Serviço, permitindo que você se conecte a APIs externas por meio de Modelos de Dados de Formulário (FDM) configurados para sua instância. Você pode mapear campos de formulário diretamente para os parâmetros de entrada do serviço e usar a opção de carga útil do evento para mapear os parâmetros de saída. O Editor visual de regras também permite definir regras para manipuladores de sucesso e falha com base na resposta do serviço: manipuladores de sucesso lidam com chamadas de API bem-sucedidas, enquanto manipuladores de falha gerenciam erros.

Isso permite enviar facilmente solicitações de API do seu formulário, processar as respostas da API e exibir ou usar os dados retornados dinamicamente no formulário. Ele garante uma integração perfeita entre seu Formulário adaptável e sistemas externos ou fontes de dados.

Vantagens de usar a função Chamar serviço no editor de regras do formulário

Estas são algumas das vantagens de usar a operação Chamar serviço no editor de regras de um Formulário adaptável:

Chamar manipuladores de serviço para respostas com êxito e falha

O editor visual de regras permite criar regras para manipuladores de sucesso e falha para operações de Chamar Serviço com base nas respostas de saída. A imagem abaixo mostra o Invocar Serviço no editor de regras visuais para um Formulário Adaptável:

Para adicionar manipulador de êxito ou falha, clique em Adicionar manipulador de sucesso ou Adicionar manipulador de falha, respectivamente.

Quando você clica em Adicionar Manipulador de Êxito, o editor de regras Invocar Manipulador de Êxito do Serviço é exibido, permitindo que você especifique regras ou lógica para gerenciar a resposta de saída Invocar Serviço quando a operação for bem-sucedida. Você pode especificar regras mesmo sem definir condições; no entanto, você pode adicionar condições para o manipulador de sucesso clicando na opção Adicionar Condição.

Você pode adicionar várias regras para lidar com respostas bem-sucedidas para a operação Invocar Serviço:

{width="50%,"}

Da mesma forma, você pode adicionar regras para manipular a resposta de saída Chamar Serviço quando a operação não for bem-sucedida. A imagem abaixo exibe o editor de regras do Manipulador de Falha de Serviço de Chamada:

Você também pode adicionar várias regras para lidar com respostas malsucedidas da operação Chamar Serviço.

O recurso Habilitar Validação de Erros no Servidor também permite validações adicionadas pelo autor ao criar um Formulário Adaptável para execução no servidor.

Pré-requisitos para usar a função Chamar serviço no editor de regras

Abaixo estão os pré-requisitos que você deve atender antes de usar Chamar Serviço no editor de regras:

Explorar o serviço de chamada por meio de diferentes casos de uso

O Invoke Service do editor visual de regras permite executar várias operações úteis. Você pode usá-lo para preencher opções suspensas, definir painéis simples ou que possam ser repetidos e validar campos de formulário, tudo com base na resposta de saída do Chamar serviço. Dessa forma, melhorando a flexibilidade e a interatividade de seus formulários.

A tabela abaixo descreve alguns cenários nos quais o Chamar Serviço pode ser usado:

Crie um formulário Get Information que recupere valores com base na entrada inserida na caixa de texto Pet ID. A captura de tela abaixo mostra o formulário usado nesses casos de uso:

Campos de formulário

Adicione os seguintes campos ao formulário:

NOTE

No campo Referência de Ligação da caixa de diálogo Propriedades dos campos de formulário, selecione e navegue para selecionar a propriedade binária adicionada no Modelo de Dados de Formulário (FDM).

Configurando painéis

Defina os painéis como repetitivos com as seguintes restrições:

Você pode ajustar os valores dos painéis repetitivos para atender às suas necessidades.

Fonte de dados

Neste exemplo, a API Swagger Petstore é usada para configurar uma fonte de dados. O Modelo de Dados de Formulário está configurado para o serviço getPetById, que recupera detalhes de animal de estimação com base na ID inserida.

Vamos publicar o seguinte JSON usando o serviço addPet na API Swagger Petstore:

{
        "id": 101,
        "category": {
            "id": 1,
            "name": "Labrador"
        },
        "name": "Lisa",
        "photoUrls": [
            "https://example.com/photos/lisa1.jpg",
            "https://example.com/photos/lisa2.jpg"
        ],
        "tags": [
            {
                "id": 1,
                "name": "vaccinated"
            },
            {
                "id": 2,
                "name": "friendly"
            },
            {
                "id": 3,
                "name": "house-trained"
            }
        ],
        "status": "available"
    }

As regras e a lógica são implementadas usando a ação Invocar Serviço no editor de regras na caixa de texto Pet ID para demonstrar os casos de uso mencionados.

Agora vamos explorar a implementação de cada caso de uso em detalhes.

Caso de uso 1: Preencher valores suspensos usando a saída de Chamar serviço

Este caso de uso demonstra como preencher opções suspensas dinamicamente com base na saída de um Invoke Service.

Implementação

Para fazer isso, crie uma regra na caixa de texto Pet ID para invocar o serviço getPetById. Na regra, defina a propriedade enum da lista suspensa photo-url como photoUrls em Adicionar Manipulador de Êxito.

Saída

Digite 101 na caixa de texto Pet ID para preencher dinamicamente as opções suspensas com base no valor inserido.

Caso de uso 2: definir painel repetível usando a saída de Chamar serviço

Este caso de uso demonstra como preencher painéis repetíveis dinamicamente com base na saída de um Chamar serviço.

Considerações

Implementação

Crie uma regra na caixa de texto Pet ID para invocar o serviço getPetById. Em Adicionar Manipulador de Êxito, adicione outra resposta de manipulador de êxito. Defina o valor do painel tags como tags na regra.

Saída

Digite 101 na caixa de texto Pet ID para preencher o painel repetível dinamicamente com base no valor de entrada.

Caso de uso 3: definir painel usando a saída de Chamar serviço

Este caso de uso demonstra como definir dinamicamente o valor de um painel com base na saída de um Chamar serviço.

Considerações

Implementação

Crie uma regra na caixa de texto Pet ID para invocar o serviço getPetById. Em Adicionar Manipulador de Êxito, adicione outra resposta de manipulador de êxito. Defina o valor da caixa de texto categoryname como category.name na regra.

Saída

Digite 101 na caixa de texto Pet ID para preencher o painel dinamicamente com base no valor de entrada.

Caso de uso 4: usar o parâmetro de saída de Chamar serviço para validar outros campos

Este caso de uso demonstra como usar a saída de um Chamar Serviço para validar dinamicamente outros campos de formulário.

Implementação

Crie uma regra na caixa de texto Pet ID para invocar o serviço getPetById. Em Adicionar Manipulador de Falha, adicione uma resposta de manipulador de falha. Ocultar o botão Enviar se um Pet ID incorreto for inserido.

Saída

Digite 102 na caixa de texto Pet ID e o botão Enviar ficará oculto.

Caso de uso 5: Carga útil do evento de uso em Navegar para ação em Chamar serviço

Este caso de uso demonstra como configurar uma regra no botão Enviar que chama um Chamar Serviço e redireciona o usuário para outra página usando a ação Navegar para.

Implementação

Crie uma regra no botão Enviar para invocar o serviço de API redirect-api. Este serviço é responsável por redirecionar o usuário para o formulário Fale Conosco.

Você pode integrar diretamente uma API como o serviço de API redirect-api no Editor de regras usando os dados JSON fornecidos abaixo:

{
  "id": "1",
  "path": "/content/dam/formsanddocuments/contact-detail/jcr:content?wcmmode=disabled"
}

Em Adicionar Manipulador de Êxito, configure a ação Navegar para para redirecionar o usuário para a página Fale Conosco usando o parâmetro Event Payload. Aqui, o usuário pode enviar seus detalhes de contato.

Opcionalmente, configure um manipulador de falhas para exibir uma mensagem de erro se a chamada de serviço falhar.

Saída

Quando o botão Enviar é clicado, o serviço de API redirect-api é chamado. Após o sucesso, o usuário será redirecionado para a página Fale Conosco.

Perguntas frequentes

P: O que acontece se eu tiver criado uma regra usando o Serviço de Chamada e depois atualizar para a versão mais recente dos componentes principais?

A: Quando você atualiza para a versão mais recente dos componentes principais, a regra Invocar Serviço atualiza automaticamente para a interface do usuário mais recente, pois ela é compatível com versões anteriores.

P: Posso adicionar várias regras para lidar com respostas bem-sucedidas ou com falhas para a operação Invoke Service?

A: Sim, você pode adicionar várias regras para lidar com respostas bem-sucedidas ou com falhas para a operação Invocar Serviço.

Artigos relacionados

Recursos adicionais