JSON Schema koppelen

Elke formulier heeft een JSON Schema nodig om te bepalen welke velden er in het output formaat moet komen te staan. Een JSON Schema laat ook toe structuur te brengen in de JSON die anders is dan de structuur van het formulier. Daarnaast laat het JSON Schema ook toe om velden een andere naam te geven in de output JSON tegenover de veldnamen in het formulier.

Er zijn 3 manieren om een JSON Schema te koppelen aan een formulier:

Genereer een JSON Schema van alle velden in een formulier en leg een automatische referentie naar alle velden (lees “Automatisch” hieronder)
Genereer een JSON Schema van alle velden in een formulier (lees “Automatisch” hieronder) en koppel de velden manueel (lees “manueel” hieronder vanaf stap 4)
Creëer manueel een JSON Schema en koppel de velden manueel (lees “manueel” hieronder)

Het is natuurlijk ook mogelijk om het JSON Schema te downloaden, aan te passen, opnieuw te uploaden en dan pas de manuele koppeling te doen. (Zie Output formaat bepalen hieronder voor meer uitleg)

Om een json schema te downloaden uit AEM, kies ‘download assets(s) as binary files’. Deze file kan dan geopend en geëditeerd worden in een json editor (bijvoorbeeld notepad++.)

Automatisch

Open je formulier
Open het pagina menu linksboven en kies je juiste optie
1. Selecteer “Genereer formulier schema“
  1. Deze optie gaat enkel je JSON Schema genereren,
  2. het JSON Schema wordt naast je formulier geplaatst,
  3. bevat de datum en uur van generatie,
  4. en is niet gekoppeld aan je formulier
  5. (je kan dan verdergaan met Stap 3 in Manueel hieronder, of een aanpassing doen aan je JSON Schema)
2. Selecteer “Genereer en bind formulier schema”
  1. Identiek dezelfde stappen als “Genereer formulier schema”
  2. maar elk JSON veld wordt automatisch gekoppeld aan elk formulier veld

Bij de eigenschappen van elk formulier veld, kan je ook aangeven of je dat veld niet in het JSON Schema wil.

Manueel

Maak een JSON Schema (zie output formaat bepalen hieronder)
1. de bestandsnaam eindigt op .schema.json
2. Aanbevolen is het om de naam van je formulier te geven
Upload dit JSON Schema en zet het naast je formulier (is geen verplichting, maar wel handiger)
Koppel het JSON Schema aan het formulier
1. Open de Page Properties van een formulier
2. Open de Form Model tab
3. Selecteer Schema in het ‘Select Form’ veld
4. Selecteer je geüploade JSON Schema
Koppel nu elk JSON Schema veld aan elk formulier veld dat je wil zien in de output JSON
1. Selecteer een formulier veld
2. Open de Eigenschappen van dat veld
3. Ga naar “Referentie koppeling”
4. Klik op het icoon achteraan dit veld
5. Selecteer uit je JSON Schema het juiste veld waaraan dit formulier veld gekoppeld wordt
Herhaal deze laatste stap per formulier veld dat je wil mappen in je output JSON. Bekijk output formaat bepalen om meer te weten te komen hoe om te gaan met verschillende type velden.

Debuggen

Open je formulier in een modus dat je het in kan vullen. Vul het al dan niet in om je data al dan niet in de output JSON te zien.

Momenteel (vrij technisch) is er een script beschikbaar dat in de browser console kan worden geplakt en uitgevoerd.

Dit geeft weer welke de bound velden zijn en unbound velden.

Enkel bound velden worden gebruikt, de unbound velden worden genegeerd.
Tenzij er geen bound velden zijn, worden de unbound velden gebruikt.

function parseXmlToJson(xml) {
    const json = {};
    for (const res of xml.matchAll(/(?:<(\w*)(?:\s[^>]*)*>)((?:(?!<\1).)*)(?:<\/\1>)|<(\w*)(?:\s*)*\/>/gm)) {
        const key = res[1] || res[3];
        const value = res[2] && parseXmlToJson(res[2]);
        json[key] = ((value && Object.keys(value).length) ? value : res[2]) || null;

    }
    return json;
}

guideBridge.getDataXML({
   success: function(guideResultObject) {
      var data = guideResultObject.data;
      var json = undefined;
      if (data.startsWith('<')) {
        json = parseXmlToJson(data);
		console.log('XML was found');
      } else {
        json = JSON.parse(data);
		console.log('JSON was found');
      }

      if (json !== undefined) {
        var boundData = json.afData.afBoundData;
        var unboundData = json.afData.afUnboundData;

        console.log("Full JSON", json);

        console.log("Bound data", boundData);
        console.log("Unbound data", unboundData);
        
        console.log("Also copied to clipboard");
        copy(data);
      } else {
          console.log("Could not parse data", data);
      }
   }
});

Output formaat bepalen

Dit deel gaat over het beïnvloeden en de mogelijkheden binnen een JSON Schema. Maar ook wat er standaard uit een gegenereerd JSON Schema komt.

Als je geen kennis van JSON Schema hebt, is het eenvoudigste te kiezen om eentje te genereren en aan te passen.

