Landbouw en visserij

Inleiding

Het Agentschap Landbouw en Zeevisserij is een Vlaams overheidsagentschap met als kerntaak het ondersteunen, reguleren en ontwikkelen van een duurzame landbouw- en visserijsector in Vlaanderen.

Use case

Percelen en ingezaaide teelten van een landbouwbedrijf opvragen bij het Agentschap Landbouw en Zeevisserij, en per erkende ramp automatisch de teeltoppervlaktes aggregeren binnen het getroffen gebied en de geldigheidsperiode van die ramp. Deze aggregatie wordt onder andere gebruikt om te controleren of de beschadigde oppervlakte van een teelt de 30%-drempel overschrijdt die recht geeft op een tegemoetkoming bij een erkende ramp (bv. het Vlaams Rampenfonds). Zonder deze drempelberekening zou enkel rekening gehouden worden met expliciet gedeclareerde, beschadigde percelen, en niet met de volledige, niet-beschadigde teeltoppervlakte van het bedrijf.

Setup

Onboardingsprocedure

Neem rechtstreeks contact op met het Agentschap Landbouw en Zeevisserij. De connector spreekt een WFS-service (Web Feature Service, een OGC-standaard) aan, beveiligd met een SSL-clientcertificaat. Voor meer info over de WFS-standaard zelf, zie docs.geoserver.org en opengeospatial.org/standards.

Dependency toevoegen in het POM.xml bestand

Om de connector te kunnen gebruiken, voeg je deze eerst als maven dependency toe aan het pom.xml bestand van je applicatie. Deze haalt de code voor de connector op bij het maken van de build voor je app.

<dependency>
   <groupId>com.skryv.connectors</groupId>
   <artifactId>lv</artifactId>
   <version>${skryv.version}</version>
</dependency>

Applicatie eigenschappen

Volgende applicatie eigenschappen kunnen ingesteld worden bij de technische setup van de landbouw en zeevisserij-connector.

Eigenschap	Verplicht	Default	Uitleg
`skryv.lv.url`	Ja	-	Basis-URL van de LV WFS-service, bv. `https://geoservices-priv.landbouwvlaanderen.be/PRIVACY/wfs` (productie) of `https://geoservices-priv.lenv.be/PRIVACY/wfs` (test).
`skryv.lv.aws.key`	Ja (bij `mutualssl.seed.enabled=true`)	-	Object-key (pad) van de keystore binnen die S3-bucket.
`skryv.lv.aws.bucket`	Ja (bij `mutualssl.seed.enabled=true`)	-	Naam van de S3-bucket waar de keystore staat.
`skryv.lv.mutualssl.keystore-file`	Ja (bij `mutualssl.enabled=true`)	-	Pad naar het keystore-bestand met het client-certificaat.
`skryv.lv.mutualssl.privateKeyPassword`	Ja (bij `mutualssl.enabled=true`)	-	Wachtwoord van de private key binnen de keystore.
`skryv.lv.mutualssl.keystorePassword`	Ja (bij `mutualssl.enabled=true`)	-	Wachtwoord van de keystore.
`skryv.lv.mutualssl.seed.enabled`	Nee	`false`	Indien `true`, wordt het keystore-bestand automatisch uit AWS S3 gehaald en lokaal weggeschreven naar `keystoreFile`, in plaats van een reeds aanwezig lokaal bestand te verwachten.
`skryv.lv.mutualssl.enabled`	Nee	`false`	Bepaalt of de connector via mTLS (client-certificaat) authenticeert. Staat dit op `false` (de default), dan gebruikt de connector een gewone, ongeauthenticeerde `RestTemplate`. Zet dit expliciet op `true` in elke echte omgeving.

Services en functies

Let op: deze connector wordt, in tegenstelling tot de andere connectoren in deze documentatie, niet aangesproken via een BPMN-workflow-expressie, maar uitsluitend rechtstreeks vanuit Java-code. De functies zijn enkel bereikbaar door LVService rechtstreeks als Java-bean te injecteren.

Java

@RequiredArgsConstructor
public class MyOwnService {
    private final LVService lvService;
}

Overzicht

