Regole generali

L'integrazione con form.io ha reso molto flessibile la creazione di servizi, consentendo a un amministratore di creare in completa autonomia un servizio digitale e metterlo online in poche ore.

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:

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";
}

Vedi anche controlli avanzati sulle date

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

Attenzione, questo componente è stato deprecato e non va più utilizzato.

Per la configurazione del componente file SDC fare riferimento al paragrafo successivo.

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

Attualmente i tipi di allegato permessi sono i seguenti: doc, docx, odt, pdf, xls, xlsx, ods, ppt, pptx, odp, csv, xml, rtf, abw, txt, jpeg, jpg, png, apng, webp, ico, gif, p7, p7m, xp7m, p7c, zip. Di cui viene controllata sia l'estensione che il MIME type. Quando si va a configurare i tipi di estensioni permesse dal componente, è possibile solo restringere questa lista. Se si dovesse aggiungere tra le estensioni permesse dal componente una estensione differente da quelle sopra elencate, non sarà comunque accettata dal sistema e verrà restituito un errore da interfaccia con la lista delle estensioni permesse di cui sopra.

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.

Il campo unique_id deve contenere SOLO caratteri ASCII, ovvero le lettere a-z (maiuscole o minuscole) e le cifre 0-9

Pagamento con Bilancio PagoPA - Versione 1 (Mypay)

Attenzione, questo componente è stato deprecato e non va più utilizzato.

Per la configurazione del bilancio dinamico fare riferimento al paragrafo successivo.

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.

if (data.tipologia === 'value') {
 	value = [
 		{codAccertamento: "", codCapitolo: "cap1", codUfficio: "uff1", importo: "2"},
 		{codAccertamento: "", codCapitolo: "cap2", codUfficio: "uff2", importo: "8"}
 	];
 } else {
 	value = [
 		{codAccertamento: "", codCapitolo: "cap1", codUfficio: "uff1", importo: "5"},
 		{codAccertamento: "", codCapitolo: "cap2", codUfficio: "uff2", importo: "5"}
 	];
 }

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

L'elenco completo delle integrazioni che supportano o meno il bilancio si trova in questa pagina.

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

if (data.lost === true) {
  value = {
    "c_1": "0.25",
    "c_2": "10.32",
    "c_3": "16.79",
  }
} else {
  value = {
    "c_1": "0.25",
    "c_2": "5.16",
    "c_3": "16.79",
  }
}

Esempio

Configurazione del bilancio nel tab dei pagamenti di un servizio

Codice javascript da inserire nel calculated value del campo payment_financial_report

if (data.lost === true) {
  value = {
    "c_1": "0.25",
    "c_2": "10.32",
    "c_3": "16.79",
  }
} else {
  value = {
    "c_1": "0.25",
    "c_2": "5.16",
    "c_3": "16.79",
  }
}

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):

var field = document.querySelector("input[name^='data[<field>]']");
if (<old_field>) {
  <new_field>> = <old_field>
  field.value = <old_field>
}

Es:
var stamp = document.querySelector("input[name^='data[stamp]']");
if (data.applicant1 && data.applicant1.data.stamp) {
  data.stamp.data.stamp = data.applicant1.data.stamp
  stamp.value = data.applicant1.data.stamp
}

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