ORAFIN

Inleiding

OraFin is de afkorting voor Oracle Finance, een financieel softwareplatform dat gebruikt wordt door de Vlaamse overheid, met name binnen het Dienstencentrum Boekhouding (DCB) van het Departement Financiën en Begroting. We connecteren met ORAFIN om uitbetalingen (bijvoorbeeld van een premie) of terugvorderingen (bijvoorbeeld van onterecht uitbetaalde premies) te laten uitvoeren.

Setup

Maven dependency

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

Onboarding bij OraFin

Je kan de connector enkel maar 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.

Communicatie

De communicatie met OraFin verloopt niet via REST-calls, maar werkt via een protocol gebaseerd op tekstbestanden. Het gaat om zogenaamde flat files waarbij de informatie verpakt zit in één lange string. Generatie of interpretatie gebeurt door deze string te concateneren of op te kappen volgens een vaste positionele syntax. De flow verloopt grosso modo via drie bestanden:

1. InFile: een opdracht tot uitbetaling of terugvordering wordt gecodeerd als een tekstbestand en op de SFTP-server (dropserver) van OraFin geplaatst.

2. OutFile: vervolgens gebeurt een check door OraFin. Het resultaat van deze check (in essentie een OK of niet-OK) is opnieuw een tekstbestand dat je kan uitlezen op de OraFin-server.

3. BetFile: na een succesvolle uitbetaling of terugvordering plaatst OraFin een laatste notificatiebestand op de OraFin-server.

Merk op dat deze bestanden info kunnen bevatten over één of meerdere transacties en dossiers. Met andere woorden, het is mogelijk om verschillende betalingen te groeperen en te bundelen in één enkel bestand.

Binnen het Skryv platform zijn de nodige functies voorzien om deze tekstbestanden automatisch aan te maken, te versturen, op te halen, te interpreteren en zo verder. Deze zijn out-of-the-box beschikbaar en worden onderaan deze pagina beschreven.

Binnen je project zet je zelf volgende zaken op om de connectie met OraFin werkende te krijgen.

• Formuliertemplate waarmee je binnen de scope van een dossier een formulier aanmaakt dat fungeert als interface met de Orafin-bestanden. Hierin komt alle relevante informatie per uitbetaling of terugvordering. Denk bijvoorbeeld aan een unieke ID, het uit te betalen of terug te vorderen bedrag en het rekeningnummer. Hierin verschijnt uiteindelijk ook de feedback van Orafin zoals de aanduiding of de uitbetaling uitgevoerd is. Dit formulier heeft verplicht de key ‘orafin_credit’ (bij betalingen) of ‘orafin_debit’ (bij terugvorderingen). Meer info verderop.

• Schedular waarbij de applicatie op met OraFin afgesproken tijdstippen bestanden op de Orafin-server plaatst of ophaalt. Bijvoorbeeld, de applicatie bundelt elke morgen om 7 uur alle aangevraagde betalingen en plaatst hiervoor een InFile-bestand op de OraFin-server. Elke avond om 7 uur checkt de applicatie dan weer of OraFin OutFile-bestanden of BetFile-bestanden heeft klaargezet.

• Mechanisme dat communicatie tussen de schedular en de individuele dossiers faciliteert. Cruciaal daarbij zijn de messages die vanuit de schedular naar het individuele dossier 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.

• Integratie van door Skryv platform ontwikkelde services en functies in zowel workflow als schedular.

In het diagram hieronder vind je een BPMN-beschrijving van het protocol. Uiteraard is dit een vereenvoudigde weergave en kan dit project per project verschillen. De werking van de schedular is hier via BPMN-notatie beschreven, maar programmatie en uitvoering gebeuren in de praktijk via een ‘full-code’ Java-extensie.

Veiligheid

De communicatie met Orafin verloopt over een beveiligde SFTP-server. De benodigde credentials worden opgeslagen in AWS Secrets Manager en via terraform als omgevingsvariabelen beschikbaar gesteld voor de applicatie.

