Webhook trickle loading inschakelen voor OEM-licenties

Samenvatting

Gegevensreplicatie met behulp van trickle loading op Invantive Data Replicator (zowel OEM als regulier) kan de belasting van het Exact Online-ecosysteem aanzienlijk verminderen en de replicatietijd voor Exact Online-tabellen verkorten. Deze notitie biedt een aanpak en praktische query’s om gegevensreplicatie voor grote aantallen bedrijven en klanten eenvoudig op te zetten en te onderhouden. De aanpak schaalt tot boven de 5.000 bedrijven, mits er voldoende resources beschikbaar zijn.

Prestaties van gegevensreplicatie en OEM

Invantive Data Replicator wordt steeds vaker ingezet in grote omgevingen, met datavolumes van meer dan 1 terabyte. Het gaat doorgaans om duizenden partities van platforms zoals Exact Online-administraties, Loket-salarisadministraties of Visma.net-administraties. Gegevensreplicatie moet een of beide van de volgende doelen bereiken:

  • De prestaties van query’s verbeteren, met minder belasting van API-ecosystemen.
  • Het gebruik van tools mogelijk maken die geen ondersteuning bieden voor Invantive SQL-drivers of ADO.NET.

Het replicatieproces zelf kan, gezien het aantal partities (administraties) en de hoeveelheid data, een flinke belasting vormen voor je cloudpartners. Daarom biedt Invantive een aantal optimalisatiestrategieën om de replicatietijd te verkorten en tegelijk de belasting van het API-ecosysteem van je leverancier te verminderen.

De meest gebruikte methode is „trickle loading". Trickle loading is een incrementele strategie: na het initieel laden van een volledige dataset worden alleen nog wijzigingen toegepast, bestaande uit deletes, inserts en updates.

De informatiestroom vanuit cloudplatforms met trickle loading wordt hieronder weergegeven als de afwijkende stroom via „Receivers":

Vooral bij grote datasets is slechts een klein percentage „hot", terwijl alle overige data „at rest" staat en wordt bewaard voor de toekomst.

Bij cloudplatforms worden deze wijzigingen (deltas) doorgaans ontleend aan webhook-events. Bij databaseplatforms worden deze wijzigingen doorgaans ontleend aan database-triggers en/of transactielogs, zoals Oracle redo logs.

Specifiek bij OEM-implementaties zijn er doorgaans tientallen omgevingen die één OEM-licentiecontractcode delen. Daarnaast wordt vaak hosting aangeboden aan klanten die hun eigen Invantive-licentie meebrengen („BYOL" of „Bring Your Own License"). Het configureren en automatisch onderhouden van webhooks in dergelijke omgevingen vraagt om extra zorg, om te voorkomen dat werkzaamheden steeds opnieuw moeten worden uitgevoerd wanneer er administraties worden toegevoegd.

De volgende code helpt je bij het optimaliseren van de activering en het onderhoud van trickle loading voor grote aantallen verschillende klanten die via OEM worden bediend. We hebben webhooks op Exact Online gebruikt om de code te illustreren.

Standaardgebruik van trickle loading (webhooks)

Het standaardgebruik van trickle loading wordt uitgelegd in een ander onderwerp, maar dit zijn de algemene stappen:

Instellen

Voor reguliere implementaties voor intern gebruik, met weinig wijzigingen in de aangesloten cloudplatforms en 1 of 1.000 partities, wordt trickle loading doorgaans eenmalig geactiveerd met de volgende instructie per tabel:

--
-- Selecteer alle in aanmerking komende bedrijven/partities.
--
use all

--
-- Schakel trickle loading in voor een specifieke tabel.
--
alter persistent cache set table NAME approach trickle

gevolgd door het eenmalig instellen van de Invantive Data Replicator-token die wordt gebruikt voor authenticatie bij het downloaden van events, met:

alter persistent cache set token = 'value'

Feed met events downloaden

Nadat deze wijzigingen zijn doorgevoerd, bevat het regelmatig uitgevoerde Invantive SQL-replicatiescript doorgaans ergens bovenaan een instructie om nieuwe events te downloaden:

alter persistent cache download feed

Automatische activering van trickle loading (webhooks) voor OEM

