Redatto nel nuovo formato il documento di installazione.

docs/installazione/_images/blank.md

@@ -0,0 +1 @@
+file intentionally created blank

docs/installazione/configurazione/index.rst

@@ -64,19 +64,12 @@ contesto di installazione nell'ambiente di esercizio.
 
 Devono essere inserite le seguenti informazioni:
 
--  **Application Server:*\ * *\ *la scelta dell'application server è
-   vincolata su "WildFly 11.0"**
--  **Work*\ * Folder: *\ *inserire il path assoluto della
-   *\ *directory*\ *, presente nell'ambiente di
-   *\ *destinazione*\ *,*\ * *\ *che sarà *\ *utilizzata da GovPay
-   *\ *per accedere a*\ * dati accessori *\ *legati alle*\ *
-   funzionalità opzionali, ad esempio:**
-
+-  **Application Server:** la scelta dell'application server è vincolata su "WildFly 11.0"**
+-  **Work Folder:** inserire il path assoluto della *directory*, presente nell'ambiente di destinazione, che sarà utilizzata da GovPay per accedere a dati accessori legati alle funzionalità opzionali, ad esempio:
    -  **file di configurazione personalizzati**
    -  **loghi dei psp**
 
--  **Log Folder**: inserire il path assoluto della directory, presente
-   nell'ambiente di destinazione, che sarà utilizzata da GovPay per
+-  **Log Folder**: inserire il path assoluto della directory, presente nell'ambiente di destinazione, che sarà utilizzata da GovPay per
    inserire i diversi file di tracciamento prodotti.
 
 Informazioni Applicative
@@ -87,8 +80,7 @@ Informazioni Applicative
    monitoraggio. Tipicamente si fornisce il "principal" dell'utenza
    applicativa registrata sull'Application Server, ma è in alternativa
    possibile indicare altre tipologie di utenze, come ad esempio
-   identificate dal Certificato Client Digitale (maggiori dettagli in
-   merito vengono forniti più avanti).
+   identificate dal Certificato Client Digitale.
 -  *Nome Dominio:* inserire l'hostname tramite il quale saranno
    raggiungibili i servizi di GovPay (ad esempio la console di
    monitoraggio).

docs/installazione/dispiegamento/index.rst

@@ -27,7 +27,7 @@ effettuati i seguenti passi:
 
    -  **psql -h <hostname> -d <database> -U <username> -f sql/gov_pay.sql**
 
-1. In riferimento al valore indicato come "Username
+6. In riferimento al valore indicato come "Username
    Amministratore", creare l’utenza
    applicativa sull'application server che
    rappresenti l'amministratore di GovPay. Per farlo è possibile
@@ -45,21 +45,21 @@ effettuati i seguenti passi:
    -  *Is this new user going to be used for one AS process to connect
       to another AS process?: Indicare “no”*.
 
-1. Copiare il file **datasource/govpay-ds.xml**, contenente la
+7. Copiare il file **datasource/govpay-ds.xml**, contenente la
    definizione del datasource, nella directory
    **<JBOSS_HOME>/standalone/deployments** dell'application server.
-2. Copiare le applicazioni presenti nella directory **archivi** nella
+8. Copiare le applicazioni presenti nella directory **archivi** nella
    directory **<JBOSS_HOME>/standalone/deployments** dell'application server.
-3. Installare il DriverJDBC, relativo al tipo di RDBMS indicato in fase
+9. Installare il DriverJDBC, relativo al tipo di RDBMS indicato in fase
    di setup, nella directory **<JBOSS_HOME>/standalone/deployments** dell'application server.
-4. Editare i datasources installati al **punto 7**. sostituendo la
+10. Editare i datasources installati al **punto 7**. sostituendo la
    keyword **NOME_DRIVER_JDBC.jar** con il nome del file corrispondente
    al driver jdbc.
-5. Verificare che la directory di lavoro e quella di log di GovPay,
+11. Verificare che la directory di lavoro e quella di log di GovPay,
    inserite in fase di configurazione, esistano o altrimenti crearle con
    permessi tali da consentire la scrittura all’utente di esecuzione del
    processo java dell’application server.
-6. Avviare l'application server (ad esempio su Linux con il comando
+12. Avviare l'application server (ad esempio su Linux con il comando
    **<JBOSS_HOME>/bin/standalone.sh** oppure utilizzando il relativo
    service).
 

