[AEM Forms]{class="badge positive" title="Gilt für AEM Forms)."}

Integrieren von externen APIs mit dem visuellen Regeleditor in der Kernkomponente Forms

Der visuelle Regeleditor in einem adaptiven Formular unterstützt die Funktion Service aufrufen, mit der Sie über für Ihre Instanz konfigurierte Formulardatenmodelle (FDM) eine Verbindung zu externen APIs herstellen können. Sie können Formularfelder direkt den Eingabeparametern des Service zuordnen und die Payload-Option „Ereignis“ verwenden, um die Ausgabeparameter zuzuordnen. Mit dem visuellen Regeleditor können Sie auch Regeln für Erfolgs- und Fehlerhandler definieren, die auf der Antwort des Diensts basieren: Erfolgs-Handler verarbeiten erfolgreiche API-Aufrufe, während Fehler-Handler Fehler verwalten.

Auf diese Weise können Sie API-Anfragen aus Ihrem Formular einfach senden, die API-Antworten verarbeiten und die zurückgegebenen Daten dynamisch im Formular anzeigen oder verwenden. Dadurch wird eine nahtlose Integration zwischen Ihrem adaptiven Formular und externen Systemen oder Datenquellen sichergestellt.

Vorteile der Verwendung des Service „Invoke“ im Regeleditor des Formulars

Die Verwendung des Vorgangs „Service aufrufen“ im Regeleditor eines adaptiven Formulars bietet folgende Vorteile:

Aufrufen von Service-Handlern für Erfolgs- und Fehlerantworten

Mit dem visuellen Regeleditor können Sie basierend auf den Ausgabeantworten Regeln für Erfolgs und Fehlerhandler für Vorgänge Dienst aufrufen“ erstellen. Die folgende Abbildung zeigt den Service aufrufen im visuellen Regeleditor für ein adaptives Formular:

Hinzufügen von Erfolgs-Handler und Fehler-Handler

Um einen Erfolgs- oder Fehlerhandler hinzuzufügen, klicken Sie Erfolgs-Handler hinzufügen bzw auf Fehler-Handler hinzufügen.

Wenn Sie auf Add Success Handler klicken, wird der Regeleditor Invoke Service Success Handler angezeigt, in dem Sie Regeln oder Logiken angeben können, um die Antwort Invoke Service zu verwalten, wenn der Vorgang erfolgreich war. Sie können Regeln auch ohne Definition von Bedingungen angeben. Sie können jedoch Bedingungen für den Erfolgshandler hinzufügen, indem Sie auf die Option Bedingung hinzufügen klicken.

Sie können mehrere Regeln hinzufügen, um erfolgreiche Antworten für den Vorgang Service aufrufen zu verarbeiten:

{width="50%,"}

Auf ähnliche Weise können Sie Regeln hinzufügen, um die Service aufrufen-Ausgabeantwort zu verarbeiten, wenn der Vorgang nicht erfolgreich ist. In der folgenden Abbildung wird der Regeleditor Invoke Service Failure Handler angezeigt:

Sie können auch mehrere Regeln hinzufügen, um nicht erfolgreiche Antworten aus dem Vorgang Service aufrufen zu verarbeiten.

Die Funktion Fehlervalidierung auf dem Server aktivieren ermöglicht Validierungen, die vom Autor beim Entwerfen eines adaptiven Formulars hinzugefügt wurden, um auch auf dem Server ausgeführt zu werden.

Voraussetzungen für die Verwendung des Aufrufdienstes im Regeleditor

Im Folgenden finden Sie die Voraussetzungen, die Sie erfüllen müssen, bevor Sie Service aufrufen im Regeleditor verwenden:

Erkunden von Invoke Service durch verschiedene Anwendungsfälle

Mit dem Service „Invoke des visuellen Regeleditors Sie mehrere nützliche Vorgänge ausführen. Sie können damit Dropdown-Optionen ausfüllen, wiederholbare oder einfache Bereiche festlegen und Formularfelder validieren, und zwar alles basierend auf der Ausgabeantwort des Service aufrufen. Dadurch wird die Flexibilität und Interaktivität Ihrer Formulare verbessert.

In der folgenden Tabelle werden einige Szenarien beschrieben, in denen der Service aufrufen verwendet werden kann:

Erstellen Sie ein Get Information Formular, das Werte basierend auf der Eingabe abruft, die in das Textfeld Pet ID eingegeben wurde. Der folgende Screenshot zeigt das Formular, das in diesen Anwendungsfällen verwendet wird:

Formularfelder

Fügen Sie die folgenden Felder zum Formular hinzu:

NOTE

Wählen Sie im Feld Bindungsverweis im Dialogfeld Eigenschaften der Formularfelder aus und navigieren Sie zur binären Eigenschaft, die Sie im Formulardatenmodell (FDM) hinzugefügt haben.

Konfigurieren von Bedienfeldern

Legen Sie die Bereiche mit den folgenden Einschränkungen als repetitiv fest:

Sie können die Werte der sich wiederholenden Bereiche an Ihre Anforderungen anpassen.

Datenquelle

In diesem Beispiel wird die Swagger Petstore-API zum Konfigurieren einer Datenquelle verwendet. Das Formulardatenmodell ist für den Service getPetById konfiguriert, der je nach eingegebener ID Heimtierdetails abruft.

Posten wir die folgende JSON mit dem Service addPet in der 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"
    }

Regeln und Logik werden mithilfe der Aktion Service aufrufen im Regeleditor im Pet ID-Textfeld implementiert, um die erwähnten Anwendungsfälle zu demonstrieren.

Im Folgenden wird nun die Implementierung der einzelnen Anwendungsfälle im Detail untersucht.

Anwendungsfall 1: Auffüllen von Dropdown-Werten mithilfe der Ausgabe von „Service aufrufen“

Dieses Anwendungsbeispiel zeigt, wie Dropdown-Optionen basierend auf der Ausgabe eines Invoke Service dynamisch aufgefüllt werden.

Implementierung

Erstellen Sie dazu eine Regel im Pet ID Textfeld, um den getPetById-Service aufzurufen. Legen Sie in der Regel die enum-Eigenschaft des photo-url-Dropdown-Menüs unter "photoUrls hinzufügen“ auf fest.

Ausgabe

Geben Sie 101 in das Textfeld Pet ID ein, um die Dropdown-Optionen basierend auf dem eingegebenen Wert dynamisch zu füllen.

Anwendungsfall 2: Festlegen eines wiederholbaren Bereichs mithilfe der Ausgabe von „Service aufrufen“

Dieses Anwendungsbeispiel zeigt, wie wiederholbare Bereiche basierend auf der Ausgabe eines „Service " dynamisch werden.

Überlegungen

Implementierung

Erstellen Sie eine Regel für das Pet ID Textfeld, um den getPetById-Service aufzurufen. Fügen in " hinzufügen“ eine weitere Erfolgshandler-Antwort hinzu. Legen Sie in der Regel den Wert des tags Bedienfelds auf tags fest.

Ausgabe

Geben Sie 101 in das Textfeld Pet ID ein, um den wiederholbaren Bereich basierend auf dem Eingabewert dynamisch zu füllen.

Anwendungsfall 3: Festlegen des Bedienfelds mit der Ausgabe von „Service aufrufen“

Dieser Anwendungsfall zeigt, wie Sie den Wert eines Bedienfelds basierend auf der Ausgabe eines „Service " dynamisch.

Überlegungen

Implementierung

Erstellen Sie eine Regel für das Pet ID Textfeld, um den getPetById-Service aufzurufen. Fügen in " hinzufügen“ eine weitere Erfolgshandler-Antwort hinzu. Legen Sie in der Regel den Wert des categoryname Textfelds auf category.name fest.

Ausgabe

Geben Sie 101 in das Textfeld Pet ID ein, um den Bereich basierend auf dem Eingabewert dynamisch zu füllen.

Anwendungsfall 4: Verwenden des Ausgabeparameters „Service aufrufen“, um andere Felder zu validieren

Dieser Anwendungsfall zeigt, wie Sie die Ausgabe eines Service aufrufen zur dynamischen Validierung anderer Formularfelder verwenden.

Implementierung

Erstellen Sie eine Regel für das Pet ID Textfeld, um den getPetById-Service aufzurufen. Fügen in „Fehler-Handler" eine Fehler-Handler-Antwort hinzu. Blenden Sie die Senden aus, wenn eine falsche Pet ID eingegeben wurde.

Ausgabe

Geben Sie 102 in das Pet ID Textfeld ein, und die Schaltfläche Senden ist ausgeblendet.

Anwendungsfall 5: Verwenden der Ereignis-Payload in „Zur Aktion navigieren“ im Dienst „aufrufen“

In diesem Anwendungsbeispiel wird gezeigt, wie eine Regel auf der Schaltfläche Senden konfiguriert wird, die einen Service aufrufen und den Benutzer dann mithilfe der Aktion Navigieren zu“ zu einer anderen.

