formio-sdk

Node/browser helper utilities for Form.io APIs.

Install

npm install formio-sdk

Quick start (Node)

const { FormioHelper } = require("formio-sdk");

const helper = new FormioHelper({
  baseUrl: "https://servizi.example.it/lang",
  token: process.env.AUTH_TOKEN,
  locale: "it",
  siteUrl: "https://servizi.example.it",
  applicationId: "12345"
});

async function run() {
  const tenant = await helper.getTenantInfo();
  console.log("tenant:", tenant);

  const profile = await helper.authenticatedCall("users/me");
  console.log("profile:", profile);
}

run().catch(console.error);

API notes

• getFieldApplication(getParams, applicationId) : in Node pass applicationId as argument or constructor option.
• getFieldMeta(getParams) : returns parsed tenant meta (or nested key via lodash path).
• authenticatedCall, authenticatedPOSTCall, authenticatedRequest : return undefined when token is missing (same behavior as original helper).

Constructor options

• baseUrl: Formio backend base URL.
• token: auth token string (or function returning token).
• locale: locale string (defaults to it).
• siteUrl: optional site URL used by getBookingConfig.
• applicationId: fallback id used by getFieldApplication.
• origin: base origin for relative URLs in addLimitParam.
• storage: custom storage adapter (getItem) to read auth-token.
• httpClient: custom axios-like client.
• logger: custom logger with error/warn methods.
• getBaseUrl, getCurrentToken, getCurrentLocale, getSiteUrl : override functions for full control.

Profile block (prefill PDND + fallback once-only)

applyProfileBlocks(formInstance, fiscalCode, options) scansiona un'istanza Form.io alla ricerca di componenti "profile block" e li pre-compila usando la PDND (se l'e-service collegato è attivo) oppure, in fallback, con i dati once-only salvati in precedenza dall'utente.

await helper.applyProfileBlocks(formInstance, fiscalCodeRichiedente, {
  serviceId: "df15f3d4-f800-41e3-81a3-2a4d6fef5d1c", // usato per caricare services/{serviceId}/pdnd-configs
  userId: currentUser.id, // omesso/undefined per utenti anonimi (disabilita il once-only)
});

Ritorna un Array<{ data: object }> da unire alla submission (es. tramite formInstance.setValue), e inoltre emette formInstance.emit("sdkProfileBlockData", { data }) per ogni risultato — resta in ascolto di questo evento per ricevere anche i dati che arrivano più tardi (vedi "Profile block condizionali" più sotto), non solo il valore di ritorno della chiamata iniziale:

formInstance.on("sdkProfileBlockData", ({ data }) => {
  // unisci `data` allo stato del form / alla submission
});

Come abilitare un componente come profile block

Sul componente nested-form ("Form") nel builder di Form.io, in API → Custom Properties, imposta:

• profile_block: true
• trusted_prefill: true

Entrambi i booleani sono accettati anche come stringa "true", perché il widget Custom Properties del builder salva sempre i valori come stringa.

Dentro il sotto-form di quel componente:

• Il primo componente del sotto-form deve avere properties.eservice (l'id dell'e-service PDND) e, opzionalmente, properties.format (default "default").
• Ogni campo che deve essere marcato/disabilitato quando arrivano i dati PDND necessita di properties.pdnd_field: true.

Profile block condizionali

Un profile block può essere mostrato/nascosto con una normale conditional (o customConditional) di Form.io — non serve nessuna proprietà speciale. applyProfileBlocks elabora solo i componenti attualmente visibili (component.visible !== false); un componente senza alcuna conditional è sempre visibile, quindi i profile block incondizionati continuano a funzionare esattamente come prima.

Poiché una conditional può cambiare la visibilità anche nello stesso step (senza navigazione tra pagine), applyProfileBlocks registra anche un unico watcher debounced (~350ms) su formInstance.on("change", ...) per ogni istanza di form, che ri-scansiona i profile block appena diventati visibili e non ancora processati, emettendo sdkProfileBlockData per ciascuno che risolve. Non serve richiamare applyProfileBlocks manualmente per gestire questo caso.

Limite noto: component.visible riflette solo la conditional del componente stesso — non viene forzato a false solo perché un antenato (panel/fieldset) è nascosto da una sua conditional.

Usare un codice fiscale diverso per ogni profile block

Di default ogni profile block viene interrogato usando l'argomento fiscalCode passato ad applyProfileBlocks (tipicamente quello del richiedente). Un profile block relativo a un altro soggetto (es. il coniuge) di solito ha bisogno del proprio codice fiscale. Va abilitato esplicitamente con properties.fiscal_code_path sul componente profile block stesso — un path lodash get risolto contro il getValue() di quel componente:

{
  "type": "form",
  "key": "spouse",
  "properties": {
    "profile_block": true,
    "trusted_prefill": true,
    "fiscal_code_path": "data.tax_id"
  }
}

Il path è relativo alla forma prodotta dai campi di quel componente — es. "data.tax_id" per un campo piatto con key tax_id, oppure "data.fiscal_code.data.fiscal_code" se il codice fiscale arriva da un sotto-componente/nested-form con key fiscal_code.

Non esiste un path di default implicito: se fiscal_code_path non è impostato, il profile block usa sempre il fiscalCode globale. Se è impostato ma risolve a un valore vuoto (l'utente non l'ha ancora compilato), il componente viene considerato non pronto — non parte nessuna chiamata, e non viene marcato come processato, quindi verrà ritentato automaticamente (tramite lo stesso watcher debounced su change usato per la visibilità condizionale) non appena il campo verrà compilato. Questo evita che si faccia mai fallback silenziosamente sul codice fiscale del soggetto sbagliato.