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 |
|
|
Wijzig een dossier via |
Alleen |
|
|
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. |
Namen en keys
|
Afspraak |
Waarom |
Meer info |
|---|---|---|
|
Geef beans, componenten en eigen formuliercomponenten een prefix van je applicatie. |
Platformcomponenten beginnen met |
|
|
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. |
|
|
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. |
|
|
Geef elementen waarnaar code verwijst een betekenisvolle key, niet de ID die de BPMN-editor automatisch toekent. |
Een automatische ID zoals |
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. |
|
|
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. |
|
|
Roep een externe dienst vanuit de workflow asynchroon aan, met retries. |
Met |
|
|
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. |
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. |
|
|
Zet een execution listener die een variabele klaarzet, vóór het |
Beide worden uitgevoerd in de volgorde waarin ze in de XML staan. |
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. |
Geplande taken en onderhoudstaken
|
Afspraak |
Waarom |
Meer info |
|---|---|---|
|
Geef bij een geplande taak de tijdzone expliciet mee. |
Zonder tijdzone geldt die van de server. |
|
|
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. |
|
|
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. |
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. |
|
|
Maak afgeleide velden leeg voor je nieuwe gegevens ophaalt. |
Zo blijft er geen verouderde waarde staan als het ophalen mislukt. |
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 ( |
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 |
Veel upgrades verlopen zonder problemen, en de buildfouten tonen precies wat er aangepast moet worden. |
|
Controleer of |
Die versie staat in de pom van de platform-BOM. Een afwijkende versie geeft fouten bij het bouwen of uitvoeren. |
|
Zet de versie van |
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.