Bijvoorbeeld:

{
 name = "SKRYV_ORAFIN_PRIVATEKEYPATH"
 value = aws_secretsmanager_secret.orafin_ssh_key_prod.name
},
{
 name = "SKRYV_ORAFIN_PRIVATEKEYPASSWORD"
 value = aws_secretsmanager_secret.orafin_ssh_password_prod.name
},

Applicatie eigenschappen

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

Let op: Applicatie-instellingen in application.properties kunnen worden overschreven door waarden die via terraform worden ingesteld als omgevingsvariabelen of externe configuratiebronnen (zoals AWS Parameter Store of Secrets Manager).

Formuliertemplates voor uitwisseling met Orafin

Een Skryv formuliertemplate vormt de interface om info met de Orafin bestanden (InFile, OutFile, BetFile) uit te wisselen. Voor uitbetalingen heef het formulier verplicht de key ‘orafin_credit’, de naam zelf is vrij te kiezen. Voor terugvorderingen is de key ‘orafin_debit’. Onderstaande lijst toont de velden die je in deze formulier kan opnemen. Sommige info is verplicht (d.w.z. zonder deze info Orafin een foutmelding terugsturen), andere info is optioneel. Het formulier valt uiteen in twee secties. De eerste sectie bevat info specifiek over de betalingen of terugvorderingen; de tweede sectie bevat algemene instellingen. Let erop dat de keys van je formuliervelden exact overeenstemmen met de waardes in de ‘Veld’-kolom.

De betekenis van elk veld en de mogelijke waardes die erin komen, moeten op voorhand doorgesproken zijn met OraFin.

Sectie 1 : specifieke info

Voor betalingen :

Voor terugvorderingen:

Sectie 2: algemene instellingen

Voor uitbetalingen:

Voor terugvorderingen:

Services en functies

De ORAFIN-connector bestaat uit een aantal services waarbinnen verschillende functies beschikbaar zijn. Hieronder volgt een beschrijving van alle functies gegroepeerd per service. Deze zijn op te roepen vanuit de schedular of vanuit de workflow.

Uitbetalingen

Orafin InFile service

Deze service zorgt voor het creëren en uitsturen van een Orafin-bestand op basis van verzoeken tot uitbetaling.

createInFilesForReadyDossiers

Expressie

${orafinInFileService.createInFilesForReadyDossiers(String orafinMessageName)}

Uitleg

• Haalt klaarstaande betalingsinformatie op uit de verschillende dossiers. Na uitsturen naar Orafin wordt een message teruggestuurd naar de betrokken dossiers.

• Op te roepen vanuit de schedular.

Input

Output

Geen output.

Orafin Out service

Deze service zorgt voor het afhandelen van teruggestuurde Orafin-bestanden die informatie bevatten over de status van elk verzoek tot uitbetaling (met name of die aanvaard is of niet).

processOutFiles

Expressie

${orafinOutService.processOutFiles()}

Uitleg

• Deze functie zorgt voor de verwerking van de beschikbare bestanden.

• Op te roepen vanuit de schedular.

Input

Geen input.

Output

Geen output.

updateCreditDocumentFromOutFile

Expressie

${orafinOutService.updateCreditDocumentFromOutFile(String dossierId, OutfileResponse outfileResponse, String paymentId)}

Uitleg

• Deze functie voert een update uit van het ‘ORAFIN_CREDIT_DOCDEF’-formulier. Het wijzigt de status van de velden ‘orafinStatus’ en ‘orafinErrorCode’ op basis van info uit de verwerkte OutFiles.

• Op te roepen vanuit de BPMN-workflow.

Input

Output

Boolean

De functie evalueert naar true als de OrafinStatus gelijk is aan ‘Imported’ (d.w.z. aanvaard). Indien niet, dan geeft de functie false terug. Op basis van de geretourneerde waarde zal je via een gateway een specifiek vervolgpad in de workflow activeren.