docs/installazione/verifica/index.rst

@@ -10,9 +10,7 @@ Per la fase di verifica dell'installazione, effettuare i seguenti passi:
    contesti dispiegati, suddivisi tra servizi di frontend (rivolti
    all'utente finale) e servizi di backend (rivolti all'utenza interna):
 
--
-
-   -  **Frontend:**
+2.1 **Frontend:**
 
       -  **/govpay/frontend/web/connector**
 
@@ -28,7 +26,7 @@ Per la fase di verifica dell'installazione, effettuare i seguenti passi:
          **api per la gestione del colloquio con la piattaforma centrale
          pagoPA**
 
-   -  **Backend:**
+2.2 **Backend:**
 
       -  **/govpay/backend/api/pendenze**
 
@@ -50,28 +48,28 @@ Per la fase di verifica dell'installazione, effettuare i seguenti passi:
          **web application che corrisponde al cruscotto di gestione e
          monitoraggio di GovPay**
 
-1. Verificare che i servizi esposti da GovPay verso pagoPA siano
+3. Verificare che i servizi esposti da GovPay verso pagoPA siano
    raggiungibili verificando sul browser le seguenti URL:
 
 -  http://<hostname>:<port>/govpay/frontend/api/pagopa/PagamentiTelematiciCCPservice?wsdl
 -  http://<hostname>:<port>/govpay/frontend/api/pagopa/PagamentiTelematiciRTservice?wsdl
 
-1. Verificare che la **govpayConsole**, l’applicazione web per la
+4. Verificare che la **govpayConsole**, l’applicazione web per la
    gestione della configurazione e monitoraggio di GovPay, sia
    accessibile tramite browser all’indirizzo:
 
--  **http://<hostname>:<port>/govpay/backend/gui/backoffice**
+   -  **http://<hostname>:<port>/govpay/backend/gui/backoffice**
 
-In caso di corretto funzionamento verrà visualizzata la pagina di
-autenticazione per l'accesso alla console.
+   In caso di corretto funzionamento verrà visualizzata la pagina di
+   autenticazione per l'accesso alla console.
 
-1. Accedere alla govpayConsole usando l'utenza di jboss configurata in
+5. Accedere alla govpayConsole usando l'utenza di jboss configurata in
    fase di dispiegamento.
 
    L’utenza creata in precedenza ha accesso a tutte le funzionalità
    compresa la gestione degli utenti. Utilizzando questo accesso
    potranno quindi essere registrati dei nuovi utenti.
 
-2. Completata l’installazione di GovPay, per proseguire con l'utilizzo
+6. Completata l’installazione di GovPay, per proseguire con l'utilizzo
    del sistema si rimanda al “Manuale Utente”.
 

docs/integrazione/interfacce/index.rst

@@ -71,6 +71,9 @@ Il risultato finale è il seguente:
 .. figure:: ../_images/INT08_FormDiImmissioneDati.png
    :align: center
    :name: FormLayoutCompleto
+
+   Form Layout Completo
+
 
 A titolo di esempio si consideri il campo di selezione, i cui valori sono stati inseriti nel json nella seguente sezione:
 
@@ -89,7 +92,9 @@ Il risultato è il seguente
 
 Lo script completo è (si noti le parti di definizione dei pattern di email e codice fiscale)
 
