[AEM Forms]{class="badge positive" title="(Se aplica a AEM Forms)."}

Integración de API externas con el Editor de reglas visuales en Forms de componentes principales

El Editor de reglas visuales de un formulario adaptable admite la característica Invocar servicio, que permite conectarse a API externas mediante modelos de datos de formulario (FDM) configurados para su instancia. Puede asignar campos de formulario directamente a los parámetros de entrada del servicio y utilizar la opción de carga útil de evento para asignar los parámetros de salida. El Editor de reglas visual también le permite definir reglas para los controladores de éxito y de error en función de la respuesta del servicio: los controladores de éxito administran las llamadas de API correctas, mientras que los controladores de error administran los errores.

Esto le permite enviar fácilmente solicitudes de API desde el formulario, procesar las respuestas de la API y mostrar o utilizar los datos devueltos de forma dinámica dentro del formulario. Garantiza una integración perfecta entre el formulario adaptable y los sistemas externos o fuentes de datos.

Ventajas de utilizar el servicio de invocación en el editor de reglas del formulario

Estas son algunas ventajas de utilizar la operación Invocar servicio en el editor de reglas de un formulario adaptable:

Invocar los controladores de servicio para las respuestas de éxito y error

El editor de reglas visual permite crear reglas para los controladores de éxito y de error para las operaciones Invocar servicio en función de sus respuestas de salida. La siguiente imagen muestra Invocar servicio en el editor de reglas visuales para un formulario adaptable:

Agregar un controlador de éxito y un controlador de errores

Para agregar el controlador de éxito o de error, haga clic en Agregar controlador de éxito o en Agregar controlador de error, respectivamente.

Al hacer clic en Agregar controlador de éxito, aparece el editor de reglas Invocar controlador de éxito de servicio, que le permite especificar reglas o lógica para administrar la respuesta de salida Invocar servicio cuando la operación se realiza correctamente. Puede especificar reglas incluso sin definir condiciones; sin embargo, puede agregar condiciones para el controlador de éxito haciendo clic en la opción Agregar condición.

Puede agregar varias reglas para controlar las respuestas correctas para la operación Invocar servicio:

{width="50%,"}

Del mismo modo, puede agregar reglas para controlar la respuesta de salida Invocar servicio cuando la operación no se realice correctamente. La siguiente imagen muestra el editor de reglas Invocar controlador de errores del servicio:

También puede agregar varias reglas para controlar las respuestas erróneas de la operación Invocar servicio.

La característica Habilitar validación de errores en el servidor permite que el autor agregue validaciones al diseñar un formulario adaptable para que también se ejecute en el servidor.

Requisitos previos para utilizar Invoke Service en el editor de reglas

A continuación se muestran los requisitos previos que debe cumplir antes de usar Invocar servicio en el editor de reglas:

Exploración del servicio de invocación mediante diferentes casos de uso

Invocar servicio del editor de reglas visual le permite realizar varias operaciones útiles. Puede usarlo para rellenar opciones desplegables, establecer paneles simples o repetibles y validar campos de formulario, todo en función de la respuesta de salida de Invocar servicio. De este modo, se mejora la flexibilidad y la interactividad de los formularios.

La tabla siguiente describe algunos escenarios en los que se puede usar Invocar servicio:

Cree un formulario Get Information que recupere valores según la entrada escrita en el cuadro de texto Pet ID. La captura de pantalla siguiente muestra el formulario utilizado en estos casos de uso:

Campos de formulario

Agregue los campos siguientes al formulario:

NOTE

En el campo Referencia de enlace del cuadro de diálogo Propiedades de los campos de formulario, seleccione y desplácese hasta seleccionar la propiedad binaria que agregó en el modelo de datos de formulario (FDM).

Configurar paneles

Defina los paneles como repetitivos con las restricciones siguientes:

Puede ajustar los valores de los paneles repetitivos para adaptarlos a sus necesidades.

Origen de datos

En este ejemplo, la API Swagger Petstore se usa para configurar un origen de datos. El modelo de datos de formulario Form está configurado para el servicio getPetById, que recupera los detalles del animal doméstico en función del ID ingresado.

Publicemos el siguiente JSON usando el servicio addPet en la API de 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"
    }

Las reglas y la lógica se implementan mediante la acción Invocar servicio en el editor de reglas del cuadro de texto Pet ID para mostrar los casos de uso mencionados.

Ahora vamos a explorar en detalle la implementación de cada caso de uso.

Caso de uso 1: Rellenar valores desplegables utilizando la salida de Invocar servicio

Este caso de uso muestra cómo rellenar opciones desplegables de forma dinámica en función del resultado de Invoke Service.

Implementación

Para conseguirlo, cree una regla en el cuadro de texto Pet ID para invocar el servicio getPetById. En la regla, establezca la propiedad enum de la lista desplegable photo-url en photoUrls en Agregar controlador de éxito.

Salida

Escriba 101 en el cuadro de texto Pet ID para rellenar dinámicamente las opciones desplegables en función del valor introducido.

Caso de uso 2: Establecer un panel repetible con la salida del servicio de invocación

Este caso de uso muestra cómo rellenar paneles repetibles de forma dinámica basándose en el resultado de un servicio Invoke.

Consideraciones

Implementación

Cree una regla en el cuadro de texto Pet ID para invocar el servicio getPetById. En Agregar controlador de éxito, agregue otra respuesta de controlador de éxito. Establezca el valor del panel tags en tags en la regla.

Salida

Escriba 101 en el cuadro de texto Pet ID para rellenar dinámicamente el panel repetible en función del valor de entrada.

