Data retentie in YAVC

Bij data rententie gaat het om de vraag: hoe lang moet data worden opgeslagen? Bij gebruik van YAVC over een langere periode, zal het ruimtebeslag van de data steeds verder toenemen. Dit leidt onherroepelijk dat de vraag: welke data moet hoe lang worden behouden?

YAVC biedt een aantal mogelijkheden voor dataretentie, ofwel het bepalen van de duur van de opslag van data. Retentie van data is binnen YAVC van toepassing voor de navolgende typen data:

  • VLOG data: dit is dus de brondata, zoals die wordt opgehaald van de verkeersregelautomaten, en wordt gebruikt voor de weergave van de fasenlog.
    • Filtering/validatie data: dit betreft informatie over de validiteit van detectormeldingen in de VLOG data; deze informatie wordt gebruikt om de betrouwbaarheid van de analysedata te verbeteren.
  • Analysedata: dit betreft afgeleide data, waarbij op basis van de VLOG data diverse grootheden worden doorgerekend, zoals intensiteiten, roodrijders, cyclustijden, wachttijden, et cetera.
  • Evaluatiedata: het is binnen YAVC (met een extra module) mogelijk op basis van de uitkomsten van de analyses evaluatiegegevens te berekenen, zoals rapportcijfers.
  • Overige data: hierbij gaat het om logging van foutmeldingen, bijhouden van ophalen bestanden.
  • Voor alle overige data in YAVC (dit betreft in hoofdzaak configuratie gegevens) wordt geen dataretentie toegepast.

Bij de omgang met retentie van data binnen YAVC zijn er een aantal mogelijke werkwijzen denkbaar:

  • Globale dataretentie: wanneer dit is ingeschakeld, is de bewaartermijn voor alle typen data binnen het systeem gelijk.
  • Opgesplitste dataretentie: het is ook mogelijk, per typedata afzonderlijk te bepalen hoe lang deze bewaard moet worden.
    • Middels opgesplitste dataretentie is het bijvoorbeeld mogelijk ruwe VLOG data langer te bewaren dan de analysedata, of juist andersom.
    • Bij opgesplitste dataretentie is het mogelijk per type analyse af te wijken van de globaal ingestelde bewaartermijn voor analysedata: zo kunnen bijvoorbeeld intensiteitgegevens langer worden bewaakt dan overige analysedata, of kan bepaalde analysedata juist korter worden bewaard.
  • Afwijken per intersectie: bij de configuratie van een intersectie is het mogelijk afzonderlijke instellingen op te geven voor dataretentie voor die specifieke intersectie. LET OP: dit staat in dat geval geheel los van de instellingen op niveau van YAVC als geheel, en wordt ook dan toegepast wanneer dataretentie globaal is uitgeschakeld.

De mogelijke instellingen voor data retentie binnen YAVC client worden hieronder weergegeven:

De volgende instellingen zijn hier beschikbaar (waarmee de diverse mogelijkheden zoals hierboven toegelicht kunnen worden ingeregeld):

  1. Globale data retentie: instellen van het aantal dagen dat data globaal wordt bewaard. Data ouder dan deze instelling wordt dagelijks (’s nachts) verwijdert; dit betreft dan dus VLOG data, analyse data, en evt. evalautie data
    • De opties hieronder zijn enkel dan beschikbaar wanneer globale dataretentie is uitgeschakeld
  2. VLOG dataretentie: instellen van het aantal dagen dat ruwe VLOG data wordt bewaard. Let op: is de VLOG data eenmaal weg, dan kan er geen analysedata meer worden (her)berekend.
    • Merk op: in tegenstelling tot de labels bij de vinkjes in deze afbeelding, geldt de bewaartermijn van analysedata niet voor filtering; filtering is zonder VLOG data nutteloos; daarom geldt bewaartermijn voor VLOG data ook voor filtering. Vanaf versie 4.0.3 van de client is dit gecorrigeerd.
  3. Analyse dataretentie: instellen van het aantal dagen dat analysedata moet worden bewaard.
  4. Specifieke dataretentie per type analyse: indien retentie van analysedata is ingeschakeld, kan je desgewenst per typeanalyse worden afgeweken van de algemene ingestelde bewaartermijn. Zowel een kortere als een langere termijn is mogelijk.
  5. Evaluatie dataretentie: instellen van het aantal dagen dat evaluatiedata bewaard moet worden.
  6. Overige retentie-instellingen: hier worden ingesteld hoe lang error logging moeten worden bewaard, alsook de records van geïmporteerde bestanden.
    • Periodiek opschonen hypertables: wanneer in YAVC analysedata worden herberekend, kan het leiden tot fragmentatie in de database. Deze optie zorgt ervoor dat periodiek (één keer per week) de betreffende tabellen worden nagelopen, en fragmentatie waar nodig wordt verholpen. Dit belast de server enigszins, maar kan zorgen voor vermindering van het ruimtegebruik.

