Documentazione AEM as a Cloud Service Guida utente

Elaborazione batch di comunicazioni AEM Forms as a Cloud Service

Ultimo aggiornamento: 19 febbraio 2025

Si applica a:
Experience Manager as a Cloud Service

Argomenti:
Moduli adattivi

Creato per:

Amministratore
Sviluppatore
Utente

Le comunicazioni consentono di creare, assemblare e distribuire comunicazioni personalizzate e orientate al brand, ad esempio corrispondenza aziendale, documenti, rendiconti, lettere di elaborazione delle richieste di rimborso, avvisi sui benefit, fatture mensili e kit di benvenuto. Puoi utilizzare le API di comunicazione per combinare un modello (XFA o PDF) con i dati del cliente per generare documenti in formati PDF, PS, PCL, DPL, IPL e ZPL.

Le comunicazioni forniscono API per la generazione di documenti su richiesta e pianificata. È possibile utilizzare API sincrone per API batch e on-demand (API asincrone) per la generazione pianificata dei documenti:

Le API sincrone sono adatte per casi di utilizzo su richiesta, a bassa latenza e per la generazione di documenti a record singolo. Queste API sono più adatte ai casi d’uso basati su azioni dell’utente. Ad esempio, la generazione di un documento dopo che un utente ha compilato un modulo.
Le API in batch (API asincrone) sono adatte per casi di utilizzo pianificati di generazione di documenti con throughput elevato. Queste API generano documenti in batch. Ad esempio, bollette telefoniche, rendiconti per carta di credito e rendiconti dei benefit generati ogni mese.

Operazioni batch

Un'operazione batch è un processo di generazione di più documenti di tipo simile per un set di record a intervalli pianificati. Un'operazione batch è composta da due parti: Configurazione (definizione) ed esecuzione.

Configurazione (definizione): una configurazione batch memorizza informazioni su varie risorse e proprietà da impostare per i documenti generati. Ad esempio, fornisce dettagli sul modello XDP o PDF e sulla posizione dei dati dei clienti da utilizzare, oltre a specificare varie proprietà per i documenti di output.
Esecuzione: per avviare un'operazione batch, passare il nome della configurazione batch all'API di esecuzione batch.

Componenti di un'operazione batch

Configurazione cloud: la configurazione di Experience Manager Cloud consente di connettere un'istanza di Experience Manager all'archiviazione di Microsoft Azure di proprietà del cliente. Consente di specificare le credenziali per l'account Microsoft Azure di proprietà del cliente per la connessione.

Configurazione archivio dati batch (USC): la configurazione dei dati batch consente di configurare un'istanza specifica dell'archivio BLOB per le API batch. Consente di specificare i percorsi di input e output nell’archiviazione BLOB di Microsoft Azure di proprietà del cliente.

API batch: consente di creare configurazioni batch ed eseguire esecuzioni batch basate su queste configurazioni per unire un modello PDF o XDP con i dati e generare output nei formati PDF, PS, PCL, DPL, IPL e ZPL. Le comunicazioni forniscono API batch per la gestione della configurazione e l’esecuzione in batch.

data-merge-table

Archiviazione: le API di comunicazione utilizzano l'archiviazione cloud di Microsoft Azure di proprietà del cliente per recuperare i record dei clienti e archiviare i documenti generati. È possibile configurare l’archiviazione di Microsoft Azure nella configurazione di Experience Manager Cloud Service.

App: applicazione personalizzata per l'utilizzo delle API Batch per generare e utilizzare documenti.

Generare più documenti utilizzando operazioni batch

È possibile utilizzare le operazioni batch per generare più documenti a intervalli pianificati.

video poster

https://video.tv.adobe.com/v/338349

È possibile guardare il video o eseguire le istruzioni riportate di seguito per imparare a generare documenti utilizzando operazioni batch. La documentazione di riferimento API utilizzata nei video è disponibile in formato .yaml. Puoi scaricare il file API batch e caricarlo in Postman per verificare la funzionalità delle API e seguire il video.

Prerequisiti

Per utilizzare l’API Batch, è necessario quanto segue:

Account di archiviazione Microsoft Azure
Modelli PDF o XDP
Dati da unire con i modelli
Utenti con privilegi di amministratore Experience Manager

Configurare l’ambiente

Prima di utilizzare un'operazione batch:

Carica dati cliente (file XML) nell’archiviazione BLOB di Microsoft Azure
Creare una configurazione cloud
Crea configurazione archivio dati batch
Caricare modelli e altre risorse nell’istanza di Experience Manager Forms Cloud Service

Carica dati cliente (file XML) nell’archiviazione di Azure

Nell'archiviazione di Microsoft Azure creare contenitori e caricare i dati del cliente (XML) nelle cartelle all'interno dei contenitori.

NOTE

È possibile configurare l'archiviazione di Microsoft Azure per pulire automaticamente la cartella di input o spostare il contenuto della cartella di output in una posizione diversa a intervalli pianificati. Tuttavia, assicurati che le cartelle non vengano pulite quando è ancora in esecuzione un’operazione batch che fa riferimento alle cartelle.

Creare una configurazione cloud

La configurazione Cloud connette l’istanza di Experience Manager all’archiviazione di Microsoft Azure. Per creare una configurazione Cloud:

Vai a Strumenti > Cloud Services > Archiviazione Azure
Apri una cartella per ospitare la configurazione e fai clic su Crea. Puoi utilizzare la cartella Globale o crearne una.
Specifica il nome della configurazione e le credenziali per la connessione al servizio. È possibile recuperare queste credenziali dal portale di archiviazione di Microsoft Azure.
Fai clic su Crea.

L'istanza di Experience Manager è ora pronta per connettersi all'archiviazione di Microsoft Azure e utilizzarla per archiviare e leggere il contenuto, quando necessario.

Crea configurazione archivio dati batch

La configurazione dei dati in batch consente di configurare contenitori e cartelle per l’input e l’output. I record dei clienti vengono conservati nella cartella di Source e i documenti generati vengono inseriti nella cartella di destinazione.

Per creare la configurazione:

Vai a Strumenti > Forms > Connettore di archiviazione unificata.
Apri una cartella per ospitare la configurazione e fai clic su Crea. Puoi utilizzare la cartella Globale o crearne una.
Specifica Titolo e Nome della configurazione. In Archiviazione selezionare Archiviazione Microsoft Azure.
In Percorso configurazione archiviazione, sfoglia e seleziona la configurazione cloud che contiene le credenziali dell’account di archiviazione Azure di proprietà del cliente.
Nella cartella Source, specifica il nome del contenitore di archiviazione Azure e della cartella contenente i record.
Nella cartella di destinazione, specifica il percorso del contenitore e della cartella di archiviazione Azure in cui archiviare i documenti generati.
Fai clic su Crea.

L'istanza di Experience Manager è ora connessa all'archiviazione di Microsoft Azure e configurata per recuperare e inviare dati a posizioni specifiche nell'archiviazione di Microsoft Azure.

Carica modelli e altre risorse nella tua istanza di Experience Manager

In genere, un’organizzazione dispone di più modelli. Ad esempio, un modello per gli estratti conto della carta di credito, gli estratti conto benefit e le richieste di rimborso. Carica tutti i modelli XDP e PDF nella tua istanza Experience Manager. Per caricare un modello:

Apri l’istanza di Experience Manager.
Passa a Forms > Forms e documenti
Fai clic su Crea > Cartella e crea una cartella. Apri la cartella.
Fai clic su Crea > Carica file e carica i modelli.

Utilizzare l’API batch per generare documenti

Per utilizzare un’API batch, crea una configurazione batch ed esegui un’esecuzione basata su tale configurazione. La documentazione API fornisce informazioni sulle API per creare ed eseguire un batch, i parametri corrispondenti e i possibili errori. È possibile scaricare il file di definizione API e caricarlo in Postman o software simile per testare le API per creare ed eseguire un'operazione batch.

Creare un batch

Per creare un batch, utilizzare l'API POST /config. Includi le seguenti proprietà obbligatorie nel corpo della richiesta HTTP:

configName: specificare un nome univoco per il batch. Ad esempio wknd-job
dataSourceConfigUri: specificare il percorso della configurazione dell'archivio dati batch. Può essere un percorso relativo o assoluto della configurazione. Esempio: /conf/global/settings/forms/usc/batch/wknd-batch
outputTypes: Specificare i formati di output: PDF e PRINT. Se si utilizza il tipo di output PRINT, nella proprietà printedOutputOptionsList specificare almeno una opzione di stampa. Le opzioni di stampa sono identificate dal relativo tipo di rendering, pertanto al momento non sono consentite più opzioni di stampa con lo stesso tipo di rendering. I formati supportati sono PS, PCL, DPL, IPL e ZPL.
modello: specificare il percorso assoluto o relativo del modello. Ad esempio crx:///content/dam/formsanddocuments/wknd/statements.xdp

Se specifichi un percorso relativo, specifica anche una directory principale del contenuto. Consulta la documentazione API per informazioni dettagliate sulla directory principale dei contenuti.

È possibile utilizzare GET /config /[configName] per visualizzare i dettagli della configurazione batch.

Eseguire un batch

Per eseguire un batch, utilizzare POST /config /[configName]/execution. Ad esempio, per eseguire un batch denominato wknd-demo, utilizza /config/wknd-demo/execution. All’accettazione della richiesta, il server restituisce il codice di risposta HTTP 202. L’API non restituisce alcun payload, ad eccezione di un codice univoco (identificatore di esecuzione) nell’intestazione della risposta HTTP per il processo batch in esecuzione sul server. È possibile utilizzare l'identificatore di esecuzione per recuperare lo stato del batch.

NOTE

Mentre il batch è in esecuzione, non apportare modifiche alle cartelle di origine e di destinazione corrispondenti, alla configurazione dell'origine dati e alla configurazione di Microsoft Azure Cloud.

Controllare lo stato di un batch

Per recuperare lo stato di un batch, utilizzare GET /config /[configName]/execution/[execution-identifier]. L’identificatore di esecuzione è incluso nell’intestazione della risposta HTTP per la richiesta di esecuzione batch.

La risposta della richiesta di stato contiene la sezione relativa allo stato. Fornisce dettagli sullo stato del processo batch, sul numero di record già nella pipeline (già letti ed elaborati) e sullo stato di ciascun outputType/renderType(numero di elementi in corso, riusciti e non riusciti). Lo stato include anche l'ora di inizio e di fine del processo batch insieme alle informazioni sugli eventuali errori. L'ora di fine è -1 fino al completamento dell'esecuzione batch.

NOTE

Quando si richiedono più formati PRINT, lo stato contiene più voci. Ad esempio PRINT/ZPL, PRINT/IPL.
Un processo batch non legge tutti i record contemporaneamente, ma continua a leggere e ad incrementare il numero di record. Lo stato restituisce quindi -1 finché tutti i record non sono stati letti.

Visualizza documenti generati

Al termine del processo, i documenti generati vengono archiviati nella cartella success nel percorso di destinazione specificato nella configurazione dell'archivio dati batch. In caso di errori, il servizio crea una cartella failure. Fornisce informazioni sul tipo e sul motivo degli errori.

Comprendiamo con l'aiuto di un esempio: si supponga che esista un file di dati di input record1.xml e due tipi di output: PDF e PCL. Il percorso di destinazione contiene quindi due sottocartelle pdf e pcl, una per ciascuno dei tipi di output. Supponiamo che la generazione di PDF sia riuscita, quindi la sottocartella pdf contiene la sottocartella success che a sua volta contiene il documento PDF generato record1.pdf. Supponiamo che la generazione PCL non sia riuscita, quindi la sottocartella pcl contiene una sottocartella failure che a sua volta contiene un file di errore record1.error.txt contenente i dettagli dell'errore. Inoltre, il percorso di destinazione contiene una cartella temporanea denominata __tmp__ che contiene alcuni file necessari durante l'esecuzione batch. È possibile eliminare questa cartella se non sono presenti esecuzioni batch attive che fanno riferimento alla cartella di destinazione.

NOTE

L’elaborazione di un batch può richiedere un po’ di tempo a seconda del numero di record di input e della complessità del modello, attendi alcuni minuti prima di controllare le cartelle di destinazione per i file di output.

Documentazione di riferimento API

La documentazione di riferimento API fornisce informazioni dettagliate su tutti i parametri, i metodi di autenticazione e i vari servizi forniti dalle API. La documentazione di riferimento API è disponibile in formato .yaml. Puoi scaricare il file API batch e caricarlo in Postman per verificare la funzionalità delle API.

recommendation-more-help