Pattern di Interazione PULL per API SOAP

Il pattern di interazione, denominato PULL, prevede che il fruitore non fornisca un indirizzo di callback, mentre l’erogatore fornisce un indirizzo interrogabile per verificare lo stato di processamento di una richiesta e, al fine dell’elaborazione della stessa, il risultato (Fig. 285).

../../../_images/modipa_flusso_PULL_SOAP.png

Fig. 285 Flusso previsto in un Pattern di Interazione PULL per API SOAP

Come riportato dalle Linee Guida di Interoperabilità ModI:

  • L’interfaccia di servizio dell’erogatore fornisce tre metodi differenti al fine di inoltrare una richiesta, controllarne lo stato ed ottenerne il risultato

  • Al passo (1), il fruitore effettua una richiesta;

  • Al passo (2), l’erogatore DEVE fornire insieme all’acknowledgement della richiesta nel body, un correlation ID riportato nel header custom SOAP X-Correlation-ID;

  • Al passo (3), il fruitore DEVE utilizzare i l correlation ID ottenuto al passo (2) per richiedere lo stato di processamento di una specifica richiesta;

  • Al passo (4) l’erogatore, quando il processamento non si è ancora concluso fornisce informazioni circa lo stato della lavorazione della richiesta, quando invece il processamento si è concluso risponde indicando in maniera esplicita il completamento;

  • Al passo (5), il fruitore utilizza il correlation ID di cui al passo (2) al fine di richiedere il risultato della richiesta;

  • Al passo (6), l’erogatore fornisce il risultato del processamento.

Configurazione delle API

Per attuare la configurazione su GovWay si deve procedere con la registrazione dell’API che deve contenere i tre metodi differenti descritti precedentemente.

  • Richiesta

Effettuata la registrazione delle API, accedere al dettaglio dell’azione corrispondente alla richiesta ed impostare nella sezione “ModI” un pattern di interazione non bloccante “PULL” con ruolo “Richiesta” come mostrato nella figura Fig. 286:

../../../_images/modipa_flusso_PULL_richiesta_SOAP.png

Fig. 286 Configurazione della richiesta dell’API SOAP (PULL)

  • Richiesta Stato

Successivamente, accedere al dettaglio dell’azione che consente di richiedere lo stato di processamento ed impostare nella sezione “ModI” un pattern di interazione non bloccante “PULL” con ruolo “Richiesta Stato”. Definire anche la correlazione verso l’azione relativa alla richiesta come mostrato nella figura Fig. 287:

../../../_images/modipa_flusso_PULL_richiestaStato_SOAP.png

Fig. 287 Configurazione della richiesta stato di processamento dell’API SOAP (PULL)

  • Risposta

Accedere al dettaglio dell’azione corrispondente alla risposta ed impostare nella sezione “ModI” un pattern di interazione non bloccante “PULL” con ruolo “Risposta”. Definire anche la correlazione verso l’azione relativa alla richiesta come mostrato nella figura Fig. 288:

../../../_images/modipa_flusso_PULL_risposta_SOAP.png

Fig. 288 Configurazione della risposta dell’API SOAP (PUSH)

Configurazione dell’Erogazione

Sul dominio dell’erogatore deve essere definita l’erogazione dell’API.

  • Richiesta

Le richieste ricevute sull’erogazione vengono inoltrate al backend da GovWay rimanendo poi in attesa dell’acknowledgement.

Ricevuto il messaggio di acknowledgement GovWay verifica la presenza dell’header SOAP custom “X-Correlation-ID”. Se tale header non risulta presente viene generato da GovWay impostando come valore l’identificativo della transazione, che è stato inoltrato con la richiesta al backend tramite gli header di integrazione descritti nella sezione Scambio di informazioni nella richiesta inoltrata dal gateway al server e Altri header di Integrazione (per default tramite l’header http “GovWay-Transaction-ID”).

Nota

Header “X-Correlation-ID” generato da GovWay

