VEKA

Inleiding

Deze connector laat toe om te communiceren met VEKA. VEKA is een intern verzelfstandigd Vlaams agentschap binnen het beleidsdomein Omgeving, opgericht op 1 januari 2021 uit het vroegere VEA. Hoofdtaak is de stimulering en uitvoering van het energie- en klimaatbeleid in Vlaanderen.

Use cases

• Een specifiek EPC-certificaat opvragen op basis van het attestnummer, om de energieprestatie van een gebouw te raadplegen binnen een dossier.

• Alle EPC-certificaten voor een gegeven adres opzoeken (bv. wanneer het attestnummer nog niet gekend is), met of zonder busnummer.

Setup

Onboardingprocedure

Om de connector op te zetten, moet je een specifieke onboardingsprocedure doorlopen. Neem hiervoor contact op met VEKA. Dit resulteert in de nodige info waarmee je je Skryv app kan authenticeren bij VEKA. De authenticatie gebeurt via mTLS (client-certificaat): het certificaat, de private key en het wachtwoord worden gebruikt om een KeyStore/SSL-context op te bouwen waarmee elke aanroep naar de EPC-API wordt geauthenticeerd.

Dependency toevoegen aan 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>veka</artifactId>
   <version>${skryv.version}</version>
</dependency>

Applicatie eigenschappen

Volgende applicatie eigenschappen kunnen ingesteld worden bij de technische setup van de VEKA-connector.

Services en functies

Overzicht

@RequiredArgsConstructor
public class MyOwnService {
    private final EpcCamundaConnector veka;
}

getCertificate

Workflow expressie

${veka.getCertificate(String certNumber, String date)}

Java-code

EpcCertificate certificate = veka.getCertificate(certNumber, date);

Input

Output

Je krijgt een EpcCertificate-object terug met: typePand, attestnummer, label, gebouwId, gebouweenheidId, datumIngediend, adres (postcode, straat, huisnummer, gemeente, busnummer, land), datumGeldigheid, attestnummerLaatstGeldend, status, error.

Error-handling

Deze functie gooit geen exceptie bij een HTTP-foutstatus van de EPC-API. In plaats daarvan krijg je een EpcCertificate-object terug waarvan enkel het veld errors ingevuld is, met een bericht in de vorm:

Het EPC attest kan niet worden opgehaald, de API service gaf volgende status code terug: "<statuscode> <responsbody>"

Controleer dit veld dus altijd, in plaats van te veronderstellen dat een geretourneerd object automatisch geldig is:

EpcCertificate certificate = veka.getCertificate(certNumber, date);
if (certificate.getErrors() != null) {
    // fout opgetreden, zie certificate.getErrors() voor detail
}

Bij een ontbrekend of ongeldig ingevuld certNumber/date (bv. verkeerd datumformaat) gooit de connector wél een niet-opvangbare EpcValidationException, wat resulteert in een Camunda-incident.

getSearchCertificates

Deze functie bestaat in twee varianten: met en zonder busnummer.

Workflow expressie 1 (met busnummer)

${veka.getSearchCertificates(String street, String housenumber, String busnumber, String zipcode, String municipality)}

Workflow expressie 2 (zonder busnummer)

${veka.getSearchCertificates(String street, String housenumber, String zipcode, String municipality)}

Java-code

// Variant 1
SearchCertificate[] certificates = veka.getSearchCertificates(street, housenumber, busnumber, zipcode, municipality);

// Variant 2
SearchCertificate[] certificates = veka.getSearchCertificates(street, housenumber, zipcode, municipality);

Input

Output

Je krijgt een lijst SearchCertificate[] terug met alle EPC-certificaten voor het opgegeven adres. Elk element bevat: id, status, attestnummer, datumIngediend, gebouweenheidId, gebouwId, datumGeldigheid, epcEenheidType, bestemming, gebouwTypes (lijst), adressen (lijst van adressen, elk met postcode/straat/huisnummer/gemeente/busnummer/land plus een crabcode-object en arId), en score (kengetal: meeteenheid + waarde; label: waarde).

Error-handling

In tegenstelling tot getCertificate gooit deze functie bij een HTTP-foutstatus van de EPC-API wél een exceptie, maar wordt de oorspronkelijke HttpStatusCodeException opnieuw gegooid als een generieke RuntimeException, zonder het statuscode-detail te behouden. Dit resulteert in een Camunda-incident. Bij een ontbrekende parameter (null-waarde bij één van de verplichte velden) gooit de connector een niet-opvangbare EpcValidationException, eveneens een Camunda-incident.