Bulk export analyse in YAVC client

In YAVC client is het mogelijk analyse data in bulk te exporteren. Zo kan over een langere periode voor meerdere VRI’s in één keer data worden geëxporteerd. Bij de export betreft het data per (gedeelte van een) dag. Export van gemiddelden of trends is momenteel niet mogelijk in bulk vorm.

Om gebruik te maken van de bulk export optie: open het werkblad via menu Tools > Bulk Export:

Bij (1) kunnen nu één of meer kruispunten worden geselecteerd. Vervolgens wordt bij (2) ingesteld op welke wijze precies welke data moet worden geëxporteerd:

  • Start: begin van de te exporteren periode
  • Eind: einde van de te exporteren periode (exclusief, dus tot, niet tot-en-met)
  • Weekdagen: welke dagen van de week doen mee in de export
  • Geen feestdagen: indien aangevinkt, worden als feestdag geconfigureerde datums overgeslagen bij de export (vanaf YAVC client versie 3.8.1)
  • Geen schoolvakanties: indien aangevinkt, worden als schoolvakantie geconfigureerde datums overgeslagen bij de export (vanaf YAVC client versie 3.8.1)
  • Tijd per dag start: start moment van de export, per dag die binnen de opgegeven periode ligt; zo kan dus bv. de ochtend- of avondspits worden geëxporteerd over een langere periode.
  • Tijd per dag eind: eind moment van de export (exclusief), per dag die binnen de opgegeven periode ligt
  • Analyse: het type analyse data dat moet worden geëxporteerd (momenteel kan enkel vooraf doorgerekende analyse data worden geëxporteerd, dus geen “realtime” data).
  • Type data weergave: indien van toepassing kan hier worden opgegeven hoe de data moet worden geëxporteerd; bij Wachttijd eerstwachtende kan bv. een gemiddelde per interval, of het maximum per interval worden geëxporteerd. Dit is niet bij alle typen analyses relevant.
  • Interval: het tijdsinterval om te gebruiken bij de export
  • Export locatie: waar de export terecht moet komen op schijf
  • Bestanden: per dag, of alle data onder elkaar in één bestand

Via de knop “Start export” bij (3) kan vervolgens de export worden gestart. De voortgang wordt ook getoond. In het tabblad “Export log” worden eventuele meldingen getoond, bv. indien voor een VRI (deels) geen data beschikbaar is binnen de ingestelde periode die moet worden geëxporteerd.

Ophalen niet-VLOG data

Met YAVC is het mogelijk data op te halen anders dan VLOG data, zoals bijvoorbeeld andere typen logging data die een VRI aanmaakt. De betreffende data kan geautomatiseerd worden ophaald en wordt dan opgeslagen op de server waar YAVC draait op een aangewezen locatie. Via de mogelijkheid tot het raadplegen van het server archief (YAVC client menu Tools > Server archief) kan de opgeslagen data worden opgehaald naar een lokaal systeem voor verdere verwerking.

