ORAFIN

Inleiding

ORAFIN is de boekhoudkundige dienst van de Vlaamse overheid (Oracle Finance), gebruikt door het Dienstencentrum Boekhouding (DCB) van het Departement Financiën en Begroting. De Skryv-platformconnector maakt het mogelijk om via ORAFIN uitbetalingen te laten uitvoeren, bijvoorbeeld van een premie.

Use cases

Een uitbetaling (bijvoorbeeld van een premie) laten uitvoeren via ORAFIN: begunstigden bundelen, een betalingsopdracht genereren en versturen, de aanvaarding ervan opvolgen, en na effectieve uitbetaling de betrokken dossiers hiervan op de hoogte stellen.

Setup

Onboarding

Je kan de connector enkel in gebruik nemen na een uitvoerige onboardingsprocedure bij ORAFIN. Hierbij verkrijg je alle info voor het opzetten van de connectie, en worden de nodige afspraken gemaakt rond de informatie-uitwisseling (o.a. de betekenis van een aantal vrij invulbare velden, zie ‘formuliertemplates’ verderop).

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.backend</groupId>
    <artifactId>orafin</artifactId>
    <version>${skryv.version}</version>
</dependency>

Communicatie

De communicatie met ORAFIN verloopt niet via REST-calls, maar via een protocol gebaseerd op tekstbestanden (flat files): informatie zit verpakt in regels met een vaste kolombreedte per veld, niet in JSON of XML.

De flow verloopt via drie bestanden:

• InFile: een opdracht tot uitbetaling, gecodeerd als tekstbestand en geplaatst op de server van ORAFIN.

• OutFile: het resultaat van ORAFIN's controle op die opdracht (aanvaard of niet, per begunstigde).

• BetFile: een bevestiging van ORAFIN dat de effectieve uitbetaling heeft plaatsgevonden.

Deze bestanden bevatten informatie over één of meerdere begunstigden. Je kan dus meerdere uitbetalingen in één bestand bundelen.

De platformconnector maakt hierbij gebruik van twee onafhankelijke, elk apart instelbare mechanismen:

1. Eigen opslag van de bestanden (los van ORAFIN zelf): lokaal op het bestandssysteem (default), of op AWS S3.

2. De effectieve verbinding naar de ORAFIN-server: plain FTP (default) of SFTP met authenticatie via private key.

Applicatie eigenschappen

Vul onderstaande applicatie eigenschappen in om binnen je project gebruik te maken van de connector.

Formuliertemplates voor uitwisseling met ORAFIN

Om de connector te kunnen gebruiken, voorzie je in je project twee formuliertemplates (documenten binnen de scope van het dossier). De platformconnector verwacht deze structuur letterlijk. De veldnamen hieronder komen rechtstreeks uit de broncode, dus wijzig ze niet.

Input-document: betalingsregels

Gelezen door prepareOrafinBulkDossiers. Bevat de ruwe betalingsaanvragen vóór ze gebundeld worden.

Trackingdocument: orafin

Dit document wordt door je project zelf aangemaakt/bijgewerkt (via writeOrafinDocument) en vervolgens door de overige functies (createOrafinInFile, processOrafinOutFile, processPayments, enzovoort) gelezen en bijgewerkt. Het bevat twee delen: de dossiers/begunstigden zelf, en een settings-sectie met omgevingsspecifieke standaardwaarden.

Dossiers en begunstigden

Settings-sectie

Vaste standaardwaarden, gebruikt bij het opbouwen van de InFile.

Scheduler

De platformconnector bevat zelf geen scheduler. Er is geen ingebouwd periodiek mechanisme dat automatisch nieuwe OutFiles/BetFiles bij ORAFIN ophaalt. Dit moet elk project zelf voorzien, want zonder een periodieke check komt er nooit een antwoord van ORAFIN binnen om te verwerken.

Een typische aanpak, als vertrekpunt (geen voorgeschreven implementatie):