Simpel voorbeeld

Formulier:

JSON Schema (dat werd gegenereerd):

{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "$id":"http://example.com/form_data.schema.json",
   "title":"Json schema for /vlaamse-overheid/demo-2/test-routering",
   "type":"object",
   "properties":{
      "textbox_voornaam":{
         "type":"string"
      },
      "textbox_naam":{
         "type":"string"
      },
      "dropdownlist1637886097279":{
         "type":"string"
      },
      "textbox_bijkomende_info":{
         "type":"string"
      }
   },
   "required":[
      "textbox_naam",
      "textbox_voornaam",
      "dropdownlist1637886097279",
      "textbox_bijkomende_info"
   ]
}

JSON output:

{
  "textbox_voornaam": "Sarah",
  "textbox_naam": "Janssens",
  "dropdownlist1637886097279": "1",
  "textbox_bijkomende_info": ""
}

Complex voorbeeld

JSON Schema:

JSON output:

Andere JSON Schema details

Ik wil mijn optionele velden wel of niet in de JSON output als ze leeg werden gelaten?

Dit wordt gecontroleerd door de “required” optie in het JSON Schema. Als je veld naam vermeld staat in bij “required”, zal het leeg worden doorgestuurd indien niet ingevuld. Als je de veld naam niet vermeld bij “required” en het word niet ingevuld door de gebruiker, dan zal het veld helemaal niet vermeld worden in de JSON output.

De automatische generatie zet alle velden als “required” waardoor elk niet ingevuld veld, toch meegestuurd wordt.

Ik wil enkele velden nesten in mijn output JSON?

Aan de formulier kant kan je velden groeperen door panels te gebruiken. Tijdens de automatische generatie van het JSON Schema, worden de panels gebruikt om ook inde output JSON voor een genest structuur te zorgen.

Dit JSON Schema moet gebruikt worden om de nesting te bepalen (let op “persoon”):

Hoe worden bijlagen verwerkt in de output JSON?

Afhankelijk van de een enkele bijlage of meerdere bijlages, zal de output JSON er anders uitzien.

“bijlage-single” of “bijlage-multi” zijn namen die instelbaar zijn in het JSON Schema. Maar de veldnamen “fileName”, “fileContent” en “contentType” zijn niet instelbaar en komen altijd zo mee. “fileContent” bevat een base64 versie van de bijlage.

Hoe kan ik velden niet doorsturen?

Als je geen “referentie koppeling” op de eigenschappen van een veld definieert, zal de ingevulde data in dat veld bij “unbound” JSON terecht komen en geen deel uitmaken van de output JSON. (tenzij er enkel unbound data is)

Als je JSON Schema werd gegeneerd en automatisch gekoppeld, kan je dit oplossen door naar de eigenschappen van dat veld (dat je niet meer wil doorsturen) te gaan en daar de referentie koppeling verwijderen.

Hoe kan ik een veldwaarde samenvoegen?

Velden samenvoegen kan door een hidden field te gebruiken. In het hidden veld kunnen dan bijvoorbeeld dag, maand en jaar aan elkaar geplakt worden, terwijl dit toch 3 velden zijn aan de formulier kant. Door dan deze 3 velden geen referentie koppeling te geven, worden deze niet meer doorgestuurd. Door dan het ene hidden field wel een referentie koppeling te geven, kan je enkel de samengevoegde data laten deel uitmaken van de output JSON.

Een andere use case is 2 velden waar er maar 1 van ingevuld kan worden aan de formulier kant door de gebruiker. En de output JSON ook maar 1 JSON veld wil ontvangen. Door een hidden veld te gebruiken met waarde van veld 1 of veld 2 (afhankelijk welk was ingevuld), en dit hidden veld enkel een referentie koppeling te geven, kan deze data ook samengevoegd worden.

Hoe ziet een repeatable panel eruit in de JSON output?

Een repeatable panel is een formulier veld waar de gebruiker zelf meerdere velden kan doen verschijnen of verwijderen.

Het JSON Schema bevat een array definitie voor “enqVervoer”:

Dit resulteert in deze JSON:

Hoe om te gaan met conditionele panels?

Een conditional panel verschijnt bij het selecteren van een optie (bijvoorbeeld ja) en verdwijnt bij het selecteren van een andere optie (bijvoorbeeld nee). Dit conditionele panel bevat extra velden die dus wel of niet tonen. Moest je de de velden invullen, maar daarna weer voor “nee” kiezen, zullen deze velden toch doorgestuurd worden.

Daarom moet de formulier bouwer een regel implementeren op het formulier bij het aanduiden van “nee”, om de eventuele conditioneel ingevulde velden weer leeg te maken.

Welke velden hebben nog een niet te wijzigen output?

Het voorwaarden component heeft maar 1 in te stellen JSON veld naam, “voorwaarden” in dit voorbeeld. De reviewDocment en reviewStatus komen automatisch in de JSON output en kan niet worden aangepast vanuit het JSON Schema.

Documentatie voor partners en klanten van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Met JSON-output werken