Skip to content

XBRL Toolkit

De XBRL tookit is een applicatie die is geschreven om NTA- (Nederlandse Taxonomie Architectuur) taxonomieen te kunnen lezen, bekijken en onderzoeken. De toolkit is opgebouwd uit verschillende modules.

Parser

De parser maakt van xml-bestanden waarin de taxonomie is geschreven, python-objecten. XML en daarmee XBRL is lastig te lezen voor mensen. En taxonomieen hebben de neiging groot te zijn. Om iets met XML te kunnen doen zul je die eerst moeten lezen en omzetten in gestructureerde hierarchie waarmee je verder kan werken. Dit doet de parser. De parser leest een of meerdere entrypoints in een DTS en maakt daar concepten, linkroles, labels, referenties e.a. van. Vervolgens worden alle netwerken via de locators en arcs ontdekt en bouwen de verschillende hierarchieen op.

Validator

Een van de taken van Logius is het valideren van taxonomieen die door derden zijn ontwikkeld. De meeste NTA-Regels. Je kan er voor kiezen om tijdens het parsen de taxonomie te valideren. Wanneer je hiervoor kiest, dan zal er een validator worden geladen. Tijdens de diverse stadia van de parser worden dan tests uitgevoerd die controleren of er bijvoorbeeld conform naamgevingsconventies ID's zijn weggeschreven, of concepten wel een label hebben. Dit zijn slechts twee voorbeelden, maar bijna alle regels worden gecontroleerd.

De uitkomst van de validatie wordt weggeschreven in een validatierapport, de rapporten worden gepubliceerd op de website

Database

Het resultaat van de parser is vluchtig. Als je het programma afsluit is het weg. Om langer met het resultaat te kunnen werken moet je het opslaan. Dat doen we in een database. De toolkit is zo geschreven dat dit een sqlite of een postgres database kan zijn. We hebben er voor gekozen om postgres de default te laten zijn, maar bijv. op localhost volstaat sqlite. Het gebruik van de database maakt o.a. Nessie en de Versie-vergelijker mogelijk.

Gebruik

Er zijn drie interfaces voor de toolkit, een python-gui, een python-cli en het web. De focus ligt de laatste tijd op het web, om een altijd benaderbare interface te hebben op een draaiende toolkit.

Admin workflow

Normaal gesproken is de workflow als volgt: - je uploadt een zipfile - je unpackt de zipfile (op de server) - je parset de entrypoints die in de zipfile zijn gevonden, valideert tijdens het parsen en slaat eventueel op in de database.

De hele workflow als gebruiker lees je in de Uitgebreidere gebrukersdocumentatie

Configuratie

De toolkit kent een configuratiebestand. Dit bestand is niet opgenomen in git, omdat we niet willen dat lokale instellingen op de server terecht komen en, er staan wachtwoorden in (van lokale accounts weliswaar) die beter niet kunnen lekken. Hieronder een overzicht van de belangrijkste instellingen in de configuratie. In config.sample.yaml zijn veel opties van commentaar voorzien. De configuratie staat in /app/kenniscentrumxbrl/discover_xbrl/conf/config.yaml.

  • admin
    • send_notification: boolean, wanneer true stuurt de toolkit een email wanneer het parsen van een taxonomie gereed is.
    • smtp_port: int, op welke poort luistert de smtp server?
    • user_db: gebruikers van de admin interface op het web. defaults to db/users.json
    • webroot: string, moet overeenkomen met de webroot van nginx.
  • cli
    • parse: boolean, voor de defaults in het webinterface
    • validate: boolean, voor de defaults in het webinterface
    • store: boolean, voor de defaults in het webinterface
  • db
    • type: postgres/sqlite
    • dbname: default_db_name. Deze wordt gebruikt door de GUI en CLI
    • dbnames: {dict} Key-value Databasenaam gevolgd door de filenaam of postgres-naam. Per NT-Versie bestaat er een DB.
    • host: string, van belang voor postgres
    • password: string, van belang voor postgres
    • port: int, van belang voor postgres
    • user: string, van belang voor postgres
  • logging
    • maindir: string, in welke directorie moeten de logs worden opgeslagen
    • xbrl_cli: string, bestandnaam (zonder directorienaam) voor de logging van de parser via web of cli
  • parser
    • local_taxonomy_dir: string, dit is de locatie waar de zipfiles worden uitgepakt.
    • thread_count: int, dit is een lichte server, laat maar lekker op 1 staan. Op localhost werk ik met 4 threads.
  • project_root, waar draait de applicatie. Normaal gesproken is ".." voldoende. Op de server heb ik deze vastgezet op /app/kenniscentrum_xbrl/discover_xbrl
  • validator
    • autocommit_reports: boolean, de raportgenerator kan met git werken om versiehistorie van de rapporten bij te houden (handig bij het aanpassen van de validatieregels). Op de server werken we zonder git.
    • default: string, wijst naar de directorie/module die de validator moet gebruiken.
    • report_dir: string, waar schrijven we rapporten? Door in de webdir te schrijven worden ze gelijk zichtbaar op het web.
    • write_report: boolean, je kan de validator ook zonder rapport draaien. Handig? op localhost, op de server staat deze aan.

Er staan meer configuratievariabelen in het bestand, veel daarvan hebben te maken me tde builder en vallen buiten scope van het huidige project.

API

De API werkt op de database. Als die inhoud heeft, dan is het mogelijk om de delen van de taxonomie via het web op te vragen. Op de server draait als het goed is de API altijd. De documentatie van de verschillende requests kan je in de swagger documentatie redoc of swagger nalezen.

De API is opgedeeld in twee delen; het opvraag gedeelte, delen van de NTA in JSON-Formaat en de admin. Het eerste deel wordt door nginx gecachet, de admin niet. De gehele admin-workflow gaat langs/door de API.

Deployment

In de toekomst zal je wijzigingen in de code moeten aanbrengen; een ministerie wijzigt van naam (VenJ => JenV), een jaartal wijzigt, een nieuwe namespace of een NTA-Regel vervalt om een paar voorbeelden te noemen. In al die gevallen zal er een wijzigingen in de source moeten gebeuren. Als die wijzigingen zijn gedaan en naar gitlab gepusht is het zaak de code op de server te krijgen. Log in op de server met SSH, we willen een terminal, en voer vervolgens uit:

cd /app/kenniscentrum_xbrl/
make toolkit

Dit zal achtereenvolgens een nieuwe versie van de code downloaden van gitlab (master), en de server herstarten. De logfile (/var/log/toolkit/api_server.log) wordt een versie lang bewaard als api_server.log.1 en leeggemaakt.

In de makefile staat nog enkele targets, met make list laat je zien welke er allemaal gedraaid kunnen worden.

make rebuild_cache

Het kan voorkomen dat je een aanpassing aan de toolkit hebt gedaan waardoor de JSON die de API antwoordt is veranderd. Dit ga je niet direct zien op de server omdat daar cache van elke JSON bestaat. Door dit target uit te voeren zal je wijziging ook op de server zichtbaar worden. Let op, dit is een zeer langdurig proces, momenteel duurt dit langer dan 48 uur. De site blijft werken, maar de kans bestaat de een bezoeker heel lang op antwoord moet wachten.

make sitemap

Om de crawlers een handje te helpen schrijven we een sitemap. Na het inlezen van nieuwe taxonomieen kan je dit target draaien, dan worden de nieuwe entrypoints toegevoegd aan de sitemap.

make restart Soms gaat er op de server iets mis en blijft er een parser 'hangen'. Voor die gevallen is het voldoende om de API opnieuw op te starten (zonder een nieuwe versie te deployen). Make restart doet precies dat.