Concept
Op de pagina Wat is een Skryv applicatie? lees je uit welke componenten een applicatie bestaat wanneer ze draait. Deze pagina bekijkt dezelfde applicatie vanuit de code: hoe de applicatie-repository opgebouwd is en waar je wat terugvindt.
Je bouwt een Skryv-applicatie nooit van nul op. Het platform levert de werking van dossiers, de workflow engine, de backoffice, de frontoffice en de connectoren als bibliotheken. De repository van je applicatie bevat enkel wat jouw applicatie eigen maakt: de configuratie van je dossiertypes en het maatwerk dat je erbovenop bouwt.
Het diagram toont de vaste structuur. De modules in de repository halen hun platformbouwstenen uit de Skryv-artifactory, en de module assemble voegt alles samen tot één uitvoerbare applicatie. Gestippelde onderdelen zijn optioneel.
Een Maven-project met meerdere modules
Een Skryv-applicatie is een Maven-project met meerdere modules. Dat is een gangbare manier om een Java-project op te delen: een root-pom.xml somt de modules op, en Maven bouwt ze in de juiste volgorde op basis van hun onderlinge afhankelijkheden. Meer over dit mechanisme lees je in de Maven-gids Guide to Working with Multiple Modules.
De root-pom.xml legt vast:
-
welke modules deel uitmaken van de applicatie.
-
welke platformversie je gebruikt, via de property
skryv.version. -
dat de versies van alle platformartefacten uit de platform-BOM komen.
-
waar Maven de platformartefacten ophaalt: de Skryv-artifactory.
Een vereenvoudigd voorbeeld:
<properties>
<skryv.version>32.0.0</skryv.version>
</properties>
<modules>
<module>backend</module>
<module>processes</module>
<module>backoffice</module>
<module>frontoffice</module>
<module>assemble</module>
</modules>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.skryv.backend</groupId>
<artifactId>backend</artifactId>
<version>${skryv.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Sommige applicaties declareren ook een eigen spring.boot.version. Die moet overeenkomen met de Spring Boot-versie die de gekozen platformversie verwacht. Controleer dat bij elke platformupgrade.
Standaardmodules
|
Module |
Wat erin thuishoort |
Technologie |
|---|---|---|
|
|
De configuratie per dossiertype: workflows (BPMN), formulieren, communicatietemplates en beslissingstabellen, met bijhorende tests. Zie Configuratie artefacten. |
BPMN, DMN, JSON, Handlebars |
|
|
Java-maatwerk van de applicatie: eigen services, connectoren, REST-endpoints en geplande taken. |
Java, Spring Boot |
|
|
Customizaties van de backoffice: eigen componenten, aangepaste pagina's, zoekconfiguratie, vertalingen en thema. |
AngularJS op |
|
|
Customizaties van de frontoffice: layout, pagina's, formulierconfiguratie, eigen formuliercomponenten, vertalingen en thema. |
React op |
|
|
Voegt alle modules samen tot één uitvoerbare applicatie. Bevat zelf nauwelijks code. |
Spring Boot |
In oudere applicaties heet de module voor de backoffice soms frontend en die voor de frontoffice eloket. De rol is dezelfde.
Platformartefacten als bouwstenen
De functionaliteit van het platform zit in afzonderlijke artefacten. Je neemt alleen op wat je applicatie nodig heeft, door het artefact als dependency toe te voegen. Je vermeldt daarbij geen versienummer: dat komt uit de platform-BOM. Dat principe heet een bill of materials en is standaard in Maven. Je leest er meer over in Introduction to the Dependency Mechanism.
Enkele voorbeelden uit bestaande applicaties:
|
Artefact |
Wat je ermee krijgt |
|---|---|
|
|
De kern van de back-end. Elke applicatie heeft dit nodig. |
|
|
Het uitsturen van e-mails, zie Email service. |
|
|
De Exposed API. |
|
|
Het beheer van het databaseschema. |
|
|
Een connector, bijvoorbeeld |
|
|
Hulpmiddelen om je maatwerk te testen (scope |
Opgelet: deze lijst is niet volledig. Welke artefacten er voor jouw platformversie bestaan, vind je in de Skryv-artifactory.
De frontends werken op dezelfde manier, maar met npm-pakketten uit de Skryv-registry: @skryv/core-ng1 voor de backoffice en @skryv/core-react voor de frontoffice. Voor de frontoffice in Vlaamse overheid-stijl komt daar @skryv/core-react-vo bij.
Waarom je weinig HTML en CSS in de repository ziet
Wie de repository van een Skryv-applicatie voor het eerst opent, zoekt vaak tevergeefs naar de HTML- en CSS-bestanden van de schermen. Dat is normaal. De standaardschermen, zoals het dossieroverzicht, de takenlijst, het zoekscherm en de weergave van formulieren, zitten in de platformpakketten @skryv/core-ng1 en @skryv/core-react. Die haalt npm bij het bouwen op uit de registry van Skryv, in de map node_modules, die niet in git zit. Het compileren voegt de platformpakketten en je eigen aanpassingen daarna samen tot de bestanden die de applicatie uitlevert.
In de repository staat dus alleen wat je applicatie anders maakt:
-
Een opstartpagina
index.htmlmet een lege container, waarin het platform de volledige applicatie opbouwt. -
De templates van je eigen backofficecomponenten, die vaak vooral platformcomponenten hergebruiken.
-
Je eigen frontofficecomponenten, waarvan de structuur in de JavaScript-code zelf staat, zoals gebruikelijk in React.
-
De SCSS-bestanden van je thema.
Formulieren, dossiertypes en workflows zijn bovendien helemaal geen HTML. Het zijn definities in de module processes, die het platform pas bij het gebruik omzet naar een scherm. Skryv is in de kern configuratiegestuurd: schermen worden opgebouwd uit definities, niet uit handgeschreven HTML.
Wil je zien hoe een standaardscherm in elkaar zit, bijvoorbeeld voor je het vervangt? Dan vind je de code van het platform na npm install lokaal in node_modules/@skryv/core-ng1 of node_modules/@skryv/core-react.
Eigen modules
Naast de standaardmodules kan een applicatie eigen modules bevatten. Dat is zinvol voor onderdelen die je los wilt houden van de rest van de back-end, bijvoorbeeld:
-
de koppeling tussen de claims van een identity provider en de rollen in de applicatie.
-
een integratie met een externe dienst die niet als platformconnector bestaat.
-
een brug tussen events van de workflow engine en andere systemen.
Een eigen module is een gewone Maven-module met een eigen pom.xml. Ze wordt pas deel van de applicatie wanneer je ze als dependency opneemt in assemble of in backend.
Eén uitvoerbare applicatie
De module assemble is de enige module die een uitvoerbare applicatie oplevert. Ze neemt de andere modules op als dependency en verpakt ze met de Spring Boot Maven-plugin tot skryv.jar. Dat is de standaardmanier om een Spring Boot-applicatie te verpakken. Meer lees je in Packaging Executable Archives.
Ook de gecompileerde backoffice en frontoffice worden als Maven-artefact in deze build meegenomen. Zo bouw je de volledige applicatie met één commando:
mvn clean install
Hoe je de applicatie lokaal opstart, lees je op Lokale setup.
Van architectuur naar code
De componenten uit Wat is een Skryv applicatie? vind je zo terug in de code:
|
Component |
Waar in de code |
|---|---|
|
Skryv back-end, workflow engine, Exposed API, Rapportage API |
Platformartefacten, aangevuld met je maatwerk in |
|
Email service |
Het platformartefact |
|
Backoffice |
De module |
|
Frontoffice |
De module |
|
Configuratie van dossiertypes |
De module |
|
Document model (DocMod) |
Een afzonderlijke component, niet in de repository van de applicatie |
|
Database, queuing systeem, zoekmotor, identity provider |
Niet in de code. De applicatie maakt er verbinding mee via eigenschappen. Lokaal start je ze met Docker Compose. |
Varianten
De structuur is vast, de inhoud niet. Enkele varianten die je in bestaande applicaties tegenkomt:
-
Zonder frontoffice. Een applicatie die alleen door medewerkers gebruikt wordt, heeft geen module
frontofficenodig. -
Met eigen modules. Het aantal eigen modules verschilt sterk per applicatie, van geen tot een handvol.
-
Met hulpmiddelen buiten de build. Scripts voor beheer of rapportage staan soms ook in de repository, maar maken geen deel uit van
skryv.jar. Zie Rapportage.
Waar maatwerk thuishoort
Configuratie die je in Skryv Studio maakt, komt in processes. Code die het platform uitbreidt of aanpast, komt in backend, backoffice, frontoffice of een eigen module. Welke mogelijkheden er per laag zijn en wanneer je welke kiest, lees je op Extensies & customizaties.
Platformversie en upgrades
Omdat de platformversie op één plek staat, upgrade je een applicatie door skryv.version in de root-pom.xml aan te passen en de applicatie opnieuw te bouwen. Configuratie past zich doorgaans vanzelf aan. Maatwerk moet je wel controleren: een nieuwe platformversie kan API's, componenten of thema-instellingen wijzigen. Raadpleeg daarom bij elke upgrade de release notes en Backwards compatibility.
Externe documentatie
-
Guide to Working with Multiple Modules (Apache Maven)
-
Introduction to the Dependency Mechanism (Apache Maven)
-
Packaging Executable Archives (Spring Boot)