Use case
Een lookupveld in een formulier haalt zijn opties op bij een lookup source: een stukje Java-code in de backend van de applicatie, dat weet waar de opties vandaan komen. Sommige connectoren leveren lookup sources mee, zoals de notulen-connector. Heb je opties nodig uit een systeem waarvoor nog geen lookup source bestaat? Dan schrijf je er zelf eentje via deze handleiding.
Een lookup source hoort in de back-endmodule van de applicatie, naast de andere code die met externe systemen praat. Of in de connector zelf, als je die schrijft. Het is weinig code, maar ze doorloopt een review en een release, net als alle andere code.
In principe kan je om het even waar in de back-end een lookup source toevoegen, maar de belangrijkste use case zien wij weggelegd voor connectoren die de link leggen met externe bronnen of systemen.
Vooraf
-
De backend van je applicatie heeft
skryv-backend-coreals dependency. Dat is bij elke Skryv-applicatie het geval. De interfaceLookupSourcekomt daarmee mee, en je hebt geen extra dependency nodig. -
Je hebt een manier om het externe systeem aan te spreken, bijvoorbeeld een REST-client of een bestaande connector.
Stappen
Stap 1: maak een klasse die LookupSource implementeert
Een lookup source is een Spring bean: een klasse met @Component die com.skryv.backend.lookup.LookupSource implementeert. Je hoeft ze nergens te registreren. Spring vindt de bean vanzelf, en het platform zoekt de lookup source op via haar naam.
De interface vraagt twee methodes:
package com.skryv.backend.lookup;
public interface LookupSource {
/**
* Must be unique across the application.
*/
String name();
/**
* @param params the query parameters of the request, so user input: validate them, and never let them widen what
* the dossier gives access to. Throw {@link InvalidLookupParamsException} when they are not valid.
*/
List<LookupOption> fetch(String dossierId, Map<String, String> params);
}
Stap 2: Kies een naam
name() geeft de naam terug die een configurator invult in "lookupSource" in de formulierdefinitie. De naam moet uniek zijn in de hele applicatie. Twee lookup sources met dezelfde naam laten de applicatie niet starten.
Kies een naam met een prefix voor het systeem, zodat hij herkenbaar blijft naast de lookup sources van andere connectoren. Zo heten de lookup sources van de notulen-connector notulenMeetings, notulenDepartments, enzovoort.
Stap 3: Zet elk resultaat om naar een LookupOption
fetch geeft een lijst van LookupOption terug. Een optie heeft drie delen:
public record LookupOption(String key, String label, Map<String, Object> data) { }
|
Deel |
Wat erin hoort |
|---|---|
|
|
Identificeert de optie in het externe systeem. Wordt voor altijd in het document bewaard. Maak hem stabiel: een sleutel die verandert, maakt elk eerder gegeven antwoord “niet meer beschikbaar”. |
|
|
De tekst in de keuzelijst. De gebruiker kiest alleen hierop, dus het label moet zonder context herkenbaar zijn, en mag niet veranderen voor een optie die dezelfde bleef. |
|
|
Alles wat verder nuttig is: de gegevens die een template, een mapping, een formulierexpressie of een workflowfunctie nodig kan hebben. Dit wordt mee bewaard bij het antwoord. Neem dus op wat nuttig is, en laat de rest weg. |
Een paar praktische regels, uit de lookup sources van de notulen-connector:
-
Geen
Map.ofals een waarde leeg kan zijn.Map.ofweigertnull. Gebruik eenHashMapals het externe systeem een veld kan weglaten. -
Een label mag nooit leeg zijn. Valt het externe veld soms weg, voorzie dan een terugvalwaarde, bijvoorbeeld de sleutel.
-
Datums en tijden als tekst in ISO-formaat. Zo leest een formulierexpressie of een workflow ze eenduidig uit.
Stap 4: Lees en valideer de parameters
Wat een formulier meestuurt via params of paramsWith, komt binnen in de map params. Dat is invoer van de gebruiker, over HTTP. Twee regels:
-
Valideer de parameters. Heeft je lookup source een parameter nodig, zeg dat dan in plaats van te gokken. Gooi een
InvalidLookupParamsException, en de oproeper krijgt een 400. Het veld meldt dan dat de opties niet geladen konden worden. Heb je meerdere lookup sources met dezelfde parameters, bundel het inlezen dan in één hulpklasse. De notulen-connector doet dat metLookupParams. -
Een parameter mag nooit uitbreiden wat het dossier mag zien. Het endpoint controleert alleen dat de gebruiker dit dossier mag lezen. Hangt wat de opties mogen tonen af van het dossier, leid dat dan af uit
dossierId, niet uit iets wat het formulier meestuurde.
dossierId is het dossier waartoe het formulier behoort. Het parameter is er net voor: alleen ophalen wat dit dossier mag zien.
Stap 5: Bescherm de gebruiker tegen een traag systeem
fetch loopt op de request-thread, en de gebruiker kijkt naar een laadindicator zolang het duurt.
-
Stel zelf timeouts in op elke call naar buiten. Zonder timeout houdt een traag systeem de request open tot de browser opgeeft, en blijft het veld in de laadtoestand hangen.
-
Overweeg een cache. Elke keer dat een formulier opent, vraagt het veld de opties opnieuw op. Voor lijsten die zelden veranderen, loont een cache. De notulen-connector cachet elke lijst per combinatie van parameters, met een instelbare ttl per lijst, en bewaart een mislukte call niet.
Voorbeeld
Een lookup source die de zalen van een fictief reservatiesysteem aanbiedt, gefilterd op een verplichte parameter locatieId:
@Component
@RequiredArgsConstructor
public class ZalenLookupSource implements LookupSource {
private final ZaalClient zaalClient; // je eigen client naar het externe systeem, met timeouts
@Override
public String name() {
return "reservatieZalen";
}
@Override
public List<LookupOption> fetch(String dossierId, Map<String, String> params) {
String locatieId = params.get("locatieId");
if (StringUtils.isBlank(locatieId)) {
throw new InvalidLookupParamsException("Expected the parameter locatieId, but got none");
}
return zaalClient.getZalen(locatieId).stream()
.map(ZalenLookupSource::toOption)
.toList();
}
private static LookupOption toOption(Zaal zaal) {
Map<String, Object> data = new HashMap<>(); // geen Map.of: capaciteit kan ontbreken
data.put("id", zaal.id());
data.put("naam", zaal.naam());
data.put("capaciteit", zaal.capaciteit());
return new LookupOption(zaal.id(), StringUtils.defaultIfBlank(zaal.naam(), zaal.id()), data);
}
}
In de formulierdefinitie gebruikt een configurator ze zo:
{
"name": "zaal",
"label": "Zaal",
"type": "lookup",
"required": true,
"lookupSource": "reservatieZalen",
"params": { "locatieId": "torhout" }
}
Een volledig uitgewerkt voorbeeld met zeven lookup sources, afhankelijke parameters en caching vind je in de notulen-connector.
Wat er kan mislopen
|
Situatie |
Gevolg |
|---|---|
|
Twee lookup sources geven dezelfde |
De applicatie start niet. |
|
|
404. Het veld meldt dat de opties niet geladen konden worden. |
|
|
400. Het veld meldt dat de opties niet geladen konden worden. |
|
|
Het platform vangt ze op en logt ze. Het veld meldt dat de opties niet geladen konden worden. |
|
|
Het veld blijft in de laadtoestand tot de browser opgeeft. |