1. Een periodieke taak (bv. via Spring's @Scheduled, met een cron-expressie als applicatie-eigenschap), die op een vast tijdstip:

   • OrafinManager.readOrafinOutFiles() aanroept om nieuwe bestanden bij ORAFIN op te halen, lokaal op te slaan, en van de ORAFIN-server te verwijderen.

   • de opgehaalde bestandsnamen onderverdeelt op prefix (bv. bestanden die starten met OUT_AP_INVOICES zijn OutFiles, bestanden die starten met OUT_AP_BET zijn BetFiles).

2. Verdere verwerking triggeren per bestand. Bijvoorbeeld door een eigen BPMN-proces te starten met de bestandsnamen als procesvariabele, dat vervolgens OrafinService.processOrafinOutFile(...)/analyzeBetFile(...) aanroept (rechtstreeks, of via je eigen projectlaag).

3. Voorkom overlappende uitvoeringen: als een vorige verwerkingscyclus nog niet afgerond is (bv. een vorig BPMN-proces nog actief), start dan geen nieuwe. Anders loop je het risico dat hetzelfde bestand dubbel verwerkt wordt.

Onderstaand schema illustreert precies dit patroon in de praktijk, gebaseerd op hoe een bestaand project dit heeft aangepakt. Het is geen exacte specificatie van wat de platformconnector zelf doet, en geen verplichte structuur. De concrete keuzes (cron-frequentie, hoe je bestanden aan dossiers koppelt, welk BPMN-proces je opzet) zijn projectspecifiek.

Het schema onderscheidt twee niveaus:

• Scope: individueel dossier (bovenaan). Dit toont het uitbetalingsproces van één dossier. Dit proces vult het ORAFIN-formulier in en wacht daarna passief op berichten, die het ontvangt zodra de scheduler een antwoord van ORAFIN verwerkt heeft.

• Scope: over alle dossiers heen (onderaan, ‘Skryv applicatie’). Dit toont de scheduler, die je zelf opzet (zie hierboven ‘Scheduler (project-verantwoordelijkheid)’). Deze verzamelt 's morgens alle klaarstaande ORAFIN-formulieren, bundelt ze in één InFile, en verstuurt die naar ORAFIN. 's Avonds haalt de scheduler de OutFile en de BetFile op, en stuurt telkens een bericht naar alle betrokken dossiers. Cruciaal daarbij zijn de messages die vanuit de scheduler naar de individuele dossiers gestuurd worden. Daarbij heb je nood aan een combinatie van twee unieke ID’s: enerzijds de process business key (unieke ID van het dossier) en anderzijds de payment ID (unieke ID van de betaling). Het is immers mogelijk om binnen één dossier meerdere uitbetalingsverzoeken te voorzien. Deze moeten afzonderlijk aanstuurbaar zijn.

Services en functies

Overzicht

@RequiredArgsConstructor
public class MyOwnService {
    private final OrafinService orafinService;
}

prepareOrafinBulkDossiers

Java-code

List<OrafinBulkDossier> bulkDossiers = orafinService.prepareOrafinBulkDossiers(prepareRequests);

Input

Output

Een lijst OrafinBulkDossier, elk met dossierId, dossierLabel, beneficiaries (lijst begunstigden). Dossiers waarvan de som van alle premies niet groter dan 0 is, worden er automatisch uitgefilterd.

Error-handling

Gooit een niet-opvangbare IllegalStateException als een dossier geen enkele begunstigde bevat in zijn betalingsregels-document.

writeOrafinDocument

Java-code

orafinService.writeOrafinDocument(execution);

Input

Output

Geen output (void). Zet zelf niets weg in het Skryv-document. Geeft enkel een OrafinDocument-structuur terug die je project vervolgens zelf naar het ORAFIN-document moet schrijven.

createOrafinInFile

Java-code

OrafinFile inFile = orafinService.createOrafinInFile(rawDocumentValue, dossierId);

Input

Output

Een OrafinFile-object met de opgebouwde I-/L-records voor elke begunstigde met actie ‘include’. Je project stuurt dit zelf door naar OrafinManager.saveOrafinInFile(...) om het effectief te versturen. Dat gebeurt hier niet automatisch.

processOrafinOutFile

Java-code

orafinService.processOrafinOutFile(rawDocumentValue, outFileName);

Input

Output

Geen output (void). Werkt rawDocumentValue zelf bij (status/foutcode/vervolgactie per begunstigde). Je project moet dit bijgewerkte document zelf terugschrijven.

Error-handling

Bij eender welke fout tijdens verwerking wordt de OutFile automatisch verplaatst naar de foutmap. Er wordt geen exceptie doorgegeven, enkel gelogd.

sendImportedMessages / getImportedMessagesReceivers

Java-code

orafinService.sendImportedMessages(rawDocumentValue);
// of, om zelf te versturen in plaats van de connector dit te laten doen:
List<String> ontvangers = orafinService.getImportedMessagesReceivers(rawDocumentValue);

Input

Output

sendImportedMessages: geen output. Verstuurt zelf een bericht met vaste naam (niet configureerbaar) naar elk dossier waarvan de import volledig is en waarvoor nog geen bericht verstuurd werd.
getImportedMessagesReceivers: geeft in plaats daarvan de lijst dossiernummers terug, zodat je project zelf bepaalt hoe/wanneer het bericht verstuurd wordt.

analyzeOutFile

Java-code

String omschrijving = orafinService.analyzeOutFile(filename);

Input

Output

De omschrijving uit de eerste regel van de OutFile. Puur om snel te kunnen inspecteren zonder het bestand effectief te verwerken.

sendPaidMessages / getPaidMessagesReceivers

Java-code

orafinService.sendPaidMessages(rawDocumentValue, dossierId);
// of:
List<MessagePaidDossier> betaaldeDossiers = orafinService.getPaidMessagesReceivers(rawDocumentValue, dossierId);

Input

Output

Analoog aan de Imported-versie hierboven, maar voor de effectieve uitbetaling: vast berichtnaam-patroon, of een lijst MessagePaidDossier (met dossierLabel, paymentDate, mbId) om zelf te versturen.

analyzeBetFile

Java-code

List<PaymentsWithDescription> payments = orafinService.analyzeBetFile(filename);

Input

Output

Een lijst, gegroepeerd per omschrijving, van uitgevoerde betalingen (invoiceNumber, paymentDate, paymentAmount).

moveBetToProcessed

Java-code

orafinService.moveBetToProcessed(filename);

Input

Output

Geen output (void). Verplaatst het bestand naar de ‘processed’-map.

processPayments

Java-code

orafinService.processPayments(rawDocumentValue, payments);

Input

Output

Geen output (void). Werkt rawDocumentValue zelf bij met de betaaldatum per begunstigde. Je project schrijft dit bijgewerkte document zelf terug.

getListOfCurrentDossiers

Java-code

List<String> dossiernummers = orafinService.getListOfCurrentDossiers(rawDocumentValue);

Input

Output

Lijst van dossiernummers die momenteel in het ORAFIN-document zitten.