Vooraf
Een backend-extensie is Java-code die je toevoegt aan de back-end van je applicatie, bijvoorbeeld een eigen service die je vanuit een workflow aanroept. Welke soorten backend-extensies er zijn, lees je in het Overzicht uitbreidingspunten. Deze pagina beschrijft wat ze allemaal gemeen hebben.
Je hebt nodig:
-
een applicatie die lokaal draait, zie Lokale setup
-
basiskennis van Java en Spring Boot
Je werkt in de module backend van je applicatie, of in een eigen module. Waar die modules staan, lees je op Opbouw van een Skryv applicatie.
Stap 1: maak de klasse aan
Een backend-extensie is een gewone Spring bean. Je maakt een klasse aan, annoteert ze met @Service en geeft ze een expliciete naam. Die naam gebruik je later om de extensie vanuit een workflow aan te spreken.
@Service("mijnappSubsidieService")
@RequiredArgsConstructor
@Slf4j
public class SubsidieService {
private final DossierService dossierService;
private final Skryv skryv;
public void berekenBedrag(String dossierId) {
// jouw logica
}
}
Enkele afspraken:
-
Kies een beannaam met een prefix van je applicatie, zoals
mijnappSubsidieService. Een algemene naam zoalsconnectorServiceoforafinkan botsen met een bean van het platform. -
Gebruik constructor injection. Met Lombok volstaat
@RequiredArgsConstructorenfinalvelden. Je kunt de constructor ook zelf schrijven. -
Lombok is optioneel, maar wordt in de meeste applicaties gebruikt. Veel applicaties zetten in een
lombok.configde naam van de logger opLOGGER. Daarom zie je in bestaande codeLOGGER.info(...)in plaats vanlog.info(...).
Stap 2: gebruik de services van het platform
Je extensie werkt met dossiers en documenten via de publieke API van het platform, die in skryv-backend-core zit. Je injecteert de nodige services in de constructor.
De fluent API Skryv is dezelfde API die je in expressies gebruikt. Wie expressies kent, herkent de werkwijze:
// een veld in een document invullen
skryv.dossier(dossierId)
.getDocumentByDefinitionKey("mijnDocument")
.setField("bedrag", 1250.0);
// een document inlezen als Java-object
MijnDocument document = skryv.dossier(dossierId)
.getOrCreateDocumentByDefinitionKey("mijnDocument")
.getRawDocumentValueAs(MijnDocument.class);
Andere services die je vaak nodig hebt, zijn DossierService voor dossiers en DocumentService voor documenten.
-
Wijzig een dossier altijd via
DossierService.update(dossier), niet rechtstreeks via de repository. Alleenupdate()publiceert het event waarop de zoekindex het dossier bijwerkt. Schrijf je via de repository, dan staat de nieuwe waarde wel in de database, maar niet in de zoekindex. Ze verschijnt dan bijvoorbeeld niet in de zoekresultaten van de backoffice. -
Gebruik alleen klassen uit de publieke API van het platform en uit bibliotheken die je zelf als dependency opneemt. Een klasse die enkel onrechtstreeks meekomt met een platformartefact, kan bij een platformupgrade verdwijnen. Je code compileert dan niet meer.
Stap 3: lees configuratie in
Waarden die per omgeving verschillen, zoals URL's, tokens, cron-expressies of een schakelaar om functionaliteit aan of uit te zetten, horen niet in de code. Je leest ze in als eigenschap:
@Value("${mijnapp.extern.url}")
private String externeUrl;
@Value("${mijnapp.berekening.enabled:true}")
private boolean berekeningEnabled;
Na de dubbelepunt kun je een standaardwaarde opgeven.
Zet secrets zoals tokens en wachtwoorden nooit in de code of in een eigenschappenbestand in de repository. Ze worden per omgeving ingesteld, bijvoorbeeld via omgevingsvariabelen.
Zet je functionaliteit uit met een schakelaar, laat de extensie dan duidelijk loggen dat ze niets doet. Geef geen fictieve waarde terug alsof de berekening gelukt is: zo'n stille terugval valt pas op wanneer een dossier al verkeerd behandeld is.
Stap 4: spreek de extensie aan
Je extensie is nu beschikbaar als bean in de applicatie. Hoe je ze vanuit een workflow aanroept, lees je op Extensie aanroepen vanuit de workflow. Andere extensies kunnen ze gewoon injecteren in hun constructor.
Stap 5: test je extensie
Schrijf tests in de module backend, zoals je dat in elk Spring Boot-project doet, met JUnit. Het platform levert daarvoor hulpmiddelen in het artefact com.skryv.backend:skryv-backend-test-util, dat je met scope test opneemt.
Je voert de tests van de back-end uit met:
mvn test -pl backend
Sommige applicaties draaien ook integratietests tegen echte services in een container, bijvoorbeeld met Testcontainers, of simuleren externe diensten met een stub. Pas in dat geval nooit de connector zelf aan om naar de stub te wijzen: laat de URL uit een eigenschap komen, zodat je ze per omgeving kunt instellen.
Resultaat
Je extensie draait als Spring bean in je applicatie. Ze gebruikt de services van het platform, haalt haar instellingen uit de configuratie en is gedekt door tests.
Je kunt je extra functionaliteit nu aanroepen vanuit een workflow of vanuit andere code.