La generazione dell’header soap “X-Correlation-ID”, se non presente, è disabilitabile intervenendo sulla proprietà «org.openspcoop2.protocol.modipa.soap.pull.request.correlationId.header.useTransactionIdIfNotExists» presente nel file “/etc/govway/modipa_local.properties” (si assume che “/etc/govway” sia la directory di configurazione indicata in fase di installazione). Se si disabilita la proprietà, GovWay termina con errore la transazione se rileva l’assenza dell’header soap “X-Correlation-ID” nel messaggio di acknowledgement ricevuto dal backend.

  • Richiesta Stato di Processamento

Le richieste che richiedono uno stato del processamento vengono validate da GovWay verificando la presenza dell’header soap “X-Correlation-ID” come previsto dal profilo “ModI”. Effettuata la validazione del messaggio di richiesta, eventualmente gestendo anche gli aspetti di sicurezza descritti nella sezione Sicurezza Messaggio, GovWay inoltra il messaggio al backend e rimane in attesa dell’acknowledgement. L’informazione sull’id di correlazione è inoltrato al backend, oltre che tramite l’header soap “X-Correlation-ID”, anche tramite gli header di integrazione descritti nella sezione Scambio di informazioni nella richiesta inoltrata dal gateway al server e Altri header di Integrazione (per default tramite l’header http “GovWay-Conversation-ID”).

  • Risposta

Le risposte vengono gestite da GovWay in maniera simile a quanto indicato per le richieste di stato del processamento.

Configurazione della Fruizione

Sul dominio del fruitore deve essere definita una fruizione dell’API.

  • Richiesta

Le richieste devono essere inoltrate dall’applicativo mittente utilizzando la fruizione dell’API configurata su GovWay.

Il messaggio di acknowledgement ricevuto viene validato al fine di verificare la presenza dell’header soap “X-Correlation-ID” come previsto dalla specifica “ModI”. L’informazione sull’id di correlazione è ottenibile dall’applicativo mittente sulla risposta, oltre che tramite l’header soap “X-Correlation-ID”, anche tramite gli header di integrazione descritti nella sezione Scambio di informazioni nella richiesta inoltrata dal gateway al server e Altri header di Integrazione (per default tramite l’header http “GovWay-Conversation-ID”).

  • Richiesta Stato di Processamento

Le richieste che richiedono uno stato del processamento devono essere inoltrate dall’applicativo mittente utilizzando la fruizione dell’API configurata su GovWay. Le richieste vengono validate da GovWay verificando la presenza dell’header soap “X-Correlation-ID”. GovWay permette di fornire l’informazione sull’identificativo di correlazione anche tramite modalità alternative all’header soap per poi generarlo come previsto dalla specifica “ModI” valorizzato con il valore fornito. Le modalità alternative sono le seguenti:

  • Header HTTP “X-Correlation-ID”

  • Header HTTP “GovWay-Conversation-ID” o parametro della url “govway_conversation_id” previsto per la correlazione tramite identificativo di collaborazione descritta nella sezione Correlazione tra transazioni differenti. Questa modalità richiede che sia abilitata l’indicazione dell’identificativo di collaborazione nell’API o sulla singola azione come mostrato nella figura Fig. 289:

    ../../../_images/abilitazioneIdCollaborazione_SOAP.png

    Fig. 289 Abilitazione funzionalità di correlazione govway tramite identificativo di colllaborazione

  • Header HTTP “GovWay-Relates-To” o parametro della url “govway_relates_to” previsto per la correlazione tramite riferimento della richiesta descritta nella sezione Correlazione tra transazioni differenti. Questa modalità richiede che sia abilitata l’indicazione dell’identificativo di riferimento alla richiesta nell’API o sulla singola azione come mostrato nella figura Fig. 290:

    ../../../_images/abilitazioneIdRiferimentoRichiesta_SOAP.png

    Fig. 290 Abilitazione funzionalità di correlazione govway tramite identificativo della richiesta

  • Risposta

Le risposte vengono gestite da GovWay in maniera simile a quanto indicato per le richieste di stato del processamento.