Functie	Retourtype	Info
callLVServiceFromBackoffice	`LvRefList`	Haalt percelen/teelten op voor een bedrijf en jaar, en berekent de teeltoppervlakte-aggregatie voor een specifieke ramp. Voor gebruik vanuit de back-office (KBO-nummer al gekend).
callLVServiceFromELoket	`LvRefList`	Zelfde functionaliteit, maar voor gebruik vanuit het e-loket — met een extra controle op het KBO-nummer aan de hand van het dossier-id.

callLVServiceFromBackoffice

Java-code

LvRefList refList = lvService.callLVServiceFromBackoffice(kboNumber, year, disasterCode, rampenRefList);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`kboNumber`	String	'0554768734'	KBO-nummer (10 cijfers) van het landbouwbedrijf.
`year`	int	2018	Referentiejaar waarvoor percelen/teelten opgevraagd worden.
`disasterCode`	String	'a'	Code van de erkende ramp waarvoor de teeltoppervlakte-aggregatie berekend moet worden. Moet exact overeenkomen met de `code` van precies één item in `rampenRefList` (zie Error-handling).
`rampenRefList`	List<RampenRefList>	-	Lijst van alle gekende erkende rampen. Elk item bevat: `code`, `omschrijving`, `startDate`/`endDate` (rampperiode), `typeRamp`, `datumEerstePublicatieStaatsblad`, `startdatumAanvraag`/`einddatumAanvraag`, en `municipalities` (lijst van getroffen gemeentes, elk met `stad`, `code`, en een lijst `nisCodes`).

Output

Je krijgt een LvRefList-object terug met één veld items (List<LvRefListItem>). Elk item bevat:

Veld	Uitleg
`perceel`	Perceelnummer, aangevuld met de perceelnaam indien gekend (`"41 - Perceel 41"`).
`declaredArea`	Gedeclareerde oppervlakte in hectare (de connector zet de m²-waarde van LV automatisch om).
`nisCode`	NIS-code van de gemeente waarin het perceel ligt.
`validFrom` / `validTo`	Geldigheidsperiode van de teeltregistratie.
`cropCode` / `cropName`	Teeltcode en -naam.
`totalCropArea`	Som van `declaredArea` over alle percelen met dezelfde `cropCode`, maar enkel meegeteld wanneer het perceel binnen de geldigheidsperiode van de opgegeven ramp valt (rampstartdatum tussen `validFrom` en `validTo`) én in een door die ramp getroffen gemeente ligt (NIS-code van het perceel zit in `rampenRefList`). Voor percelen die niet aan beide voorwaarden voldoen, blijft dit veld `null` — ze staan wel in de lijst, maar tellen niet mee in de aggregatie. Deze aggregatie wordt onder meer gebruikt om de 30%-schadedrempel voor een teelt te berekenen (zie Use cases).

Error-handling

Deze connector gooit uitsluitend rauwe IllegalStateExceptions, geen BpmnError. Bij aanroep vanuit een BPMN-scripttaak resulteert elke fout dus in een Camunda-incident.

Situatie	Exceptie
`disasterCode` komt met geen enkel of met meer dan één item in `rampenRefList` overeen	`IllegalStateException("Invalid structure of response from ReferenceListRepository")`
`kboNumber` is `null` (enkel bij `callLVServiceFromELoket`)	`IllegalStateException("KboNumber is not defined for dossier %s")`
LV retourneert een WFS-foutrapport (XML in plaats van JSON)	`IllegalStateException` met de geëxtraheerde `<ows:ExceptionText>`-inhoud als bericht
Het JSON-antwoord van LV kan niet geparsed worden	`IllegalStateException("Failed to parse response from LV")`

callLVServiceFromELoket

Java-code

LvRefList refList = lvService.callLVServiceFromELoket(dossierId, year, disasterCode, kboNumber, rampenRefList);

Input

Inputparameters	Data type	Voorbeeld	Uitleg
`dossierId`	String	-	Id van het dossier. Wordt enkel gebruikt in de foutmelding als `kboNumber` ontbreekt.
`year`	int	2018	Referentiejaar.
`disasterCode`	String	'a'	Zie hierboven.
`kboNumber`	String	'0554768734'	KBO-nummer. Mag hier niet `null` zijn (zie Error-handling).
`rampenRefList`	List<RampenRefList>	-	Zie hierboven.

Output

Idem als bij callLVServiceFromBackoffice.

Error-handling

Idem als bij callLVServiceFromBackoffice.