tango
een introductie
We bouwen veel "dossierapps"
Wat is een dossierapp?
Staan we even stel bij de high-level requirements van zo een "dossierapp", dan zijn ze deze:
- een doorzoekbare, filterbare en exporteerbare lijst van dossiers
- een dossier aanmaken, bekijken, bewerken en goedkeuren, en aanverwante zaken als historiek, bijlagen en meldingen
Dit soort toepassingen bouwen we keer op keer, telkens een beetje anders maar toch heel gelijkaardig. Om dit mogelijk te maken voorziet ACPaaS in heel wat engines: GDP, Workflow, Notification, ...
tango
Deze starterkit komt in de vorm van een werkende applicatie voor dossierbeheer, waarin je aanvragen voor een betaalde opleiding kan aanmaken en bewerken. De starterkit bestaat uit een responsive en accessible frontend en een fully featured business API, en dient als het vertrekpunt om snel van de grond te geraken met een volwaardige dossierbeheertoepassing.
De demotoepassing bevat volgende functionaliteiten:
- aanmelden als medewerker, met toegang afgeschermd via rollen
- dossiers zien, zoeken, aanmaken en bewerken
- bijlages toevoegen aan een dossier
- acties uitvoeren op een dossier, met of zonder de workflow engine
- meldingen ontvangen bij handelingen op het dossier
Daarnaast voorzien we ook een intakeprocedure voor nieuwe Tango-projecten, en een technische bootstrapgids om ontwikkelaars vlot door een ontwikkeling met Tango te loodsen.
Tango is modulair opgebouwd bovenop ACPaaS, en out of the box conform aan de EA richtlijnen en best practices. In deze tekening zie je de verdeling van werk tussen de Tango app en API starter kits. De frontend is gebaseerd op ACPaaS UI voor Angular en de ACPaaS UI starter kit. De backend is ontwikkeld in Node.js.
Zowel app als API zijn volledig aanpasbaar naar de noden van het project. Gemeenschappelijke functionaliteit is ontsloten als widget- en API-packages, zodat je nieuwe features en bugfixes eenvoudig als update kan binnenhalen in een bestaand Tango-project.
Laten we even inzoomen op de frontend...
Smart Table
De Tango frontend maakt gebruik van apart gepubliceerde en configureerbare smart widgets.
Het overzichtsscherm van dossiers bouwt verder op de Smart Table widget. Deze voorziet een generieke UI van een tabel met filters, sortering, paginering, excel export en meer. Als ontwikkelaar dien je enkel de configuratie en een data endpoint te voorzien. Deze widget staat toe om krachtige overzichtsschermen te bouwen zonder boilerplate code.
Dossier Editor & Form Renderer
Om dossierdetails weer te geven en bewerken bouwen we verder op de form engine. In de form composer ontwerpen we in wysiwyg-stijl één of meer formulieren voor weergave, aanmaken en bewerken. Een generieke dossier editor widget verpakt deze formulieren en gaat ze verbinden met de achterliggende Tango API. Foutberichten uit de achterliggende API worden automatisch teruggekoppeld naar het juiste veld zodat de gebruiker gerichte feedback krijgt.
Dit staat een intuïtief ontwerp van dossierdetails toe, waarbij de eindgebruiker zelf mee kan ontwerpen. Sommige details van het formulier (zoals volgorde van velden, labels, extra informatie en validatieregels) kunnen zelfs gewijzigd worden nadat de toepassing reeds live is, zonder code-aanpassingen.
Historiek
Dossierhistoriek is ontsloten via een generieke maar aanpasbare historiekwidget. De historiek kan gefilterd worden volgens de mogelijkheden van de GDPng Dossierhistoriek API, en de weergave van de historieklijnen kan aangepast worden naar de noden van de toepassing.
Een aanpasbaar detailpaneel kan toelichten wat er exact veranderde. Out of the box toont dit de statusovergangen.
Bijlagen
De bijlagenfunctionaliteit van GDPng is ontsloten als bijlagenschermen in het dossier. De UI hiervan kan volledig aangepast worden, en eventuele extra velden gelinkt aan elke bijlage kunnen bewaard worden in het dossier en wijzigingen hiervan verschijnen in de dossierhistoriek.
Onder de Tango architectuur zit ACPaaS. We maken onder andere gebruik van:
- GDPng voor het bijhouden van dossiers en dossierbijlagen (duh)
- Form engine voor dossierdetailschermen
- Notification engine voor het uitsturen van berichten bij dossierwijzigingen
- M-profiel voor het mappen van usernames op friendly names
- Authz voor het valideren van rollen en permissies
Een typische vraag bij gebruik van Tango is: "is er een speciale Tango tenant voor Form engine of GDPng?". Het antwoord is nee, omdat een Tango applicatie of API een standaardoplossing is op ACPaaS, gebouwd met Angular en Node, maar dan gewoon één met een eigenaardige origin story. Alle best practices voor standaardoplossingen kan je dus toepassen. Dit wil zeggen dat je zelf kan kiezen welke de meest geschikte GDPng en Form engine tenant voor je project zal zijn.
Tussen de widgets en de ACPaaS API's is waar het hart van de toepassing leeft, de businesslogica. De Tango API starter kit is net zoals de frontend modulair opgebouwd, uit API packages.
De packages koppelen aan als puzzelstukken, maar zijn ook afzonderlijk inzetbaar. Via configuratieparameters en hook functies kan het gedrag van de packages volledig bijgestuurd worden. Aangezien de top-level routing in de API starterkit repo zit, en niet in een package, kan je de API endpoints volledig aanpassen en uitbreiden met de specifieke businesslogica van jouw project.
Laten we even deze tussenliggende lagen dieper verkennen...
app.use(createSmartTableRouter({
gdpDossierApi: { /* ... */ },
gdpDossierTypeIds: [ "..." ],
tableConfig: {
columns: [{
label: 'Opleiding',
key: 'opleiding_name',
type: 'text',
gdpPath: 'dataObject/jsonData/opleiding/naam',
}, /* ... */ ]),
filters: [{
id: "generic",
display: "generic",
label: "Zoek een opleidingsaanvraag",
type: "input",
fields: ["aanvrager_name", "opleiding_name", "locatie"],
}, /* ... */],
options: {
defaultSortOrder: {
key: "created_at",
order: "desc",
}, /* ... */
}
},
hooks: { /* ... */ }
})
<aui-smart-table
apiUrl="/api/dossiers/table/search"
(rowClicked)="onRowSelect($event)">
</aui-smart-table>
De GDPng Smart Table connector is een BFF package die API routes voorziet om de Smart Table te voeden met dossiergegevens uit GDPng. Als ontwikkelaar voorzie je enkel welke dossiertypes je wil ontsluiten, en welke kolommen en filters ervan moeten ontsloten worden. De connector en widget handelen de details af van de weergave van de lijst van dossiers.
Via custom column components en hook functies kan de weergave van de smart table bijgestuurd worden. Out of the box is er echter erg weinig code nodig om de smart table weer te geven. De code die je hier ziet volstaat.
De dossier-and-form package vormt de basis van de Tango API. Deze maakt de verbinding tussen het formulier uit de UI en de GDPng Dossier API.
Via mappingregels bepaalt de ontwikkelaar hoe de velden uit het formulier verbinden op velden uit het dossiertype. Met behulp van hook-functies kan dit gedrag volledig gewijzigd worden, en custom validatie toegevoegd. Door de generieke digipolis/authz package worden de routes afgeschermd met de nodige permissies.
In de README van deze package staat een cookbook om allerlei gangbare scenario's op te lossen, van het genereren van een custom dossiernummer tot het inpluggen op een ander dossiersysteem dan GDPng.
Wijzigingen van velden op het dossier worden afgehandeld door een PATCH route op de dossier-and-form package. Echter, vaak hebben dossiers andere soorten van wijzigingen nodig, zoals statusveranderingen, goedkeuringen, of complexere flows waarbij gebruikersinteracties vereist zijn. Deze wijzigingen kunnen manueel getriggerd worden door de gebruiker, of gebeuren automatisch in respons op dossierwijzigingen.
Dit soort van wijzigingen die niet netjes op REST operaties mappen maken we mogelijk via de dossier-workflow package. Deze ontsluit een generiek concept van acties. Acties van het kortlopende type, zoals bvb een statuswijziging met validatiecheck, worden synchroon uitgevoerd. Ook langlopende acties zijn mogelijk, waar de gebruiker niet op zal wachten en die dus asynchroon uitgevoerd worden, eventueel via de Workflow engine.
In de huidige versie van Tango zijn beide actietypes mogelijk, maar is enkel nog maar een voorbeeldactie geimplementeerd van het kortlopende type, met name de change-status operatie. Dit is door de ontwikkelaar echter uit te breiden met alle nodige acties, zowel kortlopend als langlopend.
Bijlagen op het dossier beheren en ontsluiten als een aanpasbare API wordt afgedekt door de dossier-attachments package. Deze ontsluit alle nodige routes voor het beheren van bijlagen, en bevat een actie om bijlages ingediend vanuit het initiele formulier automatisch te verplaatsen van de voorlopige Digital Assets opslag verbonden aan het formulier naar de finale locatie in de GDPng Assets API.
Deze package maakt het ook mogelijk om extra metadata van een bijlage te bewaren in het dossier, zoals een opmerkingenveld, waarvan de wijzigingen zullen opduiken in de dossierhistoriek.
Voor het monitoren van dossiers en het automatisch uitsturen van meldingen voor wijzigingen hebben we de dossier-notifications package.
Centraal is de DossierWatcher die dossiers observeert om wijzigingen te detecteren. Een TaskWatcher om taken van de GDPng Process API te observeren is voorzien in de architectuur, maar is (nog) niet gerealiseerd.
DossierWatcher bevraagt de GDPng Dossier API om wijzigingen van dossiers te ontdekken, zodat deze altijd geobserveerd worden, zelfs wanneer het notifications-systeem tijdelijk onbeschikbaar was tijdens de wijziging. Via state tracking in MongoDB verzekeren we dat wijzigingen slechts eenmalig gedetecteerd worden en geen dubbele of verouderde notifications zullen triggeren. Een jobssysteem gebaseerd op AgendaJS en MongoDB zorgt dat de afhandeling van dossierwijzigingen automatische retry-pogingen doet bij onbeschikbaarheid van de onderliggende API's en dat deze oplossing vlot schaalt naar hoge volumes door extra containers op te spinnen.
De NotificationSender maakt een abstractie over de onderliggende notification engine, zodat de ontwikkelaar zich kan focussen op de inhoud van notifications in plaats van de mechaniek van hoe je de Notification engine aan moet roepen.
Out of the box is voorzien in een generieke DossierNotifications oplossing die emails uitstuurt bij creatie en wijziging van een dossier. Het is mogelijk om deze mails inhoudelijk te wijzigen via templates, en om in plaats van mails andere notifications uit te sturen, zoals SMS of in-app. Een generieke notifications smart widget staat toe om met minimale code in-app notifications te integreren in de UI voor die toepassingen waar dit gewenst is.
Deze oplossing is volledig losstaand inzetbaar van de rest van Tango, en kan dan ook ingeplugd worden op andere GDPng toepassingen.
Aan GDPR verplichting zoals het aantoonbaar verwijderen van persoonlijke gegevens voldoen is vaak geen evidentie. Om die reden voorziet de Tango basis in een volwaardige GDPR oplossing voor het verwijderen of anonimiseren van dossiers.
Een beheerder (afgeschermd via de gepaste rol) krijgt een overzichtsscherm te zien van dossiers die aan de voorwaarden voldoen om geanonimiseerd of verwijderd te worden (bvb ouder dan 3 maanden). Als Tango-ontwikkelaar kies je zelf welke dossiers dit zijn, hoe je de gegevens daarvan toont, en of je de verwijderings- of anonimiseringsfunctie aan gaat bieden als een knop, of allebei.
Wanneer de beheerder op de knop klikt wordt in de achtergrond een job gestart die deze dossiers zal verwerken als een langlopende operatie. Elk dossier wordt een aparte job binnen het AgendaJS jobsysteem. Op deze manier garanderen we dat elk dossier aantoonbaar verwijderd of geanonimiseerd kan worden. Een Jobs UI toont de voortgang van deze operatie.
Als ontwikkelaar bepaal je zelf via een hook functie exact wat anonimisering wil zeggen: welke velden moeten aangepast worden, en welke waarden schrijf je daar naartoe, en moeten bijlagen nu wel of niet verwijderd worden? Kies je voor verwijdering dan is dit standaard een hard delete, maar ook een soft delete is mogelijk via een hook functie.
Go Tango
Wil je starten met Tango, dan begin je steeds met een intake. Tijdens de intake zal een Enterprise Architect jouw use case matchen tegen de Tango-functionaliteit, en je gidsen door het gebruik van Tango. Vraag een intake via de contactinformatie op het ACPaaS Portaal.
Na de intake ga je als businessarchitect door de documentatie op het ACPaaS Portaal, op de ACPaaS Wiki, en in de readme's van de Tango git repo's. De kennis over de mogelijkheden van de Tango bouwblokken gebruik je dan om een oplossing te schetsen die verder bouwt bovenop de basis van Tango, in plaats van ervan af te wijken, zodat deze snel kan gebouwd worden.
Als ontwikkelaar start je met de bootstrapgids uit de Tango app starter kit git repo. Deze bevat het stappenplan hoe je een Tango app en API ontwikkelt en uitrolt.
Loop je vast met Tango, dan kan je steeds terecht met je vragen op het #tango kanaal op Digipolis Slack, of kan je ze sturen naar de contactpersonen uit het ACPaaS Portaal.
Dit was Tango. Hopelijk ben je ook begeesterd door deze oplossing.