Création d’une action Envoyer personnalisée pour les formulaires adaptatifs

Un formulaire adaptatif fournit plusieurs actions Envoyer prêtes à l’emploi. Une action Envoyer spécifie les détails des actions à effectuer sur les données collectées via le formulaire adaptatif, par exemple l’envoi de données sur un e-mail.

Vous pouvez créer une action Envoyer personnalisée pour ajouter des fonctionnalités non incluses dans les actions Envoyer prêtes à l’emploi ou qui ne sont pas prises en charge par une seule action Envoyer prête à l’emploi. Il peut s’agir par exemple de l’envoi de données à un processus, de l’enregistrement des données dans un magasin de données, de l’envoi d’une notification par e-mail à la personne qui envoie le formulaire et de l’envoi d’un e-mail à la personne responsable du traitement du formulaire envoyé pour approbation ou rejet par le biais d’une seule action Envoyer.

Format des données XML

Les données XML sont envoyées à la servlet à l’aide du paramètre de requête jcr:data. Les actions Envoyer peuvent accéder au paramètre pour traiter les données. Le code ci-après décrit le format des données XML. Les champs liés au modèle de formulaire apparaissent dans la section afBoundData. Les champs non liés apparaissent dans la afUnoundDatasection.

<?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>

Champs d’action

Une action Envoyer peut ajouter des champs d’entrée masqués (à l’aide de la balise HTML input) au code HTML du formulaire affiché. Ces champs masqués peuvent contenir les valeurs dont elle a besoin lors du traitement de l’envoi du formulaire. Lors de l’envoi du formulaire, ces valeurs de champ sont publiées en tant que paramètres de requête que l’action Envoyer peut utiliser lors de la gestion de l’envoi. Les champs d’entrée sont appelés champs d’action.

Par exemple, une action Envoyer qui capture également le temps nécessaire pour remplir un formulaire peut ajouter les champs d’entrée masqués startTime et endTime.

Un script peut fournir les valeurs des champs startTime et endTime lors du rendu du formulaire et avant l’envoi du formulaire. Le script de l’action Envoyer post.jsp peut ensuite accéder à ces champs à l’aide des paramètres de requête et calculer le temps total nécessaire au remplissage du formulaire.

Pièces jointes

Les actions Envoyer peuvent également utiliser les pièces jointes que vous joignez à l’aide du composant Pièce jointe. Les scripts des actions Envoyer peuvent accéder à ces fichiers à l’aide de l’API RequestParameter sling. La méthode isFormField de l’API permet de déterminer si le paramètre de requête correspond à un fichier ou à un champ de formulaire. Vous pouvez effectuer une itération sur les paramètres de requête dans une action Envoyer pour identifier les paramètres de pièce jointe.

L’exemple de code ci-après identifie les pièces jointes de la requête. Il lit ensuite les données du fichier à l’aide de Get API. Il crée enfin un objet Document à l’aide des données et l’ajoute à la liste.

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()));
    }
}

Lorsque vous joignez des fichiers au formulaire adaptatif, le serveur valide les pièces jointes après l’envoi du formulaire adaptatif et renvoie un message d’erreur dans les cas suivants :

  • Les pièces jointes comprennent un nom de fichier qui commence par le caractère (.), qui contient les caractères \ / : * ? " < > | % $ ou qui contient des noms de fichier spéciaux réservés au système d’exploitation Windows, tels que nul, prn, con, lpt ou com.

  • La taille de la pièce jointe du fichier est de 0 octet.

  • Le format de la pièce jointe n’est pas défini dans la section Types de fichiers pris en charge lors de la configuration du composant Pièce jointe dans un formulaire adaptatif.

Chemin de transfert et URL de redirection

Après avoir exécuté l’action requise, la servlet Submit transfère la requête vers le chemin de transfert. Une action utilise l’API setForwardPath pour définir le chemin de transfert dans la servlet Guide Submit.

Si l’action ne fournit pas de chemin de transfert, la servlet Submit redirige le navigateur à l’aide de l’URL de redirection. L’auteur configure l’URL de redirection à l’aide de la configuration de la page Merci dans la boîte de dialogue Modifier le formulaire adaptatif. Il est également possible de configurer l’URL de redirection par le biais de l’action Envoyer ou de l’API setRedirectUrl de la servlet Guide Submit. Les paramètres de requête envoyés à l’URL de redirection peuvent aussi être configurés à l’aide de l’API setRedirectParameters de la servlet Guide Submit.

REMARQUE

Un auteur fournit l’URL de redirection (à l’aide de la configuration de la page Merci). Les actions Envoyer prêtes à l’emploi utilisent l’URL de redirection pour rediriger le navigateur à partir de la ressource référencée par le chemin de transfert.

Vous pouvez créer une action Envoyer personnalisée qui transfère une requête vers une ressource ou une servlet. Adobe recommande que le script qui effectue la gestion des ressources pour le chemin de transfert redirige la requête vers l’URL de redirection au terme du traitement.

Action Envoyer

Une action Envoyer est un sling:Folder qui contient les éléments suivants :

  • addfields.jsp : ce script fournit les champs d’action qui sont ajoutés au fichier HTML lors du rendu. Utilisez ce script pour ajouter les paramètres d’entrée masqués requis lors de l’envoi au script post.POST.jsp.

  • dialog.xml : ce script est similaire à la boîte de dialogue Composant CQ. Il fournit des informations de configuration que l’auteur personnalise. Les champs s’affichent sous l’onglet Actions Envoyer de la boîte de dialogue Modifier le formulaire adaptatif lorsque vous sélectionnez l’action Envoyer.

  • post.POST.jsp : la servlet Submit appelle ce script avec les données envoyées et les autres données des sections précédentes. Toute mention relative à l’exécution d’une action dans cette page implique l’exécution du script post.POST.jsp. Pour enregistrer l’action Envoyer avec les formulaires adaptatifs à afficher dans la boîte de dialogue Modifier le formulaire adaptatif, ajoutez les propriétés suivantes au sling:Folder:

    • guideComponentType de type chaîne et valeur fd/af/components/guidesubmittype

    • guideDataModel de type chaîne qui spécifie le type de formulaire adaptatif auquel l’action Envoyer est applicable. xsd est pris en charge pour les formulaires adaptatifs basés sur XSD. basic est pris en charge pour les formulaires adaptatifs qui n’utilisent pas XDP ou XSD. Pour afficher l’action sur plusieurs types de formulaires adaptatifs, ajoutez les chaînes correspondantes. Séparez chaque chaîne par une virgule. Par exemple, pour rendre une action visible sur les formulaires adaptatifs basés sur XSD, spécifiez la valeur en tant que xsd.

    • jcr:description de type chaîne. La valeur de cette propriété est affichée dans la liste des actions Envoyer située sous l’onglet Actions Envoyer de la boîte de dialogue Modifier le formulaire adaptatif. Les actions prêtes à l’emploi figurent dans le référentiel CRX, à l’emplacement /libs/fd/af/components/guidesubmittype.

    • submitService de type chaîne. Pour plus d’informations, voir Planification de l’envoi du formulaire adaptatif pour les actions personnalisées.

Création d’une action Envoyer personnalisée

Pour créer une action Envoyer personnalisée qui enregistre les données dans le référentiel CRX et vous envoie ensuite un e-mail, suivez la procédure ci-après. Le formulaire adaptatif contient l’action Envoyer Stocker le contenu (obsolète) prête à l’emploi qui permet d’enregistrer les données dans le référentiel CRX. En outre, AEM fournit une API de messagerie qui peut être utilisée pour envoyer des e-mails. Avant d’utiliser l’API de messagerie, vous devez configurer le service Day CQ Mail via la console système. Vous pouvez réutiliser l’action Stocker le contenu (obsolète) pour stocker les données dans le référentiel. L’action Stocker le contenu (obsolète) se trouve à l’emplacement /libs/fd/af/components/guidesubmittype/store dans le référentiel CRX.

  1. Connectez-vous à CRXDE Lite en accédant à https://<server>:<port>/crx/de/index.jsp. Créez un nœud avec la propriété sling:Folder et le nom store_and_mail dans le dossier /apps/custom_submit_action. Créez le dossier custom_submit_action, le cas échéant.

    Capture d’écran décrivant la création d’un nœud avec la propriété sling:Folder

  2. Fournissez les champs de configuration obligatoires.

    Ajoutez la configuration nécessaire à l’action Stocker. Copiez le nœud cq:dialog de l’action Stocker à l’emplacement /libs/fd/af/components/guidesubmittype/store dans le dossier d’action à l’emplacement /apps/custom_submit_action/store_and_email.

    Capture d’écran affichant la copie du nœud de boîte de dialogue au dossier d’action

  3. Fournissez des champs de configuration pour demander à l’auteur la configuration des e-mails.

    Le formulaire adaptatif contient également une action E-mail qui permet d’envoyer des e-mails aux utilisateurs. Personnalisez cette action selon vos besoins. Accédez à /libs/fd/af/components/guidesubmittype/email/dialog. Copiez les nœuds du nœud cq:dialog dans le nœud cq:dialog de votre action Envoyer (/apps/custom_submit_action/store_and_email/dialog?lang=fr).

    Personnalisation de l’action d’e-mail

  4. Rendez l’action accessible dans la boîte de dialogue Modifier le formulaire adaptatif.

    Ajoutez les propriétés suivantes au nœud store_and_email :

  5. Ouvrez un formulaire adaptatif. Cliquez sur le bouton Modifier en regard de Démarrer pour ouvrir la boîte de dialogue Modifier du conteneur de formulaires adaptatifs. La nouvelle action s’affiche sous l’onglet Actions Envoyer. La sélection de l’action Store and Email affiche la configuration ajoutée au nœud dialog.

    Boîte de dialogue de configuration de l’action Envoyer

  6. Utilisez l’action pour effectuer une tâche.

    Ajoutez le script post.POST.jsp à votre action. (/apps/custom_submit_action/store_and_mail/?lang=fr).

    Exécutez l’action Stocker prête à l’emploi (script post.POST.jsp). Utilisez l’API FormsHelper.runAction(java.lang.String, java.lang.String, org.apache.sling.api.resource.Resource, org.apache.sling.api.SlingHttpServletRequest, org.apache.sling.api.SlingHttpServletResponse)) fournie par CQ dans votre code pour exécuter l’action Stocker. Ajoutez le code suivant à votre fichier JSP :

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

    Pour envoyer l’e-mail, le code lit l’adresse électronique du destinataire à partir de la configuration. Pour récupérer la valeur de configuration dans le script de l’action, lisez les propriétés de la ressource actuelle à l’aide du code ci-après. Vous pouvez également lire les autres fichiers de configuration.

    ValueMap properties = ResourceUtil.getValueMap(resource);

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

    Utilisez enfin l’API de messagerie CQ pour envoyer l’e-mail. Utilisez la classe SimpleEmail pour créer l’objet Email comme illustré ci-dessous :

    REMARQUE

    Vérifiez que le fichier JSP porte le nom post.POST.jsp.

    <%@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);
    %>
    

    Sélectionnez l’action dans le formulaire adaptatif. L’action envoie un e-mail et stocke les données.

Utilisez la propriété submitService pour les actions Envoyer personnalisées

Lorsque vous définissez l’action Envoyer personnalisée, qui comprend la propriété submitService, le formulaire déclenche l’action FormSubmitActionService lors de l’envoi. L’action FormSubmitActionService utilise la méthode getServiceName pour récupérer la valeur de la propriété submitService. En fonction de la valeur de la propriété submitService, le service appelle la méthode d’envoi appropriée. Incluez FormSubmitActionService dans le lot personnalisé que vous téléchargez sur le serveur AEM Forms.

Ajoutez la propriété submitService de type string sur sling:Folder de votre action Envoyer personnalisée pour activer Adobe Sign pour le formulaire adaptatif. Vous pouvez sélectionner l’option Activer Adobe Sign dans la section Signature électronique des propriétés du conteneur de formulaires adaptatifs uniquement après avoir défini la valeur de la propriété submitService de votre action d’envoi personnalisée.

Propriété du service d’envoi

Sur cette page