Working version v32.1.X v32.0.X v29.1.X
Working version v32.1.X v32.0.X v29.1.X Dutch

Back-end extensie bouwen

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.

Java
@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 zoals connectorService of orafin kan botsen met een bean van het platform.

  • Gebruik constructor injection. Met Lombok volstaat @RequiredArgsConstructor en final velden. Je kunt de constructor ook zelf schrijven.

  • Lombok is optioneel, maar wordt in de meeste applicaties gebruikt. Veel applicaties zetten in een lombok.config de naam van de logger op LOGGER. Daarom zie je in bestaande code LOGGER.info(...) in plaats van log.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:

Java
// 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. Alleen update() 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:

Java
@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:

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