-{
+.. code-block:: guess
+   
+   {
 	"schema": {
 		   "type": "object",
 		   "required": [
@@ -152,16 +157,18 @@ Lo script completo è (si noti le parti di definizione dei pattern di email e co
 			"title": "Tipo di violazione"
 		}
 	]
-}
+   }
 
             
             
 Validazione
 ~~~~~~~~~~~
 
+Lo script di validazione è ancora espresso nel formato json angular schema. Nel nostro esempio si presenta in questo modo:
 
-
-              {
+.. code-block:: guess
+   
+   {
 	"schema": {
 		"type": "object",
 		"required": [
@@ -224,29 +231,215 @@ Validazione
 			"title": "Tipo di violazione"
 		}
 	]
-}
+   }
 
             
+Un'osservazione attenta dello script ne mostra la sostanziale equivalenza con quello di definizione del layout. In effetti lo script afferma che:
+1. I campi necessari sono idPendenza, soggettoPagatore e tipoSanzione, che si mappano su quelli definiti nel punto precedente
+2. idPendenza è una stringa alfanumerica lunga fino a 35 caratteri
+3. l'email non è necessaria: per essa è comunque fornita un'espressione regolare che impedisce l'immissione di email non valide
+4. Il tipo sanzione ammette solo tre valori (123, 456, 789)
+
+In effetti, immettendo lo script nel simulatore prima segnalato si ottiene il seguente risultato
+
+
+.. figure:: ../_images/INT10_FormValidazione.png
+   :align: center
+   :name: Validazione
+
+   Validazione
+
 
+Si nota dai messaggi che il simulatore mostra come le componenti di validazione siano correttamente interpretate.
 
+Ci si potrebbe chiedere il perchè di questa ripetizione (Layout Form Dati e Validazione): la ragione di questa necessità risiede nel comportamento non omogeneo dei browser. La prima validazione è infatti demandata al lato client della filiera applicativa, che non ha alcun contratto sull'esecuzione dei controlli. In altre parole, la piattaforma non ha alcuna sicurezza che i controlli immessi nel Layout Form saranno davvero effettuati lato client: l'unica strategia davvero cautelativa, in casi come questi, è pertanto quella di avere uno strato server di gestione degli errori che, prima di interpretare i dati e trasformarli, provveda alla validazione di quanto immesso anche se arrivato al server senza controlli clienti (comportamento del browser).
+Per i motivi appena descritti, si consiglia sempre di implementare i controlli formali anche in questa sezione.
 
 
 Trasformazione
 ~~~~~~~~~~~~~~
 
+Questa sezione provvede all'instradamento, previa loro trasformazione, dei dati immessi nel form verso i servizi che li consumeranno (applicazione selezionata nella sezione *Inoltro*). Vediamone un esempio complessivo i cui blocchi commenteremo in modo dettagliato:
+
+.. code-block:: guess    
+
+   <#assign jsonUtilities = class["org.openspcoop2.utils.json.JSONUtils"].getInstance()>
+   <#assign request = jsonUtilities.getAsNode(jsonPath.read("$"))>
+   <#assign calendar = class["java.util.Calendar"]>
+   <#assign now = new("java.util.Date")>
+   <#assign calendarInstance = calendar.getInstance()>
+   <#assign xxx = calendarInstance.setTime(now)!>
+   <#assign yyy = calendarInstance.add(calendar.MONTH, 1)!>
+   <#assign zzz = calendarInstance.set(calendar.DATE, calendarInstance.getActualMaximum(calendar.DAY_OF_MONTH))!>
+   <#assign dataValidita = calendarInstance.getTime()?string("yyyy-MM-dd")>
+   <#if request.get("tipoSanzione").asText() = "Violazione art. 123">
+	<#assign importo = "54.01">
+   <#elseif request.get("tipoSanzione").asText() = "Violazione art. 456">
+	<#assign importo = "123.6">
+   <#elseif request.get("tipoSanzione").asText() = "Violazione art. 678">
+	<#assign importo = "307">
+   <#setting locale="en_US">
+   
+   {
+	"idA2A": "A2A-DEMO",
+	"idPendenza": "${request.get("idPendenza").asText()}",
+	"idDominio": "${pathParams["idDominio"]}",
+	"idTipoPendenza": "${pathParams["idTipoPendenza"]}",
+ 	"causale": "Sanzione amministrativa - Verbale n. ${request.get("idPendenza").asText()}",
+	"soggettoPagatore": {
+		"tipo": "F",
+		"identificativo": "${request.get("soggettoPagatore").get("identificativo").asText()}",
+		"anagrafica": "${request.get("soggettoPagatore").get("anagrafica").asText()}",
+		"email": "${request.get("soggettoPagatore").get("email").asText()}"
+	},
+   	"importo": "${importo}",
+	"dataValidita": "${dataValidita}",
+	"dataScadenza": "${dataValidita}",
+	"tassonomiaAvviso": "Servizi erogati dal comune",
+	"voci": [
+		{
+			"idVocePendenza": "1",
+			"importo": "${importo}",
+			"descrizione": "${request.get("tipoSanzione").asText()}",
+			"ibanAccredito": "IT02L1234500000111110000001",
+			"tipoContabilita": "ALTRO",
+			"codiceContabilita": "${pathParams["idTipoPendenza"]}"
+		}
+	]
+   }
+       
+
+Al fine di contestualizzare in modo opportuno il discorso fin qui fatto, è opportuno ricordare il sottostante di questo passo della filiera di elaborazione dei dati, come da interfaccia di configurazione:
 
 
+.. figure:: ../_images/INT13_ContestoDiRiferimento.png
+   :align: center
+   :name: ContestoDiRiferimento
+
+   Contesto di riferimento della trasformazione
+
+
+Analizziamo ora le diverse parti dello script
+
+
+.. code-block:: guess    
+
+   <#assign jsonUtilities = class["org.openspcoop2.utils.json.JSONUtils"].getInstance()>
+   <#assign request = jsonUtilities.getAsNode(jsonPath.read("$"))>
+   <#assign calendar = class["java.util.Calendar"]>
+   <#assign now = new("java.util.Date")>
+   <#assign calendarInstance = calendar.getInstance()>
+   <#assign xxx = calendarInstance.setTime(now)!>
+   <#assign yyy = calendarInstance.add(calendar.MONTH, 1)!>
+   <#assign zzz = calendarInstance.set(calendar.DATE, calendarInstance.getActualMaximum(calendar.DAY_OF_MONTH))!>
+   <#assign dataValidita = calendarInstance.getTime()?string("yyyy-MM-dd")>
+   <#if request.get("tipoSanzione").asText() = "Violazione art. 123">
+	<#assign importo = "54.01">
+   <#elseif request.get("tipoSanzione").asText() = "Violazione art. 456">
+	<#assign importo = "123.6">
+   <#elseif request.get("tipoSanzione").asText() = "Violazione art. 678">
+	<#assign importo = "307">
+   <#setting locale="en_US">
+
+in questa sezione, oltre al trattamento abbozzato delle date di inizio e fine validità (si ricordi che si è in presenza di un esempio) si assegna l'importo in funzione del tipo di sanzione, con la relativa logica di controllo (<#if e seguenti)
+
+Vediamo la sezione di trasformazione vera e propria, con la logica di alimentazione del servizio web di inoltro:
+
+.. code-block:: guess    
+     
+   {
+	"idA2A": "A2A-DEMO",
+	"idPendenza": "${request.get("idPendenza").asText()}",
+	"idDominio": "${pathParams["idDominio"]}",
+	"idTipoPendenza": "${pathParams["idTipoPendenza"]}",
+ 	"causale": "Sanzione amministrativa - Verbale n. ${request.get("idPendenza").asText()}",
+	"soggettoPagatore": {
+		"tipo": "F",
+		"identificativo": "${request.get("soggettoPagatore").get("identificativo").asText()}",
+		"anagrafica": "${request.get("soggettoPagatore").get("anagrafica").asText()}",
+		"email": "${request.get("soggettoPagatore").get("email").asText()}"
+	},
+   	"importo": "${importo}",
+	"dataValidita": "${dataValidita}",
+	"dataScadenza": "${dataValidita}",
+	"tassonomiaAvviso": "Servizi erogati dal comune",
+	"voci": [
+		{
+			"idVocePendenza": "1",
+			"importo": "${importo}",
+			"descrizione": "${request.get("tipoSanzione").asText()}",
+			"ibanAccredito": "IT02L1234500000111110000001",
+			"tipoContabilita": "ALTRO",
+			"codiceContabilita": "${pathParams["idTipoPendenza"]}"
+		}
+	]
+   }
+
+Possiamo notare che:
+*  idPendenza viene preso dal corrispondente campo definito nella sezione di layout. Occorre porre particolare attenzione a che il wording sia il medesimo di quello in definizione formale del form
+*  idDominio, idTipoPendenza vengono valorizzati nello stesso modo
+*  si definisce l'input, per il campo composto voci, come idVocePendenza, importo, descrizione (preso direttamente dalla request), ibanAccredito imposto come fisso, tipo e codice contabilità
 
+In buona sostanza, esiste una parte preparatoria, con una vera logica di trasformazione e definizione di variabili intermedie, ed una parte di elencazione dei parametri del servizio di inoltro che viene implementata a partire dai semilavorati della prima parte. Il risultato è comunque di avere un sistema di input, trasformazione ed elaborazione configurato e pronto per la produzione tramite la scrittura di alcuni semplici script, ovvero senza le costose, classiche fasi di costruzione di un front-end dedicato propriamente detto. Questa metodologia assicura l'ottimizzazione di tempi e costi e la possibilità di effettuare modifiche praticamente in tempo reale. 
 
 
 Promemoria avviso di pagamento
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+La piattaforma intende semplificare anche la corispondenza mail con il soggetto debitore (ovviamente a patto che sia presente e presidiata la mail di quest'ultimo), automatizzando l'invio degli avvisi di pagamento. Possiamo, nella sezione apposita, immettere due script freemarker, uno dedicato all'oggetto della mail, il secondo pensato per generare automaticamente il corpo della stessa. 
+
+.. code-block:: guess    
+
+   Promemoria pagamento: ${versamento.getCausaleVersamento().getSimple()}
+
+A partire dall'oggetto versamento, lo script estrae la causale, generando l'oggetto della mail dell'avviso di pagamento.
+
+
+.. code-block:: guess    
+
+   Gentile ${versamento.getAnagraficaDebitore().getRagioneSociale()}, 
+   le notifichiamo che e' stata elevata una sanzione amministrativa a suo carico: verbale n. ${versamento.getCodVersamentoEnte()}.
+   Puo' effettuare il pagamento on-line dal portale ${dominio.getRagioneSociale()} al seguente indirizzo:
+   https://demo.govcloud.it/govpay-portal/?idDominio=01234567890&numeroAvviso=${versamento.getNumeroAvviso()}.
+   Oppure stampare l'avviso che trova allegato alla presente email per effettuare il pagamento presso un qualsiasi
+   prestatore di servizi di pagamento aderente al circuito pagoPA. 
+   Distinti saluti.
   
-
-
+Ancora una volta si noti l'estrema personalizzabilità del sistema, che rende possibile variare i messaggi a seconda del dominio e del tipo di sanzione in modo trasparente e praticamente in tempo reale. Il messaggio può dipendere, in toni e riferimento, anche dall'eventuale ritardo rispetto alle scadenze, con tempistiche differenziate: ciò comporta la scrittura di logica di processo in termini elementari.
 
 
 Promemoria ricevuta telematica
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A valle del processo di pagamento della pendenza, la piattaforma, similmente a quanto fatto con l'avviso di pagamento, semplifica l'invio di una ricevuta telematica al soggetto pagatore. Possiamo, nella sezione apposita, immettere due script freemarker, uno dedicato all'oggetto della mail, il secondo pensato per generare automaticamente il corpo della stessa. 
+
+.. code-block:: guess    
+
+   <#if rpt.getEsitoPagamento().getCodifica() = 0>
+     Notifica pagamento eseguito: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
+   <#elseif rpt.getEsitoPagamento().getCodifica() = 1>
+     Notifica pagamento non eseguito: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
+   <#elseif rpt.getEsitoPagamento().getCodifica() = 2>
+     Notifica pagamento eseguito parzialmente: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
+   <#elseif rpt.getEsitoPagamento().getCodifica() = 3>
+     Notifica decorrenza termini pagamento: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
+   <#elseif rpt.getEsitoPagamento().getCodifica() = 4>
+     Notifica decorrenza termini pagamento: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
+
+A partire dall'oggetto versamento, lo script estrae la causale, generando l'oggetto della mail dell'avviso di pagamento.
+
+.. code-block:: guess    
+
+   <#assign dataRichiesta = rpt.getDataMsgRichiesta()?string("yyyy-MM-dd HH:mm:ss")>
+   Il pagamento di "${versamento.getCausaleVersamento().getSimple()}" effettuato il ${dataRichiesta} risulta concluso con esito
+   ${rpt.getEsitoPagamento().name()}:
+   Ente creditore: ${dominio.getRagioneSociale()} (${dominio.getCodDominio()})
+   Istituto attestante: ${rpt.getDenominazioneAttestante()} (${rpt.getIdentificativoAttestante()})
+   Identificativo univoco versamento (IUV): ${rpt.getIuv()}
+   Codice contesto pagamento (CCP): ${rpt.getCcp()}
+   Importo pagato: ${rpt.getImportoTotalePagato()}
+   
+   Distinti saluti.
+  
+Questo tipo di soluzione per la ricevuta telematica possiede tutte le caratteristiche positive dell'avviso di pagamento viste nella sezione precedente.