[AEM Forms]{class="badge positive" title="Si applica ad AEM Forms)."}

Integrazione di API esterne con l’Editor di regole visive nel Forms dei componenti core

L’editor di regole visive in un modulo adattivo supporta la funzionalità Invoke Service, che consente di connettersi alle API esterne tramite i modelli di dati del modulo (FDM) configurati per l’istanza. Puoi mappare i campi modulo direttamente sui parametri di input del servizio e utilizzare l’opzione payload dell’evento per mappare i parametri di output. L’Editor di regole visive consente inoltre di definire regole per i gestori con esito positivo o negativo in base alla risposta del servizio: i gestori con esito positivo gestiscono le chiamate API, mentre i gestori con esito negativo gestiscono gli errori.

Questo consente di inviare facilmente richieste API dal modulo, elaborare le risposte API e visualizzare o utilizzare dinamicamente i dati restituiti all’interno del modulo. Garantisce un’integrazione perfetta tra il modulo adattivo e i sistemi o le origini dati esterni.

Vantaggi dell’utilizzo del servizio Invoke nell’editor di regole del modulo

Di seguito sono riportati alcuni vantaggi dell’utilizzo dell’operazione Invoke Service nell’editor di regole di un modulo Adobe:

Richiama i gestori del servizio per le risposte di esito positivo e negativo

L’editor di regole visive consente di creare regole per i gestori di operazioni riuscite e non riuscite per le operazioni Richiama servizio in base alle relative risposte di output. L’immagine seguente mostra il servizio Invoke nell’editor di regole visive per un modulo adattivo:

Aggiunta del gestore di successo e del gestore degli errori

Per aggiungere un gestore operazioni riuscite o non riuscite, fare clic rispettivamente su Aggiungi gestore operazioni riuscite o Aggiungi gestore operazioni non riuscite.

Quando si fa clic su Aggiungi gestore operazioni riuscite, viene visualizzato l’editor di regole Richiama gestore operazioni riuscite del servizio, che consente di specificare regole o logica per gestire la risposta di output Richiama servizio quando l’operazione ha esito positivo. È possibile specificare regole anche senza definire condizioni; tuttavia, è possibile aggiungere condizioni per il gestore di operazione riuscita facendo clic sull’opzione Aggiungi condizione.

È possibile aggiungere più regole per gestire le risposte corrette per l’operazione Richiama servizio:

{width="50%,"}

Analogamente, è possibile aggiungere regole per gestire la risposta di output Invoke Service quando l’operazione non riesce. Nell’immagine seguente viene visualizzato l’editor di regole Richiama gestore errori servizio:

È inoltre possibile aggiungere più regole per gestire le risposte non riuscite dall’operazione Richiama servizio.

La funzionalità Abilita convalida errori sul server consente l’aggiunta di convalide da parte dell’autore durante la progettazione di un modulo adattivo da eseguire anche sul server.

Prerequisiti per l’utilizzo del servizio Invoke nell’editor di regole

Di seguito sono riportati i prerequisiti che è necessario soddisfare prima di utilizzare Invoke Service nell’editor di regole:

Esplorazione del servizio Invoke attraverso diversi casi d’uso

Il servizio Invoke dell’editor di regole visive ti consente di eseguire diverse operazioni utili. Puoi utilizzarlo per popolare le opzioni a discesa, impostare pannelli ripetibili o semplici e convalidare i campi del modulo, il tutto in base alla risposta di output del servizio Invoke. In questo modo, è possibile migliorare la flessibilità e l’interattività dei moduli.

La tabella seguente descrive alcuni scenari in cui è possibile utilizzare il servizio Invoke:

Creare un modulo Get Information che recuperi i valori in base all’input immesso nella casella di testo Pet ID. La schermata seguente mostra il modulo utilizzato in questi casi d’uso:

Campi modulo

Aggiungi i campi seguenti al modulo:

NOTE

Nel campo Associa riferimento della finestra di dialogo Proprietà dei campi modulo, seleziona e passa alla proprietà binaria aggiunta nel modello dati modulo.

Configurazione dei pannelli

Impostate i pannelli come ripetitivi con i seguenti vincoli:

È possibile regolare i valori dei pannelli ripetitivi in base alle proprie esigenze.

Origine dati

In questo esempio viene utilizzata l’API Swagger Petstore per configurare un’origine dati. Il Modello dati modulo è configurato per il servizio getPetById, che recupera i dettagli dell’animale domestico in base all’ID immesso.

Pubblichiamo il seguente JSON utilizzando il servizio addPet nell’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"
    }

Le regole e la logica vengono implementate utilizzando l’azione Richiama servizio nell’editor delle regole nella casella di testo Pet ID per dimostrare i casi d’uso menzionati.

Esaminiamo ora in dettaglio l’implementazione di ogni caso d’uso.

Caso d’uso 1: popolare i valori a discesa utilizzando l’output del servizio di richiamo

Questo caso d’uso illustra come popolare dinamicamente le opzioni a discesa in base all’output di un Invoke Service.

Implementazione

Per ottenere questo risultato, creare una regola nella casella di testo Pet ID per richiamare il servizio getPetById. Nella regola, impostare la proprietà enum del menu a discesa photo-url su photoUrls in Aggiungi gestore di successo.

Output

Immettere 101 nella casella di testo Pet ID per popolare dinamicamente le opzioni del menu a discesa in base al valore immesso.

Caso d’uso 2: impostare un pannello ripetibile utilizzando l’output del servizio di richiamo