Het volgende Invantive PSQL-blok schakelt trickle loading in voor alle geselecteerde partities (zoals Exact Online-administraties), beperkt tot de gerepliceerde tabellen die webhooks ondersteunen.

Voorbeeldcode in Invantive PSQL:

begin
 for r_trickle in
 ( --
   -- Activeer trickle loading voor alle tabellen waarvoor
   -- trickle loading beschikbaar is maar nog niet geactiveerd.
   --
   -- Selecteert alle gerepliceerde tabellen die webhooks ondersteunen (en
   -- dus trickle loading). Beperk
   -- tot de tabellen die één of meer tabelpartities hebben
   -- (zoals Exact Online-administraties) waarvoor trickle loading
   -- nog niet is geactiveerd.
   --
   -- Verwachte uitvoeringstijd bij de eerste run in seconden: 5 keer het aantal partities (administraties).
   -- Verwachte uitvoeringstijd na de eerste runs in seconden: 1.
   --
   select distinct
          'alter persistent cache set table '
          || tbe.tbe_full_qualified_name
          || '  approach trickle'
          stmt
   from   dc_tables@datacache tbe    
   join   dc_table_partitions@DataCache tpn
   on     tpn.tbe_id = tbe.tbe_id
   and    tpn.tpt_seeding_approach_used_code = 'C' /* Volledig. */
   join   SYSTEMTABLES@DataDictionary ste
   on     ste.full_qualified_name = tbe.tbe_full_qualified_name
   and    ste.webhook_topic is not null
   --
   -- Sla alle XML-tabellen over, aangezien geen enkele daarvan
   -- toch webhooks heeft.
   --
   where  tbe.tbe_full_qualified_name like '%REST%'
 )
 loop
   execute immediate r_trickle.stmt;
 end loop;
end;

Wanneer webhooks niet beschikbaar zijn, kun je de smart sampling-aanpak overwegen. Als alternatief kun je, wanneer tabellen meer dan 50.000 rijen bevatten en server-side filtering beschikbaar is, query’s van het volgende type gebruiken om de replicatieprestaties te verbeteren:

create or replace table REPLICA@DATABASE
as
select ... from OLD
union
distinct on PK
select ... from NEW where MODIFIED > date

Een ander alternatief is het gebruik van de synchronize-instructie, die de inhoud van de twee tabellen op elkaar afstemt. Raadpleeg de SQL-grammatica voor meer instructies.

Berichten downloaden voor OEM

Een webhook-event leidt ertoe dat berichten worden geregistreerd door Invantive Cloud in een wachtrij. De inhoud van deze wachtrij kan worden gedownload en verwerkt door Invantive Data Replicator.

Bij OEM’s moet, om ervoor te zorgen dat de juiste berichten worden gedownload, de data-container-ID worden meegegeven bij het downloaden. Anders zal de eerste omgeving alle berichten downloaden. Deze berichten worden dan niet verwerkt, maar door ze te downloaden worden ze wel onbeschikbaar voor de overige omgevingen.

Voorbeeldcode in Invantive PSQL:

declare
 l_license_contract_code varchar2 := 'L9999999999';
 l_secret_token          varchar2 := 'secret';