Caso de uso 3: Configurar el panel mediante la salida del servicio de invocación

Este caso de uso muestra cómo establecer dinámicamente el valor de un panel en función del resultado de Invocar servicio.

Consideraciones

Implementación

Cree una regla en el cuadro de texto Pet ID para invocar el servicio getPetById. En Agregar controlador de éxito, agregue otra respuesta de controlador de éxito. Establezca el valor del cuadro de texto categoryname en category.name en la regla.

Salida

Escriba 101 en el cuadro de texto Pet ID para rellenar dinámicamente el panel en función del valor de entrada.

Caso de uso 4: Usar el parámetro de salida de Invocar servicio para validar otros campos

Este caso de uso muestra cómo usar el resultado de Invocar servicio para validar dinámicamente otros campos de formulario.

Implementación

Cree una regla en el cuadro de texto Pet ID para invocar el servicio getPetById. En Agregar controlador de errores, agregue una respuesta de controlador de errores. Ocultar el botón Enviar si se escribe un Pet ID incorrecto.

Salida

Escriba 102 en el cuadro de texto Pet ID y el botón Enviar estará oculto.

Caso de uso 5: Uso de la carga útil de eventos en la acción Navegar a en Invocar servicio

Este caso de uso muestra cómo configurar una regla en el botón Enviar que llame a un servicio Invoke y luego redirija al usuario a otra página mediante la acción Navegar a.

Implementación

Cree una regla en el botón Enviar para invocar el servicio de API redirect-api. Este servicio es responsable de redirigir al usuario al formulario Contáctenos.

Puede integrar directamente una API como el servicio de API redirect-api en su editor de reglas utilizando los datos JSON que se proporcionan a continuación:

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

En Agregar controlador de éxito, configure la acción Navegar a para redirigir al usuario a la página Contáctenos con el parámetro Event Payload. Aquí, el usuario puede enviar sus datos de contacto.

De forma opcional, configure un controlador de errores para que muestre un mensaje de error si falla la llamada de servicio.

Salida

Cuando se hace clic en el botón Enviar, se invoca el servicio de API redirect-api. Una vez finalizado correctamente, se redirigirá al usuario a la página Contáctenos.

Recuperar valores de propiedad de una matriz JSON

Esta es una característica que adoptó por primera vez. Si está interesado, envíe un mensaje de correo electrónico rápido desde su dirección de trabajo a mailto:aem-forms-ea@adobe.com para solicitar acceso a la característica .

El Forms adaptable admite la invocación de un servicio, el procesamiento de respuestas JSON y la cumplimentación dinámica de campos de formulario. En esta sección se describe cómo extraer valores de propiedad de una matriz JSON y enlazarlos a campos de formulario.

Respuesta JSON de muestra

El siguiente ejemplo representa las regiones de ventas de EE. UU. y la lista de representantes de ventas:

[
  {
    "region": "East",
    "salesPerson": "Emily Carter"
  },
  {
    "region": "South",
    "salesPerson": "Michael Brown"
  },
  {
    "region": "Midwest",
    "salesPerson": "Sophia Martinez"
  },
  {
    "region": "Southwest",
    "salesPerson": "David Johnson"
  },
  {
    "region": "West",
    "salesPerson": "Linda Walker"
  }
]

Función personalizada para extraer valores de propiedad

Utilice la siguiente función personalizada para extraer valores de propiedad de la matriz JSON.

/**
 * Returns an array of values for a specific property from an array of objects.
 *
 * @name getPropertyValues
 * @param {Object[]} jsonArray An array of objects
 * @param {string} propertyName The property whose values should be extracted
 * @returns {Array} An array containing the values of the specified property
 *
 */

function getPropertyValues(jsonArray, propertyName)
{
    return jsonArray.map((obj) => obj[propertyName]);

}

La función personalizada acepta:

La función personalizada devuelve una matriz simple de valores.

Uso de la función en el Editor de reglas

Para recuperar el valor específico de la matriz JSON:

event.payload.invokeServiceResponse.rawPayloadBody

En el siguiente ejemplo se muestra cómo rellenar un formulario Sales Department con esta respuesta.

Por ejemplo, vamos a crear un formulario Sales Department que incluya los menús desplegables Select Region y Select Sales Representative.

Paso 1: Invocar el servicio al inicializar el formulario

WHEN
    Form is initialized
THEN
    Invoke Service → salesdeptinfo

Paso 2: Rellene el menú desplegable Región

Agregue un controlador de éxito para la llamada de servicio y configure la siguiente acción:

Set enum → Region dropdown
getPropertyValues(
    event.payload.invokeServiceResponse.rawPayloadBody,
    "region"
)

Esta regla lee la matriz JSON, extrae los valores de propiedad region y asigna los valores a la lista desplegable Select Region.

Del mismo modo, configure la acción para la lista desplegable Select Sales Representative en el controlador de éxito.

Cuando el formulario se carga, se devuelven los datos JSON, la función personalizada extrae los valores de las propiedades y la lista desplegable se rellena automáticamente:

Preguntas frecuentes

Q: ¿Qué sucede si he creado una regla con el servicio de invocación y luego actualizo a la última versión de los componentes principales?

A: Al actualizar a la última versión de los componentes principales, la regla Invocar servicio se actualiza automáticamente a la interfaz de usuario más reciente, ya que es compatible con versiones anteriores.

Q: ¿Puedo agregar varias reglas para controlar las respuestas correctas o de error para la operación Invocar servicio?

A: Sí, puede agregar varias reglas para controlar las respuestas correctas o de error para la operación Invocar servicio.

Artículos relacionados

Recursos adicionales