Pattern di Interazione PUSH per API SOAP

Il pattern di interazione, denominato PUSH, è utilizzabile nel caso in cui il fruitore abbia a sua volta la possibilità di esporre una interfaccia di servizio per la ricezione delle risposte (Fig. 275).

../../../_images/modipa_flusso_PUSH.png

Fig. 275 Flusso previsto in un Pattern di Interazione PUSH

Come riportato dalle Linee Guida di Interoperabilità ModI:

  • Al passo (1), il fruitore DEVE indicare l’endpoint della callback utilizzando l’header SOAP custom “X-ReplyTo”;

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

  • Al passo (3), l’erogatore DEVE riutilizzare lo stesso correlation ID fornito al passo (2) sempre utilizzando l’header SOAP custom X-Correlation-ID;

  • Al passo (4), il fruitore DEVE riconoscere tramite un messaggio di acknowledgement il ricevimento della risposta.

Configurazione delle API

Per attuare la configurazione su GovWay si deve procedere con la registrazione delle due API che definiscono il servizio di ricezione della richiesta e il servizio di Callback dove l’erogatore deve inoltrare la risposta.

  • Richiesta

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

../../../_images/modipa_flusso_PUSH_richiesta_SOAP.png

Fig. 276 Configurazione della richiesta dell’API SOAP (PUSH)

  • Risposta

Successivamente, accedere al dettaglio dell’azione relativa al servizio di callback ed impostare nella sezione “ModI” un pattern di interazione non bloccante “PUSH” con ruolo “Risposta”. Definire anche la correlazione verso il servizio e l’azione relativa alla richiesta come mostrato nella figura Fig. 277:

../../../_images/modipa_flusso_PUSH_risposta_SOAP.png

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

Configurazione dell’Erogazione

Sul dominio dell’erogatore deve essere definita sia un’erogazione dell’API relativa al servizio di richiesta che una fruizione del servizio di callback.

  • Erogazione del Servizio di Richiesta

Le richieste ricevute sull’erogazione vengono validate da GovWay verificando la presenza dell’header SOAP custom “X-ReplyTo” 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.

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

  • Fruizione del Servizio di Callback per la Risposta

Le risposte devono essere inoltrate dall’applicativo mittente utilizzando la fruizione del servizio di Callback configurata su GovWay. Le risposte vengono validate da GovWay verificando la presenza dell’header SOAP custom “X-Correlation-ID”. GovWay permette di fornire l’informazione sull’identificativo di correlazione anche tramite modalità alternative all’header soap (header http, parametri della url…) per poi generare un header soap “X-Correlation-ID” 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 seguente Fig. 278:

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

    Fig. 278 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. 279:

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

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

Configurazione della Fruizione

Sul dominio del fruitore deve essere definita sia una fruizione dell’API relativa al servizio di richiesta che un’erogazione del servizio di callback.

  • Fruizione del Servizio di Richiesta

Le richieste devono essere inoltrate dall’applicativo mittente utilizzando la fruizione del servizio di richiesta configurata su GovWay. Su ogni richiesta GovWay crea, o ne modifica il valore se già presente, dell’header soap “X-ReplyTo” previsto dal profilo “ModI”. L’header viene valorizzato con l’url di invocazione utilizzabile dalla controparte per invocare il servizio di callback configurato su GovWay.

Nota

Header “X-ReplyTo” generato da GovWay

La valorizzazione dell’header soap “X-ReplyTo” da parte di GovWay è disabilitabile intervenendo sulla proprietà «org.openspcoop2.protocol.modipa.soap.push.replyTo.header.updateOrCreate» 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-ReplyTo” nel messaggio di richiesta ricevuto dal backend.

Il messaggio di acknowledgement ricevuto viene anch’esso 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”).

  • Erogazione del Servizio di Callback per la Risposta

Le risposte ricevute sull’erogazione del servizio di Callback vengono validate da GovWay verificando la presenza dell’header SOAP custom “X-Correlation-ID” come previsto dal profilo “ModI”. Effettuata la validazione del messaggio di risposta, 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”).