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

Best practices en valkuilen

Vooraf

Deze pagina bundelt de belangrijkste afspraken uit de pagina's over extensies en customizaties. Ze komen uit de praktijk van bestaande Skryv-applicaties. Gebruik de pagina als controlelijst bij het bouwen, bij een code review of bij een platformupgrade.

Werken met het platform

Afspraak

Waarom

Meer info

Gebruik alleen de publieke API van het platform, en declareer zelf de bibliotheken die je gebruikt.

Een klasse die alleen onrechtstreeks meekomt met een platformartefact, of een import uit een intern pad zoals .../src/..., kan bij een platformupgrade verdwijnen of verschuiven. Je code breekt dan zonder waarschuwing.

Backend-extensie bouwen

Wijzig een dossier via DossierService.update(dossier), niet rechtstreeks via de repository.

Alleen update() publiceert het event waarop de zoekindex het dossier bijwerkt. Via de repository staat de waarde wel in de database, maar niet in de zoekresultaten.

Backend-extensie bouwen

Vervang zo weinig mogelijk. Vervang je een pagina, val dan voor de andere dossiertypes terug op het standaardcomponent en geef alle bindings door.

Wie een standaardonderdeel vervangt, neemt de verantwoordelijkheid over voor alles wat het deed. De andere dossiertypes blijven zo de verbeteringen uit nieuwe platformversies krijgen.

Backoffice aanpassen

Namen en keys

Afspraak

Waarom

Meer info

Geef beans, componenten en eigen formuliercomponenten een prefix van je applicatie.

Platformcomponenten beginnen met skr. Met een eigen prefix zie je meteen wat van het platform komt en wat van de applicatie.

Eigen formuliercomponenten

Behandel de naam van een bean of een formuliercomponent als een contract.

De BPMN verwijst naar de beannaam, de formulierdefinitie naar de componentnaam. Hernoem je in de code, pas dan ook elke verwijzing aan.

Extensie aanroepen vanuit de workflow

Bundel keys uit de configuratie, zoals die van dossiertypes, documenten en mijlpalen, in één bestand met constanten.

Code die naar een key verwijst, werkt niet meer als de key in Skryv Studio hernoemd wordt. Op één plek zie je meteen welke keys de code gebruikt.

Backoffice aanpassen

Geef elementen waarnaar code verwijst een betekenisvolle key, niet de ID die de BPMN-editor automatisch toekent.

Een automatische ID zoals Event_0wgv5np zegt niets over het element, en wordt makkelijk gewijzigd zonder dat iemand de code nakijkt.

Backoffice aanpassen

Configuratie en externe diensten

Afspraak

Waarom

Meer info

Haal URL's, tokens en cron-expressies uit eigenschappen, nooit uit de code.

Zo stel je ze per omgeving in. Geheimen worden per omgeving gezet, bijvoorbeeld via omgevingsvariabelen.

Backend-extensie bouwen

Test lokaal tegen een stub van een externe dienst door de URL-eigenschap te wijzigen. Pas de connector zelf nooit aan.

Een aangepaste connector kan per ongeluk mee naar productie gaan, en dan spreekt productie een nepdienst aan.

Backend-extensie bouwen

Roep een externe dienst vanuit de workflow asynchroon aan, met retries.

Met camunda:asyncBefore="true" en een failedJobRetryTimeCycle probeert de engine een mislukte aanroep opnieuw, in plaats van de stap meteen te laten falen.

Extensie aanroepen vanuit de workflow

Behandel elke mislukte aanroep als een fout, ook zonder herkenbare foutcode.

Een time-out van een gateway geeft bijvoorbeeld een HTML-pagina terug. Behandel je dat als een geldig antwoord, dan toon je de gebruiker een verkeerde inhoudelijke conclusie.

Eigen formuliercomponenten

Workflow en expressies

Afspraak

Waarom

Meer info

Gebruik in expressies alleen rechte aanhalingstekens.

Typografische aanhalingstekens geven een fout bij het uitvoeren. Ze sluipen er vaak in bij kopiëren uit een tekstverwerker of webpagina.

Extensie aanroepen vanuit de workflow

Zet een execution listener die een variabele klaarzet, vóór het inputOutput-blok dat die variabele gebruikt.

Beide worden uitgevoerd in de volgorde waarin ze in de XML staan.

Extensie aanroepen vanuit de workflow

Gebruikers en rollen

Afspraak

Waarom

Meer info

Kies de claim die de identiteit van een gebruiker bepaalt bij de start van een project, en wijzig ze nadien alleen met een migratie.

Het platform herkent een gebruiker aan die identiteit, onder meer bij toegewezen taken en de dossierbehandelaar. Een andere claim maakt van dezelfde persoon een nieuwe gebruiker.

Platformgedrag overschrijven

Geplande taken en onderhoudstaken

Afspraak

Waarom

Meer info

Geef bij een geplande taak de tijdzone expliciet mee.

Zonder tijdzone geldt die van de server.

Geplande taken en onderhoudstaken

Overschrijf geen goede gegevens met een leeg antwoord.

Geeft een externe bron niets terug, sla de update dan over en log een fout, in plaats van bijvoorbeeld een referentielijst leeg te maken.

Geplande taken en onderhoudstaken

Bouw een onderhoudstaak idempotent, met eerst een dry-run, asynchroon en met maximaal één uitvoering tegelijk.

Een onderhoudstaak raakt vaak alle dossiers. Zo kun je ze veilig testen en herhalen, en overschrijdt ze geen time-out.

Geplande taken en onderhoudstaken

Eigen formuliercomponenten

Afspraak

Waarom

Meer info

Controleer een veld dat niet in elk formulier voorkomt, voor je het gebruikt.

Ontbreekt een veld dat het component verwacht, dan faalt het component bij het openen van het formulier.

Eigen formuliercomponenten

Maak afgeleide velden leeg voor je nieuwe gegevens ophaalt.

Zo blijft er geen verouderde waarde staan als het ophalen mislukt.

Eigen formuliercomponenten

Testen

Afspraak

Waarom

Meer info

Schrijf bij een bugfix eerst een test die de fout reproduceert, en los de fout daarna op.

De test moet groen worden zonder dat je hem aanpast. Zo weet je dat de fix het probleem echt oplost.

—

Kies een testaanpak die past bij wat je test.

Bestaande applicaties gebruiken de testhulp van het platform (skryv-backend-test-util), stubs van externe diensten via MockServer, integratietests met Testcontainers, en snapshottests voor frontendcomponenten.

Backend-extensie bouwen

Bij een platformupgrade

Afspraak

Waarom

Upgrade stap voor stap, niet over veel versies tegelijk.

Elke stap isoleert een beperkte set wijzigingen, zodat je weet waar een fout vandaan komt.

Bouw de applicatie meteen na het wijzigen van skryv.version, voor je zelf naar wijzigingen zoekt.

Veel upgrades verlopen zonder problemen, en de buildfouten tonen precies wat er aangepast moet worden.

Controleer of spring.boot.version overeenkomt met de versie die de nieuwe platformversie verwacht.

Die versie staat in de pom van de platform-BOM. Een afwijkende versie geeft fouten bij het bouwen of uitvoeren.

Zet de versie van maven-antrun-plugin expliciet in de pom's van de frontends.

Zonder versie gebruikt Maven een oude versie die de compilatiestappen stilzwijgend overslaat.

Controleer de bindings van vervangen componenten, en werk snapshottests bij.

Een nieuwe platformversie kan een binding verplicht maken of extra gegevens ophalen.

Raadpleeg bij elke upgrade de release notes.