Questo caso d’uso illustra come popolare i pannelli ripetibili in modo dinamico in base all’output di un servizio Invoke.

Considerazioni

Implementazione

Creare una regola nella casella di testo Pet ID per richiamare il servizio getPetById. In Aggiungi gestore operazioni riuscite, aggiungi un’altra risposta del gestore operazioni riuscite. Impostare il valore del pannello tags su tags nella regola.

Output

Immettere 101 nella casella di testo Pet ID per popolare il pannello ripetibile in modo dinamico in base al valore di input.

Caso d’uso 3: impostare il pannello utilizzando l’output del servizio di richiamo

In questo caso d’uso viene illustrato come impostare in modo dinamico il valore di un pannello in base all’output di un servizio Invoke.

Considerazioni

Implementazione

Creare una regola nella casella di testo Pet ID per richiamare il servizio getPetById. In Aggiungi gestore operazioni riuscite, aggiungi un’altra risposta del gestore operazioni riuscite. Impostare il valore della casella di testo categoryname su category.name nella regola.

Output

Immettere 101 nella casella di testo Pet ID per popolare il pannello in modo dinamico in base al valore di input.

Caso d’uso 4: utilizzo del parametro di output del servizio Invoke per convalidare altri campi

Questo caso d’uso illustra come utilizzare l’output di un richiama servizio per convalidare dinamicamente altri campi modulo.

Implementazione

Creare una regola nella casella di testo Pet ID per richiamare il servizio getPetById. In Aggiungi gestore errori, aggiungere una risposta del gestore errori. Nascondi il pulsante Invia se viene immesso un Pet ID non corretto.

Output

Immettere 102 nella casella di testo Pet ID e il pulsante Invia è nascosto.

Caso d’uso 5: utilizzo del payload degli eventi in Accedi all’azione nel servizio di richiamo

Questo caso d’uso illustra come configurare una regola sul pulsante Invia che chiama un Richiama servizio e reindirizza l’utente a un’altra pagina utilizzando l’azione Accedi a.

Implementazione

Creare una regola sul pulsante Invia per richiamare il servizio API redirect-api. Questo servizio è responsabile del reindirizzamento dell’utente al modulo Contattaci.

È possibile integrare direttamente un’API come servizio API redirect-api nell’editor di regole utilizzando i dati JSON forniti di seguito:

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

In Aggiungi gestore di successo, configura l’azione Accedi a per reindirizzare l’utente alla pagina Contattaci utilizzando il parametro Event Payload. In questo caso, l’utente può inviare i propri dettagli di contatto.

Facoltativamente, configura un gestore degli errori per visualizzare un messaggio di errore se la chiamata al servizio non riesce.

Output

Quando si fa clic sul pulsante Invia, viene richiamato il servizio API redirect-api. Dopo il completamento, l’utente viene reindirizzato alla pagina Contattaci.

Recuperare i valori delle proprietà da un array JSON

Si tratta di una funzionalità precoce. Se sei interessato, invia un’e-mail rapida dal tuo indirizzo di lavoro a mailto:aem-forms-ea@adobe.com per richiedere l’accesso alla funzionalità.

Forms adattivo supporta la chiamata di un servizio, l’elaborazione delle risposte JSON e il popolamento dinamico dei campi del modulo. Questa sezione descrive come estrarre i valori delle proprietà da un array JSON e associarli ai campi modulo.

Risposta JSON di esempio

L’esempio seguente rappresenta le aree di vendita e l’elenco dei rappresentanti commerciali degli Stati Uniti:

[
  {
    "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"
  }
]

Funzione personalizzata per estrarre i valori delle proprietà

Utilizza la seguente funzione personalizzata per estrarre i valori delle proprietà dall’array 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 funzione personalizzata accetta:

La funzione personalizzata restituisce un semplice array di valori.

Utilizzare la funzione nell’editor di regole

Per recuperare il valore specifico dall’array JSON:

event.payload.invokeServiceResponse.rawPayloadBody

Nell’esempio seguente viene illustrato come compilare un modulo Sales Department utilizzando questa risposta.

Ad esempio, creiamo un modulo Sales Department che include i menu a discesa Select Region e Select Sales Representative.

Passaggio 1: richiama il servizio all’inizializzazione del modulo

WHEN
    Form is initialized
THEN
    Invoke Service → salesdeptinfo

Passaggio 2: popolare il menu a discesa Regione

Aggiungi un handler di successo per la chiamata del servizio e configura la seguente azione:

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

Questa regola legge l’array JSON, estrae i valori della proprietà region e assegna i valori al menu a discesa Select Region.

Allo stesso modo, configura l’azione per il menu a discesa Select Sales Representative nel Gestore di successo.

Quando il modulo viene caricato, vengono restituiti i dati JSON e la funzione personalizzata estrae i valori delle proprietà e il menu a discesa viene popolato automaticamente:

Domande frequenti

D: cosa succede se ho creato una regola utilizzando il servizio Invoke e quindi eseguo l’aggiornamento alla versione più recente dei componenti core?

A: Quando si esegue l’aggiornamento alla versione più recente dei componenti core, la regola Richiama servizio viene aggiornata automaticamente all’interfaccia utente più recente, in quanto è compatibile con le versioni precedenti.

Q: è possibile aggiungere più regole per gestire le risposte di esito positivo o negativo per l’operazione di richiamo del servizio?

A: Sì, è possibile aggiungere più regole per gestire le risposte di esito positivo o negativo per l’operazione Richiama servizio.

Articoli correlati

Risorse aggiuntive