begin
 --
 -- Verwachte uitvoeringstijd: 1 seconde per 1.000 berichten.
 --
 for r_dcr
 in
 ( select 'alter persistent cache download feed LICENSE CONTRACT CODE '''
          || l_license_contract_code
          || ''''
          || ' token '''
          || l_secret_token
          || ''''
          || ' datacontainer '''
          || dcr.dcr_name
          || ''''
          stmt
   from   ( select distinct
                   dcr.dcr_name
            from   dc_table_partitions@DataCache tpn
            join   dc_tables@DataCache tbe
            on     tbe.tbe_id = tpn.tbe_id
            join   dc_data_containers@DataCache dcr
            on     dcr.dcr_id = tbe.dcr_id
            where  tpn.tpt_seeding_approach_used_code = 'T'
          ) dcr
   order
   by     dcr.dcr_name
 )
 loop
   execute immediate r_dcr.stmt;
 end loop;
end;

Webhook-stormen

Exact Online kent „webhook-stormen". Gebeurtenissen zoals het herstellen van een back-up, upgrades of het afsluiten van periodes bij grote administraties kunnen binnen een uur miljoenen berichten veroorzaken. Er wordt geen zinvolle rate limiting toegepast, dus als je webhook-ontvanger niet goed is ontworpen, kan deze een soort „Distributed Denial of Service"-aanval ervaren.

Invantive Cloud kan 10 miljoen events per uur verwerken. Bij overschrijding worden events gethrottled en gespreid over tijd afgehandeld. Als er bijvoorbeeld binnen 60 minuten 100 miljoen events plaatsvinden verspreid over 20.000 Exact Online-administraties, heeft Invantive 10 uur nodig om bij te werken en de events voor je beschikbaar te maken.

Het gemiddelde aantal afgeleverde webhook-events is echter 50.000 per uur, slechts 0,5% van de maximale verwerkingscapaciteit. Webhook-stormen komen wel voor, maar zullen zelden de ontvangst van je events door Data Replicator significant vertragen.

Deduplicatie van meerdere events

Het is bekend dat Exact Online meerdere events veroorzaakt voor één wijziging. Zo wordt er bijvoorbeeld voor de transactiekop een webhook-event verzonden voor elke regel die in een transactie voorkomt. Dit is in de loop der tijd verbeterd en momenteel zien we vrijwel geen duplicaten meer. Eventuele overtollige duplicaten worden automatisch gededupliceerd door Invantive Cloud, mits ze binnen een instelbaar tijdsinterval worden ontvangen. Het tijdsinterval staat standaard ingesteld op 15 minuten.

Tokenbeveiliging voor OEM

De token om de feed met events op te halen wordt doorgaans persistent opgeslagen in de Data Replicator-repository, zodat deze kan worden opgehaald vanuit batchjobs, met:

alter persistent cache set token = 'value'

Sommige OEM’s geven hun eindgebruikers echter directe toegang tot de Data Replicator-repositorydatabase. Toegang tot de token zou een extra element voor een aanvalsvector kunnen vormen.

Daarom wordt de token in dit voorbeeld niet persistent in de database opgeslagen. In plaats daarvan wordt de token in het script opgeslagen. Je kunt de standaard device-key-encryptie op de tokenstring toepassen voor extra beveiliging. Bij Exact Online is dit over het algemeen niet nodig, omdat Exact Online-webhooks weinig tot geen daadwerkelijke bedrijfsinformatie bevatten.

Activering van trickle loading controleren

Bij Exact Online kun je de momenteel geactiveerde webhooks controleren met WebhookSubscriptions:

select /*+ ods(false) http_disk_cache(false) http_memory_cache(false) */
      *
from   WebhookSubscriptions

Bijvoorbeeld:

Routering van webhook-events controleren

Na de initiële activering van trickle loading bij Exact Online duurt het enige tijd voordat de daadwerkelijke replicatie plaatsvindt via incrementele trickle loading in plaats van een volledige kopie. Invantive Data Replicator heeft een heartbeat-signaal van Exact Online nodig om de lus te sluiten. Zolang er geen berichten zijn ontvangen voor webhook-events op een combinatie van Exact Online-administratie (partitie) en gerepliceerde tabel, blijft de replicatie een volledige kopie gebruiken om gegevensverlies te voorkomen.

De volgende code helpt je de lus voor het ontvangen van events te testen, door een element in Exact Online-accounts te wijzigen en te controleren of het bijbehorende bericht binnenkomt:

--
-- Test het ophalen van berichten, bijvoorbeeld met accounts.
--
update exactonlinerest..accounts 
set    name = name || '!' 
where  name like 'Belastingdienst%'
 
--
-- Wijziging ongedaan maken.
--
update exactonlinerest..accounts 
set    name = replace(name, '!', '') 
where  name like 'Belastingdienst%!'
 
--
-- Vervolgens:
-- * Wacht 3 minuten.
-- * Voer de bovenstaande download feed uit.
-- * Controleer de inhoud van de inkomende berichten.
--
select *
from   dc_incoming_messages@DataCache

Bijvoorbeeld:

Als je de lus handmatig wilt forceren te sluiten, neem dan contact op met een consultant.