Richiamare AEM Forms tramite richieste REST invoking-aem-forms-using-rest-requests

Gli esempi e gli esempi contenuti in questo documento sono solo per AEM Forms in ambiente JEE.

I processi creati in Workbench possono essere configurati in modo da poterli richiamare tramite richieste REST (Managational State Transfer). Le richieste REST vengono inviate dalle pagine di HTML. In altre parole, è possibile richiamare un processo Forms direttamente da una pagina web utilizzando una richiesta REST. Ad esempio, puoi aprire una nuova istanza di una pagina web. È quindi possibile richiamare un processo Forms e caricare un documento PDF di cui è stato eseguito il rendering con i dati inviati in una richiesta HTTP POST.

Esistono due tipi di client HTML. Il primo client HTML è un client AJAX scritto in JavaScript. Il secondo client è un modulo HTML che contiene un pulsante di invio. Un'applicazione client basata su HTML non è l'unico client REST possibile. Qualsiasi applicazione client che supporta le richieste HTTP può richiamare un servizio utilizzando una chiamata REST. È ad esempio possibile richiamare un servizio utilizzando una chiamata REST da un modulo PDF. (Vedi Richiamo del processo MyApplication/EncryptDocument da Acrobat.)

Quando si utilizzano richieste REST, si consiglia di non richiamare direttamente i servizi Forms. Richiama invece i processi creati in Workbench. Quando crei un processo destinato alla chiamata REST, utilizza un punto iniziale programmatico. In questa situazione, l’endpoint REST viene aggiunto automaticamente. Per informazioni sulla creazione di processi in Workbench, vedere Utilizzo di Workbench.

Quando si richiama un servizio utilizzando REST, viene richiesto di immettere un nome utente e una password per il modulo AEM. Tuttavia, se non si desidera specificare un nome utente e una password, è possibile disattivare la protezione del servizio.

Per richiamare un servizio Forms (un processo diventa servizio quando viene attivato) utilizzando REST, configura un endpoint REST. (Vedi "Gestione degli endpoint" nella guida per l'amministrazione.)

Dopo aver configurato un endpoint REST, è possibile richiamare un servizio Forms utilizzando un metodo HTTP GET o POST.

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

Il valore obbligatorio ServiceName è il nome del servizio Forms da richiamare. Il valore facoltativo OperationName è il nome dell'operazione del servizio. Se questo valore non viene specificato, il nome predefinito sarà invoke, ovvero il nome dell'operazione che avvia il processo. Il valore facoltativo ServiceVersion è la versione codificata nel formato X.Y. Se questo valore non viene specificato, viene utilizzata la versione più recente. Il valore enctype può anche essere application/x-www-form-urlencoded.

Tipi di dati supportati supported-data-types

I seguenti tipi di dati sono supportati quando si richiamano i servizi AEM Forms utilizzando le richieste REST:

Chiamate asincrone asynchronous-invocations

Alcuni servizi di AEM Forms, come i processi a lunga durata incentrati sull’uomo, richiedono molto tempo per essere completati. Questi servizi possono essere richiamati in modo asincrono senza blocchi. (Vedi Richiamare Processi A Lunga Durata Incentrati Sull'Uomo.)

È possibile richiamare un servizio AEM Forms in modo asincrono sostituendo services con async_invoke nell'URL di chiamata, come illustrato nell'esempio seguente.

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

Questo URL restituisce il valore dell’identificatore (in formato "text/plain") del processo responsabile di questa chiamata.

È possibile recuperare lo stato della chiamata asincrona utilizzando un URL di chiamata con services sostituito da async_status. L'URL deve contenere un parametro job_id che specifica il valore dell'identificatore del processo associato a questa chiamata. Ad esempio:

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

Questo URL restituisce un valore intero (in formato "text/plain") che codifica lo stato del processo in base alle specifiche del Manager processo (ad esempio, 2 significa in esecuzione, 3 significa completato, 4 significa non riuscito e così via).

Se il processo è completato, l’URL restituisce lo stesso risultato di se il servizio è stato richiamato in modo sincrono.

Una volta completato il processo e recuperato il risultato, il processo può essere eliminato utilizzando un URL di chiamata con services sostituito con async_dispose. L'URL deve inoltre contenere un parametro job_id che specifica il valore dell'identificatore del processo. Ad esempio:

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

Se il processo viene eliminato correttamente, questo URL restituisce un messaggio vuoto.

Segnalazione di errori error-reporting

Se non è possibile completare una richiesta di chiamata sincrona o asincrona a causa di un'eccezione generata sul server, l'eccezione viene segnalata come parte del messaggio di risposta HTTP. Se l'URL di chiamata (o l'URL async_result in caso di chiamata asincrona) non ha un suffisso .xml, il provider REST restituisce il codice HTTP 500 Internal Server Error seguito da un messaggio di eccezione.

Se l'URL di chiamata (o l'URL async_result se è presente una chiamata asincrona) ha un suffisso .xml, il provider REST restituisce il codice HTTP 200 OK seguito da un documento XML che descrive l'eccezione nel formato seguente.

 <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'elemento DSCError è facoltativo e presente solo se l'eccezione è un'istanza di com.adobe.idp.dsc.DSCException.

Sicurezza e autenticazione security-and-authentication

Per fornire chiamate REST con un trasporto sicuro, un amministratore dei moduli AEM può abilitare il protocollo HTTPS sul server applicazioni J2EE che ospita AEM Forms. Questa configurazione è specifica del server applicazioni J2EE e non fa parte della configurazione del server Forms.

Servizi AEM Forms che supportano la chiamata REST aem-forms-services-that-support-rest-invocation

Sebbene sia consigliabile richiamare i processi creati utilizzando Workbench anziché direttamente i servizi, alcuni servizi di AEM Forms supportano la chiamata REST. Il motivo per cui si consiglia di richiamare direttamente un processo anziché un servizio è che è più efficiente richiamare un processo. Considera lo scenario seguente. Si supponga di voler creare un criterio da un client REST. In altre parole, si desidera che il client REST definisca valori quali il nome del criterio e il periodo di lease offline.

Per creare un criterio, è necessario definire tipi di dati complessi, ad esempio un oggetto PolicyEntry. Un oggetto PolicyEntry definisce attributi quali le autorizzazioni associate al criterio. (Vedi Creazione di criteri.)

Invece di inviare una richiesta REST per creare un criterio (che includerebbe la definizione di tipi di dati complessi come un oggetto PolicyEntry), creare un processo che crei un criterio utilizzando Workbench. Definisci il processo per accettare variabili di input primitive, ad esempio un valore stringa che definisce il nome del processo o un numero intero che definisce il periodo di lease offline.

In questo modo, non è necessario creare una richiesta di chiamata REST che includa i tipi di dati complessi richiesti dall'operazione. Il processo definisce i tipi di dati complessi e tutte le operazioni eseguite dal client REST vengono richiamate e passate ai tipi di dati primitivi. Per informazioni sulla chiamata di un processo tramite REST, vedere Richiamo del processo MyApplication/EncryptDocument tramite REST.

L’elenco seguente specifica i servizi AEM Forms che supportano la chiamata diretta REST.

Esempi di chiamata REST rest-invocation-examples

Vengono forniti i seguenti esempi di chiamata REST:

Trasmissione di valori booleani a un processo

Nell'esempio di HTML seguente vengono passati due valori Boolean a un processo AEM Forms denominato RestTest2. Il nome del metodo di chiamata è invoke e la versione è 1.0. Si noti che viene utilizzato il metodo HTML Post.

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

Trasmissione di valori di data a un processo

Nell'esempio di HTML seguente viene passato un valore di data a un processo AEM Forms denominato SOAPEchoService. Il nome del metodo di chiamata è echoCalendar. Si noti che viene utilizzato il metodo HTML Post.

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

Trasmissione di documenti a un processo

Nell'esempio di HTML seguente viene richiamato un processo AEM Forms denominato MyApplication/EncryptDocument che richiede un documento PDF. Per informazioni su questo processo, vedere Richiamo di AEM Forms tramite 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>

Trasmissione di valori di documento e testo a un processo

Nell'esempio di HTML seguente viene richiamato un processo AEM Forms denominato RestTest3 che richiede un documento e due valori di testo. Si noti che viene utilizzato il metodo HTML Post.

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

Trasferimento dei valori di enumerazione a un processo

Nell'esempio di HTML seguente viene richiamato un processo AEM Forms denominato SOAPEchoService che richiede un valore di enumerazione. Si noti che viene utilizzato il metodo HTML Post.

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

Richiamo del processo MyApplication/EncryptDocument tramite REST

È possibile richiamare un processo AEM Forms di breve durata denominato MyApplication/EncryptDocument utilizzando REST.

Quando viene richiamato, il processo esegue le azioni seguenti:

Richiamo del processo MyApplication/EncryptDocument da Acrobat

È possibile richiamare un processo Forms da Acrobat utilizzando una richiesta REST. È ad esempio possibile richiamare il processo MyApplication/EncryptDocument. Per richiamare un processo Forms da Acrobat, posiziona un pulsante di invio su un file XDP all’interno di Designer. (Vedi Guida di Designer.)

Specifica l'URL per richiamare il processo nel campo Invia all'URL del pulsante, come illustrato nella figura seguente.

L’URL completo per richiamare il processo è https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.

Se il processo richiede un documento PDF come valore di input, assicurarsi di inviare il modulo come PDF, come illustrato nella figura precedente. Inoltre, per richiamare correttamente un processo, il processo deve restituire un documento PDF. In caso contrario, Acrobat non può gestire il valore restituito e si verifica un errore. Non è necessario specificare il nome della variabile di processo di input. Ad esempio, il processo MyApplication/EncryptDocument ha una variabile di input denominata inDoc. Non è necessario specificare inDoc, purché il modulo venga inviato come PDF.

È inoltre possibile inviare i dati del modulo come XML a un processo di Forms. Per inviare i dati XML, verificare che l'elenco a discesa Submit As specifichi XML. Poiché il valore restituito dalla procedura deve essere un documento PDF, il documento PDF viene visualizzato in Acrobat.