Erstellen einer benutzerdefinierten Sende-Aktion für adaptive Formulare

Ein adaptives Formular stellt mehrere vordefinierte Sende-Aktionen zur Verfügung. Eine Sende-Aktion gibt Details zu den Aktionen an, die mit den über das adaptive Formular erfassten Daten durchgeführt werden sollen. Beispielsweise das Senden von Daten in einer E-Mail.

Sie können eine benutzerdefinierte Sende-Aktion erstellen, um Funktionen hinzuzufügen, die nicht in vordefinierten Sende-Aktionen enthalten sind oder nicht durch eine einzelne vordefinierte Sende-Aktion unterstützt werden. Beispielsweise das Senden von Daten an einen Workflow, das Speichern der Daten in einem Datenspeicher, das Senden von E-Mail-Benachrichtigungen an die Person, die das Formular sendet, und das Senden einer E-Mail an die Person, die für die Verarbeitung des gesendeten Formulars für Genehmigungen und Ablehnungen verantwortlich ist, über eine einzige Sende-Aktion.

XML-Datenformat

Die XML-Daten werden mit dem Abfrageparameter jcr:data an das Servlet gesendet. Sende-Aktionen können zur Verarbeitung der Daten auf den Parameter zugreifen. Der folgende Code beschreibt das Format der XML-Daten. Die Felder, die an das Formularmodell gebunden sind, befinden sich im Bereich afBoundData. Nicht gebundene Felder befinden sich im afUnoundDataBereich.

<?xml ?>
<afData>
<afUnboundData>
<data>
<field1>value</field2>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
</data>
</afUnboundData>
<afBoundData>
<!-- xml corresponding to the Form Model /XML Schema -->
</afBoundData>
</afData>

Aktionsfelder

Eine Sende-Aktion kann dem gerenderten Formular-HTML (mit dem HTML-Tag input) verborgene Eingabefelder hinzufügen. Diese verborgenen Felder können Werte enthalten, die bei der Verarbeitung der Formularübermittlung benötigt werden. Wenn das Formular gesendet wird, werden diese Formularwerte als Abfrageparameter zurückgegeben, die die Sende-Aktion während der Verarbeitung der Übermittlung verwenden kann. Die Eingabefelder werden als Aktionsfelder bezeichnet.

Eine Sende-Aktion, die auch die für das Ausfüllen eines Formulars benötigte Zeit erfasst, kann beispielsweise die verborgenen Eingabefelder startTime und endTime hinzufügen.

Ein Skript kann die Werte der Felder startTime und endTime bereitstellen, wenn das Formular ausgegeben bzw. bevor das Formular übermittelt wird. Das Skript der Sende-Aktion post.jsp kann dann mithilfe von Abfrageparametern auf diese Felder zugreifen und die für das Ausfüllen des Formulars benötigte Gesamtzeit berechnen.

Dateianhänge

Sende-Aktionen können auch die Dateianhänge nutzen, die Sie mit der Komponente „Dateianhang“ hochladen. Skripts für Sende-Aktionen können mit der Sling-API-Klasse RequestParameter auf diese Dateien zugreifen. Mit der Methode isFormField der API lässt sich identifizieren, ob es sich beim Abfrageparameter um eine Datei oder ein Formularfeld handelt. Sie können in einer Sende-Aktion über die Abfrageparameter iterieren, um Dateianhang-Parameter zu identifizieren.

Mit dem folgenden Beispielcode werden die Dateianhänge in der Abfrage identifiziert. Anschließend werden die Daten mit Get API in die Datei eingelesen. Schließlich wird mit den Daten ein Dokumentobjekt erstellt und an eine Liste angehängt.

RequestParameterMap requestParameterMap = slingRequest.getRequestParameterMap();
for (Map.Entry<String, RequestParameter[]> param : requestParameterMap.entrySet()) {
    RequestParameter rpm = param.getValue()[0];
    if(!rpm.isFormField()) {
        fileAttachments.add(new Document(rpm.get()));
    }
}

Wenn Sie Dateien an das adaptive Formular anhängen, validiert der Server die Dateianhänge nach der Übermittlung des adaptiven Formulars und gibt eine Fehlermeldung zurück, wenn eine der folgenden Bedingungen vorliegt:

  • Dateianhänge enthalten einen Dateinamen, der mit dem Zeichen (.) beginnt, die Zeichen \ / : * ? " < > | ; % $ beinhaltet oder spezielle Dateinamen enthält, die für das Windows-Betriebssystem reserviert sind, wie nul, prn, con, lpt oder com.

  • Die Größe des Dateianhangs beträgt 0 Byte.

  • Das Format des Dateianhangs wird beim Konfigurieren der Komponente „Dateianhang“ in einem adaptiven Formular nicht im Abschnitt Unterstützte Dateitypen definiert.

Weiterleitungspfad und Umleitungs-URL

Nach dem Ausführen der gewünschten Aktion leitet das Sende-Servlet die Abfrage an den Weiterleitungspfad weiter. Eine Aktion verwendet die setForwardPath-API, um den Weiterleitungspfad im Guide Submit-Servlet festzulegen.

Wenn die Aktion keinen Weiterleitungspfad bereitstellt, leitet das Übermittlungs-Servlet den Browser mithilfe der Umleitungs-URL um. Der Autor konfiguriert die Umleitungs-URL über die Konfiguration der Danksagungsseite im Dialogfeld für die Bearbeitung adaptiver Formulare. Sie können die Umleitungs-URL auch über die Sende-Aktion oder die setRedirectUrl-API im Guide Submit-Servlet konfigurieren. Sie können die an die Umleitungs-URL gesendeten Abfrageparameter auch mit der setRedirectParameters-API im Guide Submit-Servlet konfigurieren.

HINWEIS

Ein Autor stellt die Umleitungs-URL bereit (über die Konfiguration der Dankeseite). Vordefinierte Sende-Aktionen verwenden die Umleitungs-URL, um den Browser von der Ressource, auf die der Weiterleitungspfad verweist, umzuleiten.

Sie können eine benutzerdefinierte Sende-Aktion schreiben, die eine Abfrage an eine Ressource oder ein Servlet weiterleitet. Adobe empfiehlt, dass das Skript, das das Ressourcen-Handling für den Weiterleitungspfad durchführt, die Abfrage an die Umleitungs-URL weiterleitet, wenn die Verarbeitung abgeschlossen ist.

Sende-Aktion

Bei einer Sende-Aktion handelt es sich um ein sling:Folder-Objekt, das Folgendes enthält:

  • addfields.jsp: Dieses Skript stellt die Aktionsfelder bereit, die der HTML-Datei während der Ausgabe hinzugefügt werden. Verwenden Sie dieses Skript, um im Skript „post.POST.jsp“ verborgene Eingabeparameter hinzuzufügen, die während der Übermittlung benötigt werden.

  • dialog.xml: Dieses Skript ähnelt dem Dialogfeld für die CQ-Komponente. Es enthält Konfigurationsinformationen, die der Autor anpasst. Die Felder werden im Dialogfeld für die Bearbeitung des adaptiven Formulars auf der Registerkarte „Aktionen übermitteln“ angezeigt, wenn Sie die Sende-Aktion auswählen.

  • post.POST.jsp: Das Submit-Servlet ruft dieses Skript mit den Daten, die Sie übermitteln, und den zusätzlichen Daten aus den vorherigen Bereichen auf. Jede Erwähnung einer Aktionsausführung auf dieser Seite impliziert die Ausführung des Skripts „post.POST.jsp“. Um die Übermittlungsaktion mit dem adaptiven Formular zu registrieren, sodass sie im Dialogfeld für die Bearbeitung des adaptiven Formulars angezeigt wird, fügen Sie diese Eigenschaften zum sling:Folder: hinzu.

    • guideComponentType vom Typ „String“ mit dem Wert fd/af/components/guidesubmittype

    • guideDataModel vom Typ „String“ und der Angabe, für welchen Typ von adaptiven Formularen die Sende-Aktion gilt. xsd wird für adaptive XSD-basierte Formulare unterstützt. basic wird für adaptive Formulare unterstützt, die weder XDP noch XSD verwenden. Um die Aktion in mehreren Typen adaptiver Formulare anzuzeigen, fügen Sie die entsprechenden Zeichenfolgen hinzu. Trennen Sie die Zeichenfolgen durch Kommas. Um beispielsweise eine Aktion in adaptiven XSD-basierten Formularen anzuzeigen, geben Sie den Wert xsd an.

    • jcr:description vom Typ „String“. Der Wert dieser Eigenschaft wird im Dialogfeld für die Bearbeitung adaptiver Formulare auf der Registerkarte „Aktionen übermitteln“ in der Liste „Aktion übermitteln“ angezeigt. Die vordefinierten Aktionen befinden sich im CRX-Repository im Verzeichnis /libs/fd/af/components/guidesubmittype.

    • submitService vom Typ „String“. Weitere Informationen finden Sie unter Planen der Übermittlung adaptiver Formulare für benutzerdefinierte Aktionen.

Erstellen einer benutzerdefinierten Sende-Aktion

Führen Sie die folgenden Schritte aus, um eine benutzerdefinierte Sende-Aktion zu erstellen, die die Daten im CRX-Repository speichert und Ihnen anschließend eine E-Mail sendet. Das adaptive Formular enthält die vordefinierte Sende-Aktion „Inhalt speichern“ (veraltet), mit der die Daten im CRX-Repository gespeichert werden. Zudem stellt AEM eine Mail-API zum Senden von E-Mails bereit. Vor der Verwendung der Mail-API müssen Sie den Service „Day CQ Mail“ über die Systemkonsole konfigurieren. Sie können die Aktion „Inhalt speichern“ (veraltet) erneut verwenden, um Daten im Repository zu speichern. Die Aktion „Inhalt speichern“ (veraltet) ist im Ordner /libs/fd/af/components/guidesubmittype/store im CRX-Repository verfügbar.

  1. Melden Sie sich unter der URL https://<server>:<port>/crx/de/index.jsp bei CRXDE Lite an. Erstellen Sie einen Knoten mit der Eigenschaft „sling:Folder“ und dem Namen „store_and_mail“ im Ordner /apps/custom_submit_action. Erstellen Sie den Ordner „custom_submit_action“, sofern dieser nicht bereits vorhanden ist.

    Screenshot zur Erstellung eines Knotens mit der Eigenschaft „sling:Folder“

  2. Füllen Sie die erforderlichen Konfigurationsfelder aus.

    Fügen Sie die Konfiguration hinzu, die für die Speichern-Aktion erforderlich ist. Kopieren Sie den Knoten cq:dialog der Speichern-Aktion aus dem Ordner /libs/fd/af/components/guidesubmittype/store in den Ordner „action“ unter /apps/custom_submit_action/store_and_email.

    Screenshot zum Kopieren des Knotens „dialog“ in den Ordner „action“

  3. Geben Sie Konfigurationsfelder an, um den Autor zur E-Mail-Konfiguration aufzufordern.

    Das adaptive Formular enthält auch eine E-Mail-Aktion, die E-Mails an Benutzer sendet. Passen Sie diese Aktion basierend auf Ihren Anforderungen an. Navigieren Sie zu /libs/fd/af/components/guidesubmittype/email/dialog. Kopieren Sie die Knoten aus dem Knoten „cq:dialog“ in den Knoten „cq:dialog“ Ihrer Sende-Aktion (/apps/custom_submit_action/store_and_email/dialog?lang=de).

    Anpassen der E-Mail-Aktion

  4. Machen Sie die Aktion im Dialogfeld für die Bearbeitung adaptiver Formulare verfügbar.

    Fügen Sie im Knoten „store_and_email“ die folgenden Eigenschaften ein:

  5. Öffnen Sie ein beliebiges adaptives Formular. Klicken Sie auf die Schaltfläche Bearbeiten neben Start, um das Dialogfeld Bearbeiten des Containers für adaptive Formulare zu öffnen. Die neue Aktion wird auf der Registerkarte Aktionen übermitteln angezeigt. Wenn Sie die Aktion Store and Email auswählen, wird die im Knoten „dialog“ hinzugefügte Konfiguration angezeigt.

    Dialogfeld mit Konfiguration der Sende-Aktion

  6. Verwenden Sie die Aktion, um eine Aufgabe durchzuführen.

    Fügen Sie der Aktion das Skript „post.POST.jsp“ hinzu. (/apps/custom_submit_action/store_and_mail/?lang=de).

    Führen Sie die OOTB-Speicheraktion aus (Skript „post.POST.jsp“). Verwenden Sie die von CQ bereitgestellte FormsHelper.runAction-API (java.lang.String, java.lang.String, org.apache.sling.api.resource.Resource, org.apache.sling.api.SlingHttpServletRequest, org.apache.sling.api.SlingHttpServletResponse) im Code, um die Speicheraktion auszuführen. Fügen Sie der JSP-Datei den folgenden Code hinzu:

    FormsHelper.runAction("/libs/fd/af/components/guidesubmittype/store", "post", resource, slingRequest, slingResponse);

    Zum Senden der E-Mail wird im Code die E-Mail-Adresse des Empfängers aus der Konfiguration gelesen. Um den Konfigurationswert aus dem Skript der Aktion abzurufen, lesen Sie die Eigenschaften der aktuellen Ressource mit dem folgenden Code. Entsprechend können Sie die anderen Konfigurationsdateien lesen.

    ValueMap properties = ResourceUtil.getValueMap(resource);

    String mailTo = properties.get("mailTo");

    Verwenden Sie schließlich die CQ Mail-API zum Senden der E-Mail. Verwenden Sie die SimpleEmail-Klasse, um das E-Mail-Objekt wie unten dargestellt zu erstellen:

    HINWEIS

    Stellen Sie sicher, dass die JSP-Datei den Namen „post.POST.jsp“ hat.

    <%@include file="/libs/fd/af/components/guidesglobal.jsp" %>
    <%@page import="com.day.cq.wcm.foundation.forms.FormsHelper,
           org.apache.sling.api.resource.ResourceUtil,
           org.apache.sling.api.resource.ValueMap,
                    com.day.cq.mailer.MessageGatewayService,
      com.day.cq.mailer.MessageGateway,
      org.apache.commons.mail.Email,
                    org.apache.commons.mail.SimpleEmail" %>
    <%@taglib prefix="sling"
                    uri="https://sling.apache.org/taglibs/sling/1.0" %>
    <%@taglib prefix="cq"
                    uri="https://www.day.com/taglibs/cq/1.0"
    %>
    <cq:defineObjects/>
    <sling:defineObjects/>
    <%
            String storeContent =
                        "/libs/fd/af/components/guidesubmittype/store";
            FormsHelper.runAction(storeContent, "post", resource,
                                    slingRequest, slingResponse);
     ValueMap props = ResourceUtil.getValueMap(resource);
     Email email = new SimpleEmail();
     String[] mailTo = props.get("mailto", new String[0]);
     email.setFrom((String)props.get("from"));
            for (String toAddr : mailTo) {
                email.addTo(toAddr);
       }
     email.setMsg((String)props.get("template"));
     email.setSubject((String)props.get("subject"));
     MessageGatewayService messageGatewayService =
                        sling.getService(MessageGatewayService.class);
     MessageGateway messageGateway =
                    messageGatewayService.getGateway(SimpleEmail.class);
     messageGateway.send(email);
    %>
    

    Wählen Sie die Aktion im adaptiven Formular aus. Die Aktion sendet eine E-Mail und speichert die Daten.

Verwenden der submitService-Eigenschaft für benutzerdefinierte Sende-Aktionen

Wenn Sie eine benutzerdefinierte Sende-Aktion mit der submitService-Eigenschaft festlegen, wird beim Senden ein Aufruf von FormSubmitActionService ausgelöst. FormSubmitActionService verwendet die getServiceName-Methode, um den Wert für die submitService-Eigenschaft abzurufen. Basierend auf dem Wert der submitService-Eigenschaft ruft der Service die entsprechende submit-Methode auf. Nehmen Sie FormSubmitActionService in das benutzerdefinierte Bundle auf, das Sie auf den AEM Forms-Server hochladen.

Fügen Sie die submitService-Eigenschaft vom Typ „String“ dem sling:Folder Ihrer benutzerdefinierten Sende-Aktion hinzu, um Adobe Sign für das adaptive Formular zu aktivieren. Sie können die Option Adobe Sign aktivieren im Bereich Elektronische Signatur der Eigenschaften des Containers für adaptive Formulare erst auswählen, nachdem Sie den Wert für die submitService-Eigenschaft der benutzerdefinierten Sende-Aktion festgelegt haben.

submitService-Eigenschaft

Auf dieser Seite