il componente di form.io per le date è piuttosto avanzato ma può creare problemi di compatibilità con i browser più datati, per fare una form con alto grado di compatibilità consigliamo un campo textfield con input mask 99/99/9999 a cui aggiungiamo una validazione js del tipo:

let passedDate = moment(data.<api>, 'DD/MM/YYYY');
if (!passedDate.isValid()){
  valid = "La data inserita non è valida";
}
if (passedDate.isAfter(moment())){
    valid = "La data inserita non può essere successiva alla data odierna";
}

Controlli avanzati

Questo controllo può essere aggiunto alla custom validation per verificare che la data contenuta nel campo della form my_expiry_date sia valida e successiva alla data odierna.

Il lavoro più rilevante lo fa la libreria momentjs, alla quale si rimanda per maggiori informazioni.

Data di nascita di un minorenne

date = moment(input, 'DD/MM/YYYY')
if (date.isAfter(moment())) {
  valid = "La data non può essere nel futuro"
} else {
  if (moment().diff(date, 'years') > 18) {
    valid = "L'età inserità non è quella di un minorenne"
  }
}

Data successiva alla data odierna

let myDate = moment(data.my_expiry_date, 'DD/MM/YYYY');
if (!myDate.isValid()){
    valid = "La data inserita non è valida";
}

if(!moment(data.my_expiry_date,'DD/MM/YYYY').isSameOrAfter(moment(new Date()),'day')
){
    valid = "La scadenza deve essere uguale o successiva alla data odierna "
}

L'oggetto viene generato automaticamente per ogni pratica, con:

Nome del servizio (primi 255 caratteri + Nome e Cognome + Codice Fiscale del richiedente

L'oggetto può essere sovrascritto usando il campo application_subject all'interno del modulo di form.io.

È necessario seguire i seguenti step:

Aggiungere al form un campo di tipo textfield, poi nella sezione Display settalo come hidden in modo che il cittadino non lo veda,

Nella sezione API lo usare la nomenclatura application_subject,

Nella sezione Data, scendendo in basso dentro Calculated Value, inserire il codice javascript per personalizzare il valore dell'oggetto.

Ecco un esempio di codice per modificare dinamicamente il campo application_subject

Di seguito vengono elencati i componenti Anagrafica disponibili che è possibile includere all'interno dei moduli:

I dati minimi strettamente necessari per le pratiche anonime:

• Codice Fiscale (applicant.data.fiscal_code.data.fiscal_code)

per utenti loggati viene fatto anche il controllo che i seguenti campi siano gli stessi dell'utente loggato:

• Nome (applicant.data.completename.data.name)

• Cognome (applicant.data.completename.data.surname)

• Codice Fiscale (applicant.data.fiscal_code.data.fiscal_code)

se si desidera abilitare l'invio di messaggi via e-mail, è necessario aggiungere all'anagrafica dell'applicant il campo apposito per l'email

• E-mail (applicant.data.email_address)

Se l'anagrafica non contiene la email, è necessario aggiungere nel form un campo con chiave email_address perché funzioni il meccanismo di avviso all'utente degli stati della pratica tramite mail.

Anagrafica Istat

• in base al comune di residenza viene popolato un campo aggiuntivo con il codice istat del comune

• se la residenza è al di fuori dell'Italia si può specificare Provincia EE e compare un campo Nazione per indicare la propria nazione di residenza

• il numero di telefono può comprendere un prefisso internazionale

Anagrafica

Anagrafica lite

Anagrafica extra lite

Anagrafica minimale

(NB: Ricordarsi che questa anagrafica non contiene il campo email, quindi sarà necessario aggiungere nel form un campo con chiave email_address per far funzionare il meccanismo di inoltro mail all'utente).

Anagrafica estesa

Anagrafica semplificata

Anagrafica trentino

Anagrafica genitore FEM

Anagrafica contatti/Anagrafica OC

Calcoli matematici e errori di approssimazione

Quando si usano componenti che richiedono calcoli matematici è consigliato aggiungere una funzione JS che corregge errori di approssimazione.

function round(value, decimals) { return Number(Math.round(value+'e'+decimals)+'e-'+decimals); }

Andare in modifica componente

Sezione Data -> Calculated Values

Aggiungere la funzione che racchiuge il calcola da fare

Quando si usa il componente Datagrid ed accedere ai valori delle righe si deve utilizzare

row.{{nome_input}}

Funzionalità avanzate Per una corretta configurazione del componete Datagrid sono necessarie alcune osservazioni:

• Non usare NestedForm al suo interno

• Per form (datagrid) complessi è consigliata impostare una sola colonna e al suo interno aggiungere un componente Columns e creare la griglia desiderata con i vari input.

Nella sezione di riepilogo il componente al momento porta un problema di struttara dati mostrati i campi come vuoti. Per risolcvere questo problema è necessario aggiungere nell'ultima sezione utile del form un componente Hidden ed aggiungere in Calculated Value il seguente scripts, da modificare in base ai nomi scelti dei Datagrid

Ci sono però alcune regole di base da seguire affinché la creazione del servizio abbia successo.

Regola 0: l'Applicant

All'interno di un modulo form.io deve essere sempre un un'anagrafica nominata Applicant. Deve essere una delle Anagrafiche disponibili come nested form definiti nel sistema.

• [MUST] Quando si inserisce un componente di tipo Nested Form è necessario ricordarsi di togliere la spunta al checkbox Save as reference presente nel tab Form

• [MUST] Non inserire componenti di tipo Nested Form all'interno di elementi di layout per il corretto popolamento automatico dei campi

Regola 1: API value

Per ogni campo compilare sempre il valore di Property Name dell'API, come mostrato in questo esempio:

Questo nome è quello che risulterà anche nelle API quando si consulta con una GET una pratica (application) di quel servizio, per questo motivo è importante rispettare questa convenzione:

1. un nome di tipo snake_case (parole separate da _)

2. usare la lingua inglese

Le date

il componente di form.io per le date è piuttosto avanzato ma può creare problemi di compatibilità con i browser più datati, per fare una form con alto grado di compatibilità consigliamo un campo textfield con input mask 99/99/9999 a cui aggiungiamo una validazione js del tipo:

Pagamenti

Per poter inserire un pagamento in un form va inserito un campo di tipo text e rispettare le seguenti regole:

• [MUST] Il name del campo deve essere payment_amount

Causale di pagamento

È possibile personalizzare il valore della causale di pagamento calcolandone il valore all'interno del form inserendo un campo di tipo text e rispettando le seguenti regole:

• [MUST] Il name del campo deve essere payment_description

• [MUST] Il campo non deve superare i 60 caratteri per evitare che la causale venga troncata all'interno dell'avviso di pagamento pdf generato dal gateway di pagamento MyPay

Nel caso in cui non venga definita nel modulo la causale assumerà un valore di default pari a:

<identificativo pratica> - <codice fiscale richiedente>

Componenti

Wizard

• [MUST] Verificare nelle impostazioni delle pagine che non sia spuntato il campo Collapsible

Componenti nascosti

E'possibile nascondere un componente nell'anteprima e dalla stampa del form aggiungendo la classe css d-preview-none; durante la compilazione del form il componente resterà visibile.

Select popolato via API

• [SHOULD] Quando si inserisce un componente di tipo select è buona norma popolare i campi Data Path (se presente) e Value Property in modo da popolare anche il campo value della select.

Nested form

• [MUST] Quando si inserisce un componente di tipo Nested Form è necessario ricordarsi di togliere la spunta al checkbox Save as reference presente nel tab Form

• [MUST] Non inserire componenti di tipo Nested Form all'interno di elementi di layout per il corretto popolamento automatico dei campi

Upload dei file con componente File

Il componente per l'upload del file è utilizzabile cone le seguenti impostazioni:

• Storage va impostato a Url

• Va specificata un url così composto https://{host}/{instance}/allegati Es.http://stanzadelcittadino.it/comune-di-bugliano/allegati

Se viene specificando in fase di impostazione il tipo di file (tab file del componente upload), questo valore viene utilizzato come descrizione del file

Upload dei file con componente File Sdc

Per il caricamento degli allegati è sufficiente inserire nel modulo il componente File Sdc, non è quindi più necessario configurare storage ed url

In fase di configurazione è ancora possibile specificare il tipo dell'allegato nel tab file, se utilizzato questo valore verrà utilizzato come descrizione del file

Il componente permette inoltre di:

• specificare se la protocollazione dell'allegato è richiesta o meno

• eseguire il controllo della firma sugli allegati inseriti dall'utente

E' buona pratica definire le estensioni ammesse e la dimensione massima degli allegati

Validazione campo recapito telefonico

Usare un componente TextField ed aggiungere in validation sotto la voce "Regular Expression Pattern " il seguente ^[+]*[(]{0,1}[0-9]{1,4}[)]{0,1}[-\s\./0-9]*$

Impedire l'invio di più pratiche per un servizio

In alcuni casi è necessario ricevere per un servizio una sola pratica per ogni cittadino, oppure per ogni impresa oppure per ogni nucleo familiare. Un modo di risolvere questa necessità è l'aggiunta di un campo specifico al modulo sul quale il sistema fa un controllo di univocità. Il campo deve avere nome:

unique_id

Il contenuto deve essere il valore univoco su cui fare il controllo, può essere un valore calcolato.

Pagamento con Bilancio PagoPA - Versione 1 (Mypay)

Il componente bilancio serve per poter dividere l'ammontare dei pagamenti in sottovoci. Per ogni riga di bilancio possono essere specificati:

• Codice del capitolo [MUST]

• Codice dell'ufficio [MUST]

• Codice di accertamento

• Importo [MUST]

Il componete di bilancio è completamente trasparente all'utente finale, deve essere quindi impostato come hidden e deve rispettare le seguenti regole:

• [MUST] Il name del campo deve essere payment_financial_report

• [MUST] La somma degli importi della componente di bilancio deve essere uguale al payment_amount specificato

• [MUST] L'importo all'interno della riga di bilancio deve essere maggiore di 0

Nel caso di componenti di bilancio complesse dipendenti da altri campi del form va inserito il valore delle componenti di bilancio dinamicamente tramite funzione js.

Nel Calculated value del campo Bilancio va inserita una funzione come l'esempio sottostante, tale funzione viene attivata al cambiamento (redraw) del campo collegato (tipologia).

Es.

Pagamento con Bilancio PagoPA - Versione 2 (Mypay v4, Efil, Iris, PmPay, Cittadino digitale, JPPA)

Con l'implementazione dei nuovi proxy di pagamento la suddivisione degli importi nelle varie voci di bilancio viene gestita direttamente nel tab del pagamento della configurazione del servizio.

Nel caso quindi di un bilancio che non varia dinamicamente al variare del modulo non è più necessario inserire il componente bilancio nel modulo.

La configurazione è specifica per ogni proxy, l'interfaccia proposta può quindi variare in base al proxy utilizzato.

Nel caso di componenti di bilancio complesse dipendenti da altri campi del form va inserito un campo hidden nel modulo il cui valore va personalizzato tramite funzione js.

• [MUST] Il name del campo deve essere payment_financial_report

• [MUST] Il componente va impostato come hidden

• [MUST] La somma degli importi della componente di bilancio deve essere uguale al payment_amount specificato

Nel Calculated value del campo payment_financial_report va inserita una funzione come l'esempio sottostante, tale funzione viene attivata al cambiamento (redraw) del campo collegato (tipologia).

Esempio

Configurazione del bilancio nel tab dei pagamenti di un servizio

Codice javascript da inserire nel calculated value del campo payment_financial_report

La chiave dell'oggetto passato deve essere uguale all'id specificato in fase di configurazione.

Rinominare i campi Form.io

Nel caso in cui vengano modificati i nomi dei campi del form con delle pratiche già collegate, i valori inseriti dagli utenti non saranno più visualizzabili nel riepilogo della pratica, ma rimangono registrati all'interno della pratica stessa. Per ripopolare i campi specifici del form è sufficiente aggiungere nel tab "Conditional" il seguente codice (NB: questo è l'unico tab in cui il js non viene rimosso durante l'anteprima):

Il valore della pratica

• Campo convenzionale: application_value

Problemi noti

Una volta aggiunta una nuova scheda in un modulo non si riesce a rimuoverla facendo click sulla X rossa

Workaround: cancellare la tab con la X rossa, fare una modifica qualunque in un'altra scheda, salvare (facendo click sul tasto avanti) e la scheda verrà effettivamente rimossajava

Quando viene utilizzata il componente select popolato via api, nella pagina di riepilogo del modulo così come nella ricevuta pdf e nella pagina dell'operatore verrà visualizzato solo il valore del componente, ma non la sua label.

Se il componente select viene configurato in questo modo:

Durante la compilazione del modulo vengono correttamente visualizzate tutte le opzioni disponibili:

nel momento in cui viene mostrata l'anteprima per il riepilogo non è più visibile la label dell'opzione selezionata, ma solo il suo valore. Nel caso in cui due valori non coincidano il risultato è il seguente:

Configurazione custom

La soluzione a questo problema è utilizzare l'opzione custom nella configurazione del componente select

e utilizzare una logica javascript personalizzata per il recupero delle opzioni della select

Questo esempio utilizza l'SDK Formio per interrogare le api dell'area personale, ma è anche possibile implementare una logica differente.

Il risultato sarà il seguente:

Domande raccolte in fascicoli o correlate tra loro

Un fascicolo è un raggruppamento di due o più pratiche relazionate con una relazione Genitore/Figlio (Parent/Child): la pratica figlia integra la pratica genitore o magari gli è successiva in termini temporali. Solitamente sono pratiche che si protocollano in un unico fascolo.

Per creare una relazione Genitore/Figlio (Parent/Child) tra due pratiche è necessario che la form della pratica figlia contenga i seguenti campi:

• [MUST] un campo di testo related_applications dove l'utente deve inserire il numero della pratica genitore,

• [MUST] un campo hidden (il cui identificatore può avere qualsiasi nome, ad esempio calculate_related_applications) di supporto per effettuare la validazione del numero di pratica inserito

[MUST] Occorre impostare il seguente codice in Validation nel campo related_applications:

Attenzione occorre specificare correttamente l'api url nella funzione getData() così composto https://{host}/{instance}/api/status/applications/

(nell'esempio è specificato https://servizi.comune-qa.bugliano.pi.it/lang/api/status/applications/)

[MUST] Occorre impostare il seguente codice in Data / Calcuated Value nel campo calculate_related_applications

Definizione

Una pratica geolocalizzata è una pratica dotata di una informazione geografica. Dal punto di vista dei dati il requisito minimo è la presenza di un campo address contenente almeno una coordinata.

Se disponibile può essere mostrata anche una descrizione testuale del luogo:

Una descrizione completa può comprendere anche molti altri dati, tra cui la definizione puntuale di tutti gli elementi dell'indirizzo.

Pratiche geolocalizzate a form.io

Se voglio geolocalizzare le pratiche di un servizio, è necessario aggiungere un campo di tipo address come da immagine. Questo elemento deve essere di primo livello, quindi non può essere contenuto da altri componenti, se non quelli di layout. Ad esempio non può essere inserito in un componente data, come un Data Grid o un Container, ma può essere contenuto in un elemento layout, come un Panel o un Fieldset).

Nella configurazione del campo è necessario impostare come "Provider" OpenStreetMap Nominatim (⚠️unico provider supportato) e come "API"->"Property Name" address.

• Esempio di uno schema completo per un campo address

• Esempio di JSON presente in una pratica che contiene un campo di questo tipo

Nel servizi a sottoscrizione sono disponibili due integrazioni:

• Iscrizione al servizio per l'iscrizione di un cittadino

• Pagamenti per servizi a sottoscrizione per registrare un pagamento collegato ad un'iscrizione esistente

Iscrizione al servizio

Per creare un iscrizione ad un servizio a sottoscrizione è necessario che il modulo contenga i seguenti campi:

• Subform applicant: dati anagrafici del richiedente

• Campo code: codice del servizio a sottoscrizione

Oppure nel caso di iscrizione per conto di altri (esempio di un genitore che iscrive il figlio minorenne):

• Subform subscriber: dati anagrafici del richiedente

• Campo code: codice del servizio a sottoscrizione

Il subform applicant/subscriber dovrà fornire i campi:

NOTE

• Nel caso in cui l'iscrizione preveda un pagamento verrà automaticamente salvato un pagamento associato all'iscrizione appena creata con una descrizione fissa Quota di iscrizione e nome Quota di iscrizione - {nome corso} - {nome e cognome iscritto} {cf iscritto}

• Il sistema consente un'unica iscrizione per corso, è dunque necessario bloccare iscrizioni duplicate durante la compilazione del modulo. A questo scopo è sufficiente effettuare una richiesta all'endpoint https://{host}/{instance}/subscriptions/availability?code={code}&cf={fiscal_code} dove

  • code è il codice del corso per il quale si vuole verificare l'esistenza di duplicati;

  • fiscal_code è il codice fiscale del cittadino che si desidera iscrivere (nota distinzione applicant e subscriber descritta nel paragrafo precedente)

La chiamata restituisce 400/406/200 a seconda della disponibilità dell'iscrizione.

Si rimanda alla validazione descritta nel paragrafo "Fascicoli".

Pagamenti per Servizi a sottoscrizione

Per salvare un pagamento associato ad un iscrizione esistente è necessario che il modulo contenga i seguenti campi:

L'iscritto effettua il pagamento per se stesso

• Subform applicant: dati anagrafici del richiedente (i.e. l'iscritto che effettua il pagamento)

• Campo code: codice del servizio a sottoscrizione

• Campo payment_identifier: identificativo del pagamento che verrà salvato come nome della voce di pagamento

• Campo payment_amount: importo del pagamento

• Campo payment_reason: Causale del pagamento che verrà salvata come descrizione della voce di pagamento

• Campo unique_id: Vincolo di univocità: questo campo serve nel caso in cui vengano create delle pratiche in bozza oppure l'import dei pagamenti tramite csv, in modo che non vengano create pratiche di pagamento duplicate

Il subform applicant/subscriber dovrà fornire i campi:

Il campo code può essere sostituito con il campo subscription_service contenente l'identificativo del servizio a sottoscrizione

L'iscritto effettua il pagamento per un altro

Nel caso in cui il richiedente effettua il pagamento per un iscritto deve essere presente il subform subscriber analogamente a quanto avviene per l'integrazione Servizi a sottoscrizione.

Anche in questo caso è possibile sostituire il campo code con il campo subscription_service

NOTE:

Affinche l'integrazione vada a buon fine una volta verificato il pagamento è indispensabile che esista un iscrizione per il cittadino con il codice fiscale inserito nel modulo. Nel caso contrario la pratica resterà bloccata nello stato precedente a quello indicato come punto di attivazione

Prenotazione appuntamenti

Per aggangiare un servizio form.io al backoffice della prenotazione appuntamenti la form dovrà contenere almeno i seguenti campi:

• Subform applicant: dati anagrafici del richiedente: Non sono richiesti tutti i campi presenti nel componente/subform anagrafica, ma è sufficiente utilizzare la subform anagrafica-lite (name, surname, email_address, phone_number e fiscal_code)

• Campo calendar: il calendario per la scelta del giorno e dello slot disponibile. La compilazione di questo campo restituirà una stringa del tipo d/m/Y @ H:i-H:i (calendar_id#meeting_id#opening_hour_id)

• Campo user_message: il messaggio descrittivo dell'utente che prenota l'appuntamento

Si consiglia di utilizzare il form Anagrafica-lite a tale scopo.

Una volta creati i vari layout fildset, inserirci tutti i componenti da raggruppare a livello logico, similmente a quanto fatto nel servizio di riferimento del design comuni .

Requisiti minimi per un corretto funzionamento

1. Tutte le chiamate esterne devono avere il protocollo HTTPS

2. Abilitare i CORS a qualsiasi dominio oppure verso https://www2.stanzadelcittadino.it/

3. Dal modulo della pratica NON è possibile chiamare indirizzi arbitrari

Le funzioni disponibili sono accessibili da window.FormioHelper

authenticatedCall('applications'): Promise

restituisce le pratiche dell'utente autenticato

Esempio: Settare le opzioni di una select

async function get_data() {
  window.FormioHelper.authenticatedCall("applications")
  .then(
    function(promise) {
      console.log(promise)
      instance.setItems(promise.data)
    })
}

if (values.length === 0) {
  get_data()
}

getTenantInfo(): Promise

restituisce le info del tenant, in particolare è utile per reperire il tenant-id

Esempio:

async function check() {
  tenant = await window.FormioHelper.getTenantInfo()
  if (tenant.comune === data.applicant.data.address.data.municipality) {
    ...
  } else {
    ...
  }
}

oppure

window.FormioHelper.getTenantInfo().then(data => {...})

getCurrentLocale(): string

restituisce la lingua corrente

Esempio:

lang = window.FormioHelper.getCurrentLocale()
if (lang === "it") {
...
} else {
...
}

getRemoteJson(url, method = 'get', headers = null): Promise

restiuisce un json da una API remota specificando eventualmente metodo e headers custom per la chiamata

Esempio: Settare le opzioni di una select

async function get_data() {
  window.FormioHelper.getRemoteJson('https://api.opencontent.it/geo/comuni')
  .then(
    function(promise) {
      console.log(promise)
      instance.setItems(promise.data)
    })
}

if (values.length === 0) {
  get_data()
}

oppure

window.FormioHelper.getRemoteJson('https://api.opencontent.it/geo/comuni')
.then(data => {...})

getFieldApplication(): Promise

restituisce il valore della chiave passata come parametro dell'oggetto application di una pratica

// Esempio oggetto application
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user_name": "string",
  "service": "string",
  "service_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "service_name": "string",
  "service_group_name": "string",
  "tenant": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "subject": "string",
  "data": {},
  "compiled_modules": [
    {}
  ],
  "attachments": [
    {}
  ],
  "creation_time": 0,
  "created_at": "2024-05-14T08:03:14.112Z",
  "submission_time": 0,
  "submitted_at": "2024-05-14T08:03:14.112Z",
  "latest_status_change_time": 0,
  "latest_status_change_at": "2024-05-14T08:03:14.112Z",
  "protocol_folder_number": "string",
  "protocol_folder_code": "string",
  "protocol_number": "string",
  "protocol_document_id": "string",
  "protocol_numbers": [
    {}
  ],
  "protocol_time": 0,
  "protocolled_at": "2024-05-14T08:03:14.112Z",
  "outcome": true,
  "outcome_motivation": "string",
  "outcome_file": {},
  "outcome_attachments": [
    {}
  ],
  "outcome_protocol_number": "string",
  "outcome_protocol_document_id": "string",
  "outcome_protocol_numbers": [
    {}
  ],
  "outcome_protocol_time": 0,
  "outcome_protocolled_at": "2024-05-14T08:03:14.112Z",
  "payment_type": "string",
  "payment_data": {},
  "status": "string",
  "status_name": "string",
  "authentication": {},
  "links": {},
  "meetings": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "integrations": [
    {}
  ],
  "backoffice_data": {},
  "flow_changed_at": "2024-05-14T08:03:14.112Z",
  "user_compilation_notes": "string",
  "external_id": "string",
  "geographic_areas": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string"
    }
  ],
  "user_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operator_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "locale": "string"
}

Esempio:

Senza nessun parametro restituisce tutto l'oggetto application

window.FormioHelper.getFieldApplication().then(data => {console.log(data)})

Con parametro restituisce il valore della chiave oggetto

window.FormioHelper.getFieldApplication('id').then(data => {console.log(data)})

getFieldMeta(): string

Esempio: Recupero dato dai meta

Senza nessun parametro restituisce tutto l'oggetto meta

window.FormioHelper.getFieldMeta()

Con parametro restituisce il valore della chiave oggetto - primo livello

window.FormioHelper.getFieldMeta('legals')

Con parametro restituisce il valore della chiave oggetto - secondo livello

window.FormioHelper.getFieldMeta('legals.privacy_info')

Esempio con array

  window.FormioHelper.getFieldMeta('topics[0].text')

In caso il filtro non trovi gli elementi restituirà false

Dal 12 dicembre 2023 le procedure previste dallo Sportello Unico Digitale devono essere rese disponibili interamente online sulla base del sistema tecnico per lo scambio transfrontaliero automatizzato di prove e l'applicazione del principio "una tantum" (OOTS – Once Only Technical System) previsto dal regolamento di esecuzione 2022/1463 della Commissione.

Ovvero deve essere prevista, per il cittadino, la possibilità di utilizzare dati di pratiche già inviati per la compilazione di nuove istanze.

É possibile attivare il principio once-only sulla piattaforma tramite l'utilizzo dei nested form all'interno del modulo del servizio. I nested form sono uno speciale componente selezionabile dall'amministratore durante la configurazione del servizio.

Una volta trascinato un nested form all'interno del modulo del servizio si aprirà l'interfaccia di configurazione del componente, l'amministratore potrà scegliere tra un set già preparato di nested form disponibili.

Per poter abilitare il principio once only su un nested form l'amministratore deve:

In fase di compilazione da parte del cittadino di una pratica con un nested form con la proprietà profile_block abilitata il dato contenuto nel componente verrà salvato nel profilo del cittadino oltre che all'interno della pratica.

In fase di compilazione dello stesso o di un qualsiasi altro servizio in cui è stato configurato un nested form con proprietà profile_block abilitata e con la stessa chiave il dato verrà automaticamente prepopolato da quello salvato precedentemente nel profilo del cittadino.

Un caso concreto: vogliamo bloccare l'invio di un bonus in ambito sociale, in modo che solo una famiglia possa fare richiesta.

Sarà indispensabile avere una base di dati o un'API da interrogare che ci da la chiave. Ipotiziamo che ci venga dato un file excel con i dati

Preparazione dei dati

Creiamo un JSON dal CSV, in modo che ogni riga del CSV diventi un oggetto di questo tipo:

{
"id": "SLVLNZxxxxxxxxx",
"famiglia": "1"
}

Si avvia un json-server per creare un'API su quei dati:

docker run -it [...] vimagick/json-server  /app/db.json --read-only 

Si testa con un client da CLI come httpie che è possibile interrogare l'API:

http get https://www2.stanzadelcittadino.it/comune-di-xxx/api/anagrafe/SLVLNZxxxxxxxxx

Ottenendo un risultato di questo tipo:

Preparazione della form

Usiamo un campo di nome unique_id per far si che solo un componente del nucleo familiare possa inviare la domanda.

Si aggiunge al form un campo di tipo Text fied che si popolerà con il valore del family code quando si inserisce nella form il campo Codice Fiscale:

Il valore del campo verrà calcolato in base a un piccolo script javascript da inserire nell'apposito campo Data -> Calculated Value

async function loadJSON(){
	response = await fetch(url, param)
	if (response.ok) {
		console.log('got successful from API')
		let responseData = await response.json()
		console.log("famiglia: " + responseData['famiglia'])
		if (!responseData.hasOwnProperty('famiglia')) {
			console.log('error: got empty response data:')
			console.log(responseData)
			console.log('error routine, setting not available value')
			instance.setValue('non disponibile')
		} else {
			console.log('got a non-null response Data')
			instance.setValue(responseData['famiglia'])
		}
	} else {
		console.log('error: got non 200 status code');
        console.log('error routine, setting not available value')
		instance.setValue('non disponibile')
	}
}

if (data.applicant.data.fiscal_code.data.fiscal_code.length == 16){
	let url = "/comune-di-xxxxx/api/anagrafe/" + data.applicant.data.fiscal_code.data.fiscal_code;
	let param = {
	  method: "get",
	  headers: {'Content-Type': 'application/json'}
	}
	loadJSON(url, param)
} else {
	console.log('not a valid value to perform api call')
	value = ""
}

Per validare il campo sarà necessaria una validazione in JS, per ottenere un controllo di questo tipo:

Validazione JS del campo

if (data.unique_id && data.unique_id !== "non disponibile") {
  valid = true
} else {
  valid = "Siamo spiacenti, il suo nucleo familiare non può beneficiare di questo servizio. Per maggiori informazioni contatti il Comune ai recapiti nel Box Informazioni presente in questa pagina."
}

Controllo univocità

Una volta abilitata l'integrazione con la PDND e configurati correttamente un client ed i relativi i e-services l'amministratore della piattaforma può abilitare un componente di tipo nested form all'utilizzo di una specifico e-services.

Per poter abilitare un nested form all'utilizzo di uno specifico e-service della PDND si deve:

Tabella di compatibilità dei nested form con e-services e formato

L'errore

Un errore che può capitare quando si fa l'editing dei servizi tramite il form builder è la comparsa di un "Unknown component", alla fine del form, prima dei pulsanti di invio/annulla.

Il bug

L'errore è dovuto a un bug dell'editor, si può correggere, ma non da interfaccia web.

Un form di form.io in stanza del cittadino è sempre di tipo wizard, ovvero fatto da N pagine.

Un form di tipo wizard DEVE avere sempre una struttura fatta da N panels, una per ogni pagina che vedete all'interno dell'editor:

{
"display": "wizard",
"type": "form",
"components": [
  {
     "title": "Richiedente",
     "type": "panel",
     ....
  },
  {
     "title": "Documenti",
     "type": "panel",
     ...
  },
  {
  {
     "title": "Consegna",
     "type": "panel",
     ...
  }
],
"_id": "61c58764fc3ee60017b98c21",
...
"__v": 11
}

Quando si verifica l'errore è perché sotto components c'e' qualcos'altro:

La soluzione

Per risolvere bisogna procedere in questo modo:

1. si prende l'ID del form mediante API: GET https://stanzadelcittadino.it/{tenant}/api/services/{service_id}

2. si prende il JSON del form da correggere: GET https://formserver.../form/{form_id}

3. si mette in un editor di testo e si toglie la parte contenente l'errore, ovvero si lasciano solo le componenti di tipo panel

4. si fa una PUT sul formserver con il JSON corretto:

 cat /tmp/form-corretto.json | http put https://formserver.../{service-name}

N.B: la PUT va fatta sullo slug del servizio, non è disponibile sull'ID del form.

In un modulo potrebbe essere necessario poter rendere modificabile un campo solo lato operatore. Per poter popolare o modificare un campo solo se si è operatori, bisogna aggiungere la proprietà operator_restricted con valore true navigando nella tab API sotto la voce Custom Properties

Aggiungere poi l'attributo readonly nel tab Layout sotto la voce HTML attributes con valore true.

Aggiungere un condizione personalizzata per renderlo invisibile agli utenti. Aggiungere nella tab Conditional sotto Advanced Conditions questo codice show = !instance.component.properties.hasOwnProperty('operator_restricted')

Con questa configurazione il cittadino non vedrà il campo, mentre resterà accessibile e modificabile agli operatori.