Om gebruik te maken van deze mogelijkheid moet het volgende worden geconfigureerd in YAVC:

  • Bij systeeminstellingen (uitklappen “Instellingen geavanceerde data verzameling”, dit zit onder de reuguliere instellingen) moet worden ingesteld waar op de server de op te halen data moet worden opgeslagen
    • Merk op: momenteel moet na een wijziging van deze instelling de bestanden-verzamelaar (file-hamster) van YAVC worden geherstart, anders komt de wijziging niet door

Per VRI moet vervolgens worden ingesteld welke data moet worden opgehaald, en hoe deze moet worden opgeslagen:

Merk op: sinds versie 3.5 van de client geldt: er is een extra optie “Periodiek opnieuw verzamelen”; deze komt beschikbaar indien “Timestamp voor bestandsnaam zetten” is aangevinkt. “Check timestamp vorige file” komt pas beschikbaar indien periodiek opnieuw verzamelen is ingeschakeld.

De volgende instellingen zien hierbij relevant:

  • Welke connectie configuratie gebruikt moet worden [1] (kan zijn van type ftp, sftp of monitored-folder). Deze kan dus afwijken van de verbinding via welke de VLOG data worden opgehaald
  • Een of meer typen data om op te halen [2]; er kunnen dus meerdere typen data worden opgehaald, waarbij per type een regel in deze lijst moet worden aangemaakt
  • Per type op te halen data moet het volgende worden ingesteld [3]:
    • De extensie – let op ! gebruik één extensie per type, zonder wildcards
    • Pad naar de data op de VRI
    • Timestamp voor bestanden zetten – indien aangevinkt, plaatst YAVC voor opgehaalde bestanden een timestamp van het moment van ophalen met het formaat yyyyMMddTHHmmss, bv.: 20230117T093900
    • Periodiek opnieuw verzamelen – dit is alleen beschikbaar indien het voorgaande vinkje aan is (timestamp voor bestandsnaam zetten). Indien aangevinkt, wordt data elke ronde opnieuw verzameld, ook als een bestand met dezelfde naam reeds eerder is opgehaald. Let op! Dit kan zeer veel data opleveren, gebruik daarom evt. de navolgende optie om hetverzameling in te perken.
    • Check timestamp vorige file – dit is alleen beschikbaar indien het voorgaande vinkje aan is (periodiek verzamelen data). Indien aangevinkt, wordt vóór download eerst bekeken of er reeds eerder een bestand met deze naam is opgehaald (de timestamp voor de bestandsnaam wordt hierbij genegeerd). Zo ja, dan wordt middels de voorgevoegde timestamp nagekeken of er genoeg tijd verstreken is sinds de voorgaande download; zo ja, dan wordt opnieuw gedownload, zo nee gebeurt er niets
    • Minimale leeftijd vorige bestand (min.) – niet zichtbaar in bovenstaand plaatje, deze optie komt tevoorschijn wanneer ‘Check timestamp vorige file’ wordt aangevinkt; hier wordt ingesteld hoe lang geleden (in minuten) het ophalen van de voorgaande file minimaal moet zijn, voor er een nieuwe versie wordt opgehaald
    • Opslaan in jaar/maand/dag mappenstructuur – indien aangevinkt worden opgehaalde bestanden geplaatst in een map per dag, zoals ook gebeurt met VLOG data. Bv: …/K1/2023/01/17.
    • Bestand op VRI verwijderen – indien aangevinkt wordt na download het bestand op de server ofwel de VRI verwijderd
    • Pad is absoluut – indien aangevinkt geldt het ingestelde pad als absoluut; bij wisselen van map wordt dan dus niet het huidige pad (waar de client/YAVC komt na inlog op de serve/VRI) als uitgangspunt gebruikt, maar wordt gepoogd direct naar de ingestelde locatie te manouevreren.