Orafin Bet Service

Deze service zorgt voor het afhandelen van Orafin uitbetalingsbestanden die informatie bevatten over de concrete uitvoering van verzoeken tot uitbetaling (met name dat de betaling is uitgevoerd, alsook de precieze datum waarop dat is gebeurd).

processBetFiles

Expressie

${orafinBetService.processBetFiles()}

Uitleg

• Deze functie zorgt voor de verwerking van de beschikbare BetFiles.

• Op te roepen vanuit de schedular.

Input

Geen input.

Output

Geen output.

updateCreditDocumentFromOutFile

Expressie

${orafinBetService.updateCreditDocumentFromBetFile(String dossierId, paymentDate, String paymentId)}

Uitleg

• Deze functie voert een update uit van het ‘ORAFIN_CREDIT_DOCDEF’-formulier. Het wijzigt de status van het veld ‘orafinStatus’ naar de waarde van PAID_BET_FILE en vult het ‘paymentDate’-veld in met de datum waarop de uitbetaling is gebeurd.

• Op te roepen vanuit de BPMN-workflow.

Input

Output

Geen output.

Terugvorderingen

Orafin InFile Debit Service

Deze service zorgt voor het creëren en uitsturen van een bestand op basis van verzoeken tot terugvordering.

createDebitInFilesForReadyDossiers

Expressie

${orafinInFileDebitService.createDebitInFilesForReadyDossiers(String orafinMessageName)}

Uitleg

• Haalt klaarstaande terugvorderingsinformatie op uit de verschillende dossiers. Na uitsturen naar Orafin wordt een message teruggestuurd naar de betrokken dossiers.

• Op te roepen vanuit de schedular.

Input

Output

Geen output.

Orafin Debit Out Service

Deze service zorgt voor het afhandelen van Orafin bestanden die informatie bevatten over de status van elk verzoek tot terugvordering (met name of die aanvaard is of niet).

processOutFiles

Expressie

${orafinDebitOutService.processDebitOutFiles()}

Uitleg

• Deze functie zorgt voor de verwerking van de beschikbare bestanden.

• Op te roepen vanuit de schedular.

Input

Geen input.

Output

Geen output.

updateDebitDocumentFromOutFile

Expressie

${orafinDebitOutService.updateDebitDocumentFromOutFile(String dossierId, OrafinDebitOut outfileResponse, String paymentId)}

Uitleg

• Deze functie voert een update uit van het ‘ORAFIN_DEBIT_DOCDEF’-formulier. Het vult de veldengroep ’orafinFeedback’ in op basis van info uit de verwerkte bestanden komende van Orafin.

• Op te roepen vanuit de BPMN-workflow.

Input

Output

Boolean

De functie evalueert naar true als Orafin de terugvorderingsopdracht aanvaard heeft. Indien niet, dan geeft de functie false terug. Op basis van de geretourneerde waarde zal je via een gateway een specifiek vervolgpad in de workflow activeren.

Orafin Debit Bet Service

Deze service zorgt voor het afhandelen van Orafin Debit BetFiles die informatie bevatten over de concrete uitvoering van verzoeken tot terugvordering (met name dat de terugvordering is uitgevoerd).

processDebitBetFiles

Expressie

${orafinDebitBetService.processDebitBetFiles()}

Uitleg

• Deze functie zorgt voor de verwerking van de beschikbare BetFiles.

• Op te roepen vanuit de schedular.

Input

Geen input.

Output

Geen output.

updateDebitDocumentFromOutFile

Expressie

${orafinDebitBetService.updateDebitDocumentFromBetFile(String dossierId, debitPayment, String paymentId)}

Uitleg

• Deze functie voert een update uit van het ‘ORAFIN_DEBIT_DOCDEF’-formulier. Het vult info over de uitgevoerde terugvordering in op basis van het door Orafin gestuurde bestand.

• Op te roepen vanuit de BPMN-workflow.

Input

Output

Geen output.