Implementierung

Erstellen Sie eine Regel für die Schaltfläche Senden, um den redirect-api-API-Service aufzurufen. Dieser Service ist für die Weiterleitung des Benutzers zum Formular Kontakt verantwortlich.

Sie können eine API mithilfe der unten bereitgestellten JSON-Daten direkt als redirect-api-API-Service in Ihren Regeleditor integrieren:

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

Konfigurieren in " hinzufügen“ die Aktion Navigieren zu, um den Benutzer mithilfe des -Parameters zur Seite Kontaktieren Event Payload umzuleiten. Hier kann der Benutzer seine Kontaktdaten übermitteln.

Optional können Sie einen Fehler-Handler konfigurieren, der eine Fehlermeldung anzeigt, wenn der Service-Aufruf fehlschlägt.

Ausgabe

Wenn auf Senden-Schaltfläche geklickt wird, wird der redirect-api-API-Service aufgerufen. Nach erfolgreicher Ausführung wird der Benutzer zur Seite Kontakt weitergeleitet.

Abrufen von Eigenschaftswerten aus einem JSON-Array

Dies ist eine Funktion für frühzeitige Benutzende. Bei Interesse können Sie eine kurze E-Mail von Ihrer Geschäftsadresse an mailto:aem-forms-ea@adobe.com senden, um Zugriff auf die Funktion .

Adaptive Forms unterstützt das Aufrufen eines Services, die Verarbeitung von JSON-Antworten und das dynamische Ausfüllen von Formularfeldern. In diesem Abschnitt wird beschrieben, wie Sie Eigenschaftswerte aus einem JSON-Array extrahieren und an Formularfelder binden.

JSON-Beispielantwort

Das folgende Beispiel stellt die US-Vertriebsregionen und die Liste der Vertriebsmitarbeiter dar:

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

Benutzerdefinierte Funktion zum Extrahieren von Eigenschaftswerten

Verwenden Sie die folgende benutzerdefinierte Funktion, um Eigenschaftswerte aus dem JSON-Array zu extrahieren.

/**
 * 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]);

}

Die benutzerdefinierte Funktion akzeptiert:

Die benutzerdefinierte Funktion gibt ein einfaches Array von Werten zurück.

Verwenden der Funktion im Regeleditor

So rufen Sie den spezifischen Wert aus dem JSON-Array ab:

event.payload.invokeServiceResponse.rawPayloadBody

Das folgende Beispiel zeigt, wie Sie ein Sales Department Formular mithilfe dieser Antwort ausfüllen.

Erstellen wir beispielsweise ein Sales Department Formular, das die Dropdown-Listen Select Region und Select Sales Representative enthält.

Schritt 1: Dienst beim Initialisieren des Formulars aufrufen

WHEN
    Form is initialized
THEN
    Invoke Service → salesdeptinfo

Schritt 2: Füllen Sie das Dropdown-Menü Region

Fügen Sie einen Erfolgshandler für den Service-Aufruf hinzu und konfigurieren Sie die folgende Aktion:

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

Diese Regel liest das JSON-Array, extrahiert die region Eigenschaftswerte und weist die Werte der Select Region Dropdown-Liste zu.

Konfigurieren Sie auf ähnliche Weise die Aktion für das Dropdown-Menü Select Sales Representative im Erfolgshandler.

Wenn das Formular lädt, werden die JSON-Daten zurückgegeben und die benutzerdefinierte Funktion extrahiert Eigenschaftswerte und die Dropdown-Liste wird automatisch ausgefüllt:

Häufig gestellte Fragen

F: Was passiert, wenn ich eine Regel mit dem Service „Invoke“ erstellt und dann auf die neueste Version der Kernkomponenten aktualisiert habe?

A: Wenn Sie ein Upgrade auf die neueste Version der Kernkomponenten durchführen, wird die Regel Service aufrufen automatisch auf die neueste Benutzeroberfläche aktualisiert, da sie abwärtskompatibel ist.

F: Kann ich mehrere Regeln hinzufügen, um erfolgreiche oder fehlgeschlagene Antworten für den Vorgang „Service aufrufen“ zu verarbeiten?

A: Ja, Sie können mehrere Regeln hinzufügen, um erfolgreiche oder fehlgeschlagene Antworten für den Vorgang Service aufrufen zu verarbeiten.

Verwandte Artikel

Zusätzliche Ressourcen