Merk nog op: er vindt momenteel geen data retentie plaats op de opgehaalde data. Dit betekent, mede afhankelijk van de aard van de opgehaalde data en de instellingen, dat het archief met data langzaam zal groeien. Dit is iets om rekening mee te houden bij het dimensioneren van de opslagruimte op de server. Op aanvraag kan CodingConnected retentie uitvoeren op de opgehaalde data.

YAVC: beveiliging public API

Binnen YAVC is een publieke API beschikbaar, waarmee meta data rond kruispunten en analyse data kan worden ontsloten naar andere applicaties. De API heeft de volgende kenmerken:

  • RESTful API
  • Beveiligd middels OAuth2
  • Beschikt over ingebakken documentatie (“swagger”)
  • Kan de volgende data ontsluiten:
    • Meta data van kruispunten (naam, straatnamen, ligging, etc.; inclusief gebruikers meta data)
    • Beschikbaarheid van analyse data
    • Lijst met beschikbare analyses (incl. id’s, die nodig zijn voor opvragen van de eigenlijke data)
    • Analyse data, voor een bepaald type analyse, een gewenste periode in de tijd, voor een opgegeven interval (bv. 15 min.)

Zie voor details over de publieke API dit artikel.

Beveiliging: OAuth2 en TLS

De API is beveiligd middels OAuth2, wat met behulp van een externe identity provider geconfigureerd moet worden. Data wordt in principe altijd versleuteld tussen de API en de ontvanger. Hierbij geldt:

  • De API maakt gebruik van OAuth2 voor de authenticatie
  • Er wordt geen gebruik gemaakt van authorisatie
  • Er wordt gebruik gemaakt van de client credentials flow
  • Versleuteling gebeurt met een certificaat en gebruikt TLS1.2

Het OAuth2 gedeelte moet worden geconfigureerd in de externe identity provider (IdP). Dit is vaak Azure Active Directory (AzureAD), maar kan ook een andere provider zijn (zoals Auth0, ADFS, KeyCloak, etc.). Om een externe applicatie toegang te geven tot de API is in hoofdlijnen nodig:

  • Configureren van de API in de IdP (dit is het “audience” a.k.a. “resource”)
  • Configureren van de externe app in de IdP
  • De externe app permissie geven tot het gebruiken van de API

Hieronder volgt een voorbeeld van een configuratie in AzureAD ter referentie:

  • Log in op de Azure Portal
  • Ga naar “Active Directory”
  • Ga naar “App registrations”
  • Hier moet de publieke API worden toegevoegd: klik op “New registration” en geef de API een herkenbare naam. Stel de API registration als volgt in:
    • Kies bij “Redirect URI” de waarde “Web” en stel de correcte callback URI in
    • Klik register
    • Stel bij “Authentication” in: “Allow public client flows” = No
    • Voeg via “Expose an API” een scope toe; er moet één scope zijn (naam is om het even, bv. “read”, de API is sowieso alleen-lezen)
    • Belangrijke informatie voor de configuratie van YAVC is:
      • Application ID van de app (tbv. juiste configuratie van de scope)
      • Directory/tenant ID (tbv. check of de token van de juiste plek komt)
      • Deze informatie heeft CodingConnected dus nodig om de API server-side correct te kunnen configureren
  • Voeg op dezelfde manier een tweede app toe, nu voor de externe applicatie die toegang moet krijgen tot de API; geef de app een herkenbare naam. Stel de app als volgt in:
    • Redirect URI is hier niet nodig
    • Klik register
    • Voeg bij “Certificates and secrets” een secret toe
    • Geef de app toegang tot de API:
      • ga naar “API permissions”
      • Klik “Add a permission”
      • Klik “My APIs” en kies de eerder aangemaakte API app uit
      • Klik onder “Permissions” de enige aangemaakte scope aan (bv: read)
    • Belangrijke informatie voor de configuratie van de externe app is:
      • Application ID van de app (dus van de nieuwe, externe app, niet van de API!)
      • Object ID van de API app (hier dus juist wél van de API! Dit is tbv. juiste configuratie van resource/audience)
      • Het aangemaakte secret
      • OAuth2 token endpoint (klik op “Endpoints” om dit weer te geven)

