Appeler AEM Forms à l’aide de demandes REST invoking-aem-forms-using-rest-requests

Les exemples et les échantillons de ce document sont réservés à l’environnement AEM Forms sur JEE.

Les processus créés dans Workbench peuvent être configurés pour être appelés avec des requêtes REST (Representational State Transfer). Les requêtes REST sont envoyées à partir de pages HTML. C’est pourquoi, vous pouvez appeler un processus Forms directement à partir d’une page web à l’aide d’une requête REST. Vous pouvez par exemple ouvrir une nouvelle instance d’une page web. Vous pouvez ensuite appeler un processus Forms et charger un document PDF généré avec les données envoyées dans une requête HTTP POST.

Il existe deux types de clients HTML. Le premier client HTML est un client AJAX écrit en JavaScript. Le second type de client est un formulaire HTML contenant un bouton d’envoi. Outre lʼapplication client HTML, il existe dʼautres clients REST possibles. Toute application client prenant en charge les requêtes HTTP peut appeler un service à l’aide d’un appel REST. Par exemple, vous pouvez appeler un service à partir d’un formulaire PDF via un appel REST. (Consultez la section Appeler le processus MyApplication/EncryptDocument depuis Acrobat).

Lorsque vous utilisez des requêtes REST, il est recommandé de ne pas appeler directement les services Forms. Au lieu de cela, appelez les processus qui ont été créés dans Workbench. Lors de la création d’un processus destiné à un appel REST, utilisez un point de départ programmatique. Le point d’entrée REST est alors ajouté automatiquement. Pour plus d’informations sur la création de processus dans Workbench, consultez la section Utiliser Workbench.

Lorsque vous appelez un service à l’aide de REST, une invite vous demande de saisir un nom d’utilisateur ou d’utilisatrice et un mot de passe AEM Forms. Toutefois, si vous ne souhaitez pas spécifier un nom d’utilisateur et un mot de passe, vous pouvez désactiver la sécurité du service.

Pour appeler un service Forms (un processus devient un service lorsque le processus est activé) à l’aide de REST, configurez un point d’entrée REST. (Consultez la section « Gérer les points dʼentrée » dans lʼAide dʼadministration.)

Une fois la configuration dʼun point d’entrée REST terminée, vous pouvez appeler un service Forms à l’aide d’une méthode HTTP GET ou POST.

 action="https://hiro-xp:8080/rest/services/[ServiceName]/[OperationName]:[ServiceVersion]" method="post" enctype="multipart/form-data"

La valeur obligatoire ServiceName est le nom du service Forms à appeler. La valeur facultative OperationName est le nom de lʼopération du service. Si cette valeur nʼest pas spécifiée, ce nom prend par défaut la valeur invoke, qui est le nom de lʼopération qui lance le processus. La valeur facultative ServiceVersion est la version encodée dans le format X.Y. Si cette valeur n’est pas spécifiée, la version la plus récente est utilisée. La valeur enctype peut également être application/x-www-form-urlencoded.

Types de données pris en charge supported-data-types

Les types de données suivants sont pris en charge lors de l’appel des services AEM Forms à l’aide de requêtes REST :

Appels asynchrones asynchronous-invocations

Certains services AEM Forms, tels que les processus pour des intervenants humains de longue durée, prennent beaucoup de temps. Ces services peuvent être appelés de manière asynchrone et non bloquante. (Voir Appel de processus pour des intervenants humains de longue durée.)

Un service AEM Forms peut être appelé de manière asynchrone en remplaçant services par async_invoke dans l’URL d’appel, comme illustré dans l’exemple suivant.

 http://localhost:8080/rest/async_invoke/SomeService. SomeOperation?integer_input_variable=123&string_input_variable=abc

Cette URL renvoie la valeur de l’identifiant (au format « text/plain ») de la tâche responsable de cet appel.

Le statut de l’appel asynchrone peut être récupéré à lʼaide dʼune URL d’appel où services est remplacé par async_status. L’URL doit contenir un paramètre job_id spécifiant la valeur d’identifiant de la tâche associée à cet appel. Par exemple :

 http://localhost:8080/rest/async_status/SomeService.SomeOperation?job_id=2345353443366564

Cette URL renvoie une valeur sous forme dʼentier (au format « text/plain ») codant le statut de la tâche selon la spécification du gestionnaire de tâches (par exemple, 2 signifie en cours d’exécution, 3 signifie terminé, 4 signifie échoué, etc.).

Si la tâche est terminée, l’URL renvoie le même résultat que si le service avait été appelé de manière synchrone.

Une fois la tâche terminée et le résultat récupéré, il est possible de supprimer la tâche à l’aide d’une URL d’appel où services est remplacé par async_dispose. L’URL doit également contenir un paramètre job_id spécifiant la valeur d’identifiant de la tâche. Par exemple :

 http://localhost:8080/rest/async_dispose/SomeService.SomeOperation?job_id=2345353443366564

Si la suppression de la tâche est réussie, cette URL renvoie un message vide.

Rapport d’erreurs error-reporting

Si une demande d’appel synchrone ou asynchrone ne peut pas être effectuée en raison d’une exception générée sur le serveur, lʼexception est signalée dans le message de réponse HTTP. Si l’URL d’appel (ou lʼURL async_result dans le cas d’un appel asynchrone) ne comporte pas de suffixe .xml, le fournisseur REST renvoie le code HTTP 500 Internal Server Error suivi d’un message d’exception.

Si l’URL d’appel (ou lʼURL async_result dans le cas d’un appel asynchrone) comporte un suffixe .xml, le fournisseur REST renvoie le code HTTP 200 OK suivi d’un document XML décrivant l’exception au format suivant.

 <exception>
       <exception_class_name>[
       <DSCError>
          <componentUID>component_UUD</componentUID>
         <errorCode>error_code</errorCode>
         <minorCode>minor_code</minorCode>
         <message>error_message</message>
       </DSCError>
 ]
       <message>exception_message</message>
     <stackTrace>exception_stack_trace</stackTrace>
       </exception_class_name>
     <exception>
       </exception>
 </exception>

Lʼélément DSCError est facultatif et présent uniquement si l’exception est une instance de com.adobe.idp.dsc.DSCException.

Sécurité et authentification security-and-authentication

Pour assurer une transmission sécurisée des appels REST, un administrateur ou une administratrice AEM Forms peuvent activer le protocole HTTPS sur le serveur d’applications J2EE hébergeant AEM Forms. Cette configuration est spécifique au serveur d’applications J2EE ; elle ne fait pas partie de la configuration du serveur Forms.

Services AEM Forms qui prennent en charge les appels REST aem-forms-services-that-support-rest-invocation

Bien qu’il soit recommandé d’appeler directement les processus créés à l’aide de Workbench plutôt que les services, certains services AEM Forms prennent en charge les appels REST. La raison pour laquelle il est recommandé d’appeler un processus plutôt qu’un service directement est qu’il est plus efficace d’appeler un processus. Considérez le scénario suivant. Supposons que vous souhaitiez créer une politique à partir d’un client REST. En d’autres termes, vous souhaitez que le client REST définisse des valeurs telles que le nom de la politique et la période d’ouverture hors ligne.

Pour créer une politique, vous devez définir des types de données complexes tels que l’objet PolicyEntry. Un objet PolicyEntry définit des attributs tels que les autorisations associées à la politique. (Voir Créer des politiques).

Au lieu d’envoyer une requête REST pour créer une politique (ce qui impliquerait de définir des types de données complexes tels qu’un objet PolicyEntry), créez un processus qui crée une politique à l’aide de Workbench. Définissez le processus pour qu’il accepte des variables d’entrée primitives telles qu’une valeur de chaîne qui définit le nom du processus ou un entier qui définit la période d’ouverture hors ligne.

De cette façon, vous n’avez pas à créer de requête d’appel REST qui inclut les types de données complexes requis par l’opération. Le processus définit les types de données complexes et tout ce que vous faites à partir du client REST est d’appeler le processus et de transmettre les types de données primitifs. Pour plus d’informations sur l’appel d’un processus à l’aide de REST, voir Appel du processus MyApplication/EncryptDocument à l’aide de REST.

Les listes suivantes spécifient les services AEM Forms qui prennent en charge les appels REST directs.

Exemples d’appel REST rest-invocation-examples

Les exemples d’appel REST suivants sont fournis :

Transmettre des valeurs booléennes à un processus

L’exemple HTML suivant transmet deux valeurs Boolean à un processus AEM Forms appelé RestTest2. Le nom de la méthode d’appel est invoke et la version est 1.0. Remarquez que la méthode Post HTML est utilisée.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/RestTest2/invoke/1.0" method="post">

 Boolean 1: <input type="text" name="inBooleanList" value="true">
 Boolean 2: <input type="text" name="inBooleanList" value="false">
 <input type="submit" value="Submit">

 </form>

 </body>
 </html>

Transmettre des valeurs de date à un processus

L’exemple HTML suivant transmet une valeur de date à un processus AEM Forms appelé SOAPEchoService. Le nom de la méthode d’appel est echoCalendar. Remarquez que la méthode HTML Post est utilisée.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/SOAPEchoService/echoCalendar" method="post">

 Date: <input type="text" name="value-to-echo" value="2009-01-02T12:15:30Z">
 <input type="submit" value="Submit">

 </form>

 </body>
 </html>

Transmettre des documents à un processus

L’exemple HTML suivant appelle un processus AEM Forms nommé MyApplication/EncryptDocument qui nécessite un document PDF. Pour plus d’informations sur ce processus, voir Appeler AEM Forms à l’aide de MTOM.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/MyApplication/EncryptDocument/invoke" method="post"
          enctype="multipart/form-data">

 File: <input type="file" name="value-to-echo">
 <input type="submit" value="Submit"/>

 </form>

 </body>
 </html>

Transmettre des valeurs de document et de texte à un processus

L’exemple HTML suivant appelle un processus AEM Forms nommé RestTest3 qui nécessite un document et deux valeurs de texte. Remarquez que la méthode Post HTML est utilisée.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/RestTest3" method="post"
          enctype="multipart/form-data">

 Doc: <input type="file" name="inDoc">
 String 1: <input type="text" name="inListOfStrings" value="hello">
 String 2: <input type="text" name="inListOfStrings" value="privet">
 <input type="submit" value="Submit"/>

 </form>

 </body>
 </html>

Transmettre des valeurs d’énumération à un processus

L’exemple HTML suivant appelle un processus AEM Forms nommé SOAPEchoService qui nécessite une valeur d’énumération. Remarquez que la méthode Post HTML est utilisée.

 <html>
 <body>

 <form name="input" action="https://hiro-xp:8080/rest/services/SOAPEchoService/echoEnum" method="post">

 Color Enum Value: <input type="text" name="value-to-echo" value="green">
 <input type="submit" value="Submit">

 </form>

 </body>
 </html>

Appeler le processus MyApplication/EncryptDocument à l’aide de REST

Vous pouvez appeler un processus de courte durée AEM Forms nommé MyApplication/EncryptDocument en utilisant REST.

Lorsque ce processus est appelé, il effectue les actions suivantes :

Appeler le processus MyApplication/EncryptDocument depuis Acrobat

Vous pouvez appeler un processus Forms depuis Acrobat en effectuant une requête REST. Par exemple, vous pouvez appeler le processus MyApplication/EncryptDocument. Pour appeler un processus Forms depuis Acrobat, placez un bouton Envoyer sur un fichier XDP dans Designer. (Voir l’aide de Designer.)

Spécifiez lʼURL dʼappel du processus dans le champ URL d’envoi du bouton, comme illustré ci-après.

L’URL complète pour appeler le processus est la suivante : https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.

Si le processus nécessite un document PDF comme valeur d’entrée, veillez à envoyer le formulaire au format PDF, comme illustré ci-dessus. En outre, pour appeler correctement un processus, il doit renvoyer un document PDF. Sinon, Acrobat ne peut pas traiter la valeur renvoyée et une erreur se produit. Il n’est pas nécessaire de spécifier le nom de la variable de processus d’entrée. Par exemple, le processus MyApplication/EncryptDocument comporte une variable d’entrée nommée inDoc. Si le formulaire est envoyé au format PDF, il n’est pas nécessaire de spécifier inDoc.

Vous pouvez également envoyer les données de formulaire au format XML à un processus Forms. Pour ce faire, assurez-vous que la liste déroulante Submit As spécifie XML. Comme la valeur renvoyée par le processus doit être un document PDF, ce dernier est affiché dans Acrobat.