Utilizzare l’elaborazione batch

Le comunicazioni consentono di creare, assemblare e distribuire comunicazioni personalizzate e orientate al marchio, ad esempio corrispondenze aziendali, documenti, dichiarazioni, lettere di elaborazione delle richieste, note sui benefit, lettere di elaborazione delle richieste, fatture mensili e kit di benvenuto. È possibile utilizzare le API di comunicazione per combinare un modello (XFA o PDF) con i dati dei clienti per generare documenti nei formati PDF, PS, PCL, DPL, IPL e ZPL.

Le comunicazioni forniscono API per la generazione di documenti on-demand e pianificati. Puoi utilizzare le API sincrone per le API on-demand e batch (API asincrone) per la generazione pianificata dei documenti:

  • Le API sincrone sono adatte a casi d’uso on-demand, 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 la compilazione da parte dell’utente di un modulo.

  • Le API Batch (API asincrone) sono adatte a casi d’uso pianificati di alta velocità per la generazione di documenti multipli. Queste API generano documenti in batch. Ad esempio, bollette telefoniche, dichiarazioni con carta di credito e dichiarazioni con benefit generate ogni mese.

Operazioni in 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 ha 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, passa 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 collegare un’istanza di Experience Manager all’archiviazione Microsoft Azure di proprietà del cliente. Ti consente di specificare le credenziali per l’account Microsoft Azure di proprietà del cliente per connettersi ad esso.

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

API batch: Consente di creare configurazioni batch ed eseguire le esecuzioni batch in base a 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 batch.

data-merge-table

Storage: Le API di comunicazione utilizzano l’archiviazione di Microsoft Azure Cloud di proprietà del cliente per recuperare i record dei clienti e archiviare i documenti generati. È possibile configurare l’archiviazione Microsoft Azure in Configurazione Experience Manager Cloud Service.

App: L’applicazione personalizzata per utilizzare le API Batch per generare e utilizzare documenti.

Genera più documenti utilizzando le operazioni batch

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

Puoi guardare il video o eseguire le istruzioni riportate di seguito per scoprire come generare documenti utilizzando operazioni batch. La documentazione di riferimento API utilizzata nei video è disponibile in formato .yaml. È possibile scaricare API batch filma e caricalo su Postman per verificare la funzionalità delle API e segui il video.

Prerequisiti

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

Configurare l’ambiente

Prima di utilizzare un'operazione batch:

  • Caricare i dati dei clienti (file XML) nell’archiviazione BLOB di Microsoft Azure
  • Creare una configurazione Cloud
  • Creare la configurazione dell’archivio dati in batch
  • Caricare modelli e altre risorse nell’istanza di Cloud Service Experience Manager Forms

Caricare i dati dei clienti (file XML) nell’archivio di Azure

Nell’archivio di Microsoft Azure, crea contenitori e caricare dati cliente (XML) al cartelle all'interno dei contenitori.

NOTA

È possibile configurare l’archiviazione 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 un'operazione batch che fa riferimento alle cartelle è ancora in esecuzione.

Creare una configurazione Cloud

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

  1. Vai a Strumenti > Cloud Services > Archiviazione di Azure
  2. Apri una cartella per ospitare la configurazione e fai clic su Crea. Utilizza la cartella Globale o crea una cartella.
  3. Specifica il nome della configurazione e le credenziali per la connessione al servizio. È possibile recupera le credenziali dal portale di archiviazione di Microsoft Azure.
  4. Fai clic su Crea.

L’istanza di Experience Manager è ora pronta per la connessione all’archiviazione Microsoft Azure e per utilizzarla per archiviare e leggere il contenuto, se necessario.

Creare la configurazione dell’archivio dati in batch

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

Per creare la configurazione:

  1. Selezionare Strumenti > Forms > Connettore di archiviazione unificata.
  2. Apri una cartella per ospitare la configurazione e fai clic su Crea. Utilizza la cartella Globale o crea una cartella.
  3. Specifica il Titolo e il Nome della configurazione. In Archiviazione selezionare Archiviazione di Microsoft Azure.
  4. In Percorso di configurazione dell'archiviazione, sfoglia e seleziona la configurazione cloud che contiene le credenziali dell'account di archiviazione Azure di proprietà del cliente.
  5. Nella cartella di origine, specifica il nome del contenitore Archiviazione di Azure e la cartella contenente i record.
  6. Nella cartella di destinazione, specifica il percorso del contenitore e della cartella Archiviazione di Azure per memorizzare i documenti generati.
  7. Fai clic su Crea.

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

Carica modelli e altre risorse nell’istanza di Experience Manager

In genere, un'organizzazione dispone di più modelli. Ad esempio, un modello per i rendiconti della carta di credito, i rendiconti benefici e le applicazioni di credito. Carica tutti i modelli XDP e PDF nella tua istanza Experience Manager. Per caricare un modello:

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

Utilizza l’API batch per generare documenti

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

Creare un batch

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

  • configName: Specificare il nome univoco del batch. 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: Specifica i formati di output: PDF e STAMPA. Se si utilizza il tipo di output PRINT, in 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.

  • template: Specifica il percorso assoluto o relativo del modello. Esempio, crx:///content/dam/formsanddocuments/wknd/statements.xdp

Se specifichi un percorso relativo, fornisci anche una directory principale del contenuto. Per informazioni sulla directory principale dei contenuti, consulta la documentazione API .

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

Eseguire un batch

Per eseguire (eseguire) un batch, utilizza POST /config /[configName]/execution. Ad esempio, per eseguire un batch denominato wknd-demo, utilizzare /config/wknd-demo/execute. Il server restituisce il codice di risposta HTTP 202 quando accetta la richiesta. L’API non restituisce alcun payload, tranne un codice univoco (identificativo dell’esecuzione) nell’intestazione della risposta HTTP per il processo batch in esecuzione sul server. Puoi utilizzare l’identificatore di esecuzione per recuperare lo stato del batch.

NOTA

Durante l’esecuzione del batch, non apportare modifiche alle cartelle di origine e di destinazione corrispondenti, alla configurazione dell’origine dati e alla configurazione di Microsoft Azure Cloud.

Verifica lo stato di un batch

Per recuperare lo stato di un batch, utilizza il 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 di stato . Fornisce dettagli sullo stato del processo batch, sul numero di record già presenti nella pipeline (già letti e in fase di elaborazione) e sullo stato di ogni outputType/renderType(numero di elementi in corso, completati 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.

NOTA
  • 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. Quindi, lo stato restituisce -1 finché tutti i record non sono stati letti.

Visualizza documenti generati

Al termine del processo, i documenti generati vengono memorizzati nella success nella posizione di destinazione specificata nella configurazione dell'archivio dati batch. In caso di errori, il servizio crea un failure cartella. Fornisce informazioni sul tipo e il motivo degli errori.

Comprendiamo con l'aiuto di un esempio: Supponiamo che sia presente un file di dati di input record1.xml e due tipi di output: PDF e PCL. Quindi la posizione di destinazione contiene due sottocartelle pdf e pcl, uno per ciascuno dei tipi di output. Supponiamo che la generazione di PDF sia riuscita, quindi il pdf la sottocartella contiene success sottocartella che a sua volta contiene il documento PDF generato record1.pdf. Supponiamo che la generazione di PCL non sia riuscita, quindi pcl la sottocartella contiene un failure sottocartella che a sua volta contiene un file di errore record1.error.txt che contiene i dettagli dell'errore. Inoltre, il percorso di destinazione contiene una cartella temporanea denominata __tmp__ che contiene alcuni file richiesti durante l'esecuzione batch. Questa cartella può essere eliminata quando non sono presenti esecuzioni batch attive che fanno riferimento alla cartella di destinazione.

NOTA

L'elaborazione di un batch può richiedere un po' di tempo a seconda del numero di record di input e della complessità del modello, attendere 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. È possibile scaricare API batch e caricalo su Postman per verificare la funzionalità delle API.

In questa pagina