De uiteindelijke configuratie voor een externe applicatie is bijvoorbeeld als volgt (screenshot uit de test app insomnia):

YAVC-client: bitmap bij actieve kruispunt

In YAVC-client is het mogelijk een ingestelde bitmap (afbeelding) weer te geven die hoort bij de actieve intersectie. Actief betekent in deze context: de intersectie van de geselecteerde fasenlog of het geselecteerde analyse werkblad. De weer te geven bitmap moet eerst zijn ingesteld bij de analyse configuratie die hoort bij de weergegeven data; bij kiezen van een andere dag, met een andere bijbehorende analyse configuratie kan de weergegeven bitmap dus veranderen.

Instellen bitmap bij analyse configuratie

Voor een bitmap kan worden weergegeven, moet deze eerst worden geconfigureerd. Dit gaat in twee stappen:

  • Toevoegen van een bitmap databron aan de kruising
  • Toewijzen van de betreffende bitmap aan een analyse configuratie

Toevoegen van een bitmap databron

Bij kruispunten in YAVC kunnen (sinds YAVC-client versie 3.x) databronnen bij kruispunten worden opgeslagen. Hier kunnen onder meer bitmaps worden opgeslagen. Open hiertoe het instellingen werkblad (systemadmin niveau is noodzakelijk!), selecteer een kruispuint, en klik dan op het tabblad “Data bronnen”:

Om een bitmap toe te voegen:

  • Selecteer in de lijst onder de knoppen “Toevoegen” en “Verwijderen” het type “Bitmap”
  • Klik nu op “Toevoegen” (de muispijl staat hierop in de afbeelding)
  • Er wordt een nieuwe bitmap toegevoegd, evenwel nog zonder bijbehorende data
  • Geef de bitmap een omschrijving via het tekstvak boven de bitmap weergave
  • Klik op “Laden” en zoek de gewenste bitmap op op schijf
  • Klik tenslotte op “Opslaan”

Toewijzen van een bitmap aan een analyse configuratie

Kies het tabblad “VLOG configuraties” van de betreffende kruising en klik vervolgens op de configuratie waarvoor een bitmap moet worden ingesteld. Klik daarna op het tabblad “Varia” en dan op “Bronnen bij configuratie”:

Kies nu de gewenste bitmap en klik vervolgens op “Opslaan”. Let op: kies bij de vraag om wel/niet te herberekenen: Nee. Herberekenen is in dit geval niet nodig, want er verandert inhoudelijk niets aan de analyse configuratie.

Weergeven van bitmap bij actieve kruispunt

Is voor een kruispunt voor één of meer analyse configuraties een bitmap ingesteld, dan kan deze worden weergegeven in YAVC-client wanneer van die kruispunt data wordt weergegeven die valt binnen de periode waarvoor de betreffende analyse configuratie geldig is.

Klik hiertoe in het menu op Beeld>Tool vensters>Weergeven bitmap:

Of gebruik de snelkoppeling op de toolbar.

Er verschijnt nu een toolvenster, dat middels de multi-venster omgeving van YAVC-client op de gewenste plek kan worden geplaatst, of als zwevend venster weergegeven kan worden. In het toolvenster kan met het muiswiel worden gezoomed, alsook met Shift+Linksklik-vasthouden+Slepen, en vervolgens met Linksklik-vasthouden worden gesleept.

Bij wisselen van actief werkblad, zal ook de weergegeven bitmap worden gewijzigd. Indien geen bitmap beschikbaar is voor de actieve data, wordt hiervan melding gemaakt. Indien meerdere werkbladen met data naast/boven elkaar worden weergegeven zal van het laatste werkblad waarin/waarop is geklikt de bitmap worden weergegeven.

De positie van het bitmap weergave toolvenster wordt opgeslagen bij sluiten/herstarten van YAVC-client. Een uitzondering hierop vormt een zwevend venster, dit kan momenteel niet worden hersteld.