Integration Control Center

Integration Control Center is het centrale werkgebied voor integratiebeheer binnen ERP-NL. De Nederlandse UI-labels gebruiken meestal Integratiebeheer of Integratie. Het doel is dat normale integratieverwerking automatisch herstelt en dat alleen echte uitzonderingen werk voor een beheerder worden.

Wat kun je met Integration Control Center?

Met Integration Control Center kun je:

• technische connecties en credentialmetadata beheren zonder secrets buiten de bestaande versleutelde opslag te halen;
• functionele integratiedefinities beheren met eigenaar, contract, mapping, flow en SLA-context;
• berichtcontracten en mappings versieerbaar beheren;
• veilige flowstappen configureren zonder vrije code-uitvoering;
• verwerkingen volgen met correlation ID, idempotency key, status en foutstap;
• uitzonderingen toewijzen, repareren, opnieuw verwerken of oplossen;
• impact analyseren voordat een connectie, mapping, flow of contract wijzigt;
• externe ingestflows via de Public API laten binnenkomen.

Belangrijkste schermen

Scherm	Route	Doel
Connecties	/setup/integration/connections	Technische endpoint- en credentialmetadata beheren
Integraties	/setup/integration/definitions	Functionele integratiedefinities beheren
Contracten	/setup/integration/contracts	Berichtcontracten, schema's, versies en gebruik bekijken
Mappings	/setup/integration/mappings	Mappingversies maken, testen en activeren
Flows	/setup/integration/flows	Veilige flowversies en stappen beheren
Webhooks	/setup/integration/webhooks	Outbound webhookabonnementen beheren
Oracle uitgaand	/setup/integration/oracle-outbound	Oracle outbound targets beheren
Verwerkingen	/monitoring/integrations/verwerkingen	Runtime verwerkingen volgen
Uitzonderingen	/monitoring/integrations/uitzonderingen	Integratie-uitzonderingen opvolgen

Concepten

Concept	UI-label	Betekenis
Connection	Connectie	Technisch endpoint, transport, authenticatietype en operationele metadata
IntegrationDefinition	Integratie	Functionele integratievariant met bron, doel, eigenaar, contract, mapping en flow
Canonical Contract	Berichtcontract	Gestandaardiseerde payloadvorm, bijvoorbeeld PaymentInstructionBatch.v1
Mapping	Mapping	Configuratie die bronvelden omzet naar het doelcontract
Flow	Flow	Veilige reeks stappen voor validatie, transformatie en serviceaanroep
IntegrationExecution	Verwerking	Eén technische verwerkingspoging
IntegrationException	Integratie-uitzondering	Beheerwerkitem nadat automatische recovery is uitgeput of niet zinvol is

Procesoverzicht

flowchart LR
  Source[Extern systeem] --> PublicApi[Public API ingest]
  PublicApi --> Definition[Integratie]
  Definition --> Contract[Contractvalidatie]
  Contract --> Mapping[Mapping]
  Mapping --> Flow[Flow]
  Flow --> Service[ERP-NL service]
  Service --> Execution[Verwerking]
  Execution --> Retry{Retrybaar?}
  Retry -->|Ja| AutoRetry[Automatische retry]
  Retry -->|Nee| Exception[Uitzondering]
  AutoRetry --> Execution
  Exception --> Replay[Repair en replay]

Het eerste prototype is Oracle EBS naar PaymentInstructionBatch.v1. De flow valideert de inbound payload, transformeert deze via de actieve mapping en roept daarna de bestaande PaymentInstructionBatch-importservice aan.

Connecties

Connecties leggen metadata vast rond technische verbindingen. Secrets blijven in de bestaande versleutelde integration_settings-opslag; int_connections bevat geen geheime waarden.

Connecties tonen onder meer:

• code en naam;
• systeemtype, transport en authenticatietype;
• omgeving;
• eigenaar;
• laatste controle;
• actieve configuratieversie;
• geplande wijziging;
• afhankelijke integraties.

Een tenant-scoped setting-upsert kan ontbrekende connectiemetadata automatisch aanmaken. Globale fallback-settings blijven in integration_settings en worden geen tenantloze connecties.

Integraties

Een integratiedefinitie beschrijft de functionele variant: bron, doel, berichttype, contract, mapping, flow, eigenaar, status en afhankelijkheden. Integraties kunnen gepauzeerd en hervat worden.

De Integraties-lijst is bewust licht: paginering, filters en zoeken draaien server-side en de lijst laadt geen verwerkingen, readiness of volledige versiehistorie per rij. De lijst toont configuratiestatus, niet runtime-status. Een rij openen toont direct een bewerkdialoog. Diezelfde dialoog haalt recente verwerkingen en readiness op, zodat bekijken en bewerken niet over twee popups verdeeld zijn. Geen verwerkingen wordt als Geen verwerkingen getoond; laadfouten blijven herkenbare fouten.

Een filterwijziging begint op de eerste pagina. Alle ondersteunde omgevingen blijven beschikbaar, ook als ze niet op de huidige pagina voorkomen. Zoeken vindt ook de naam/code van source- en targetconnecties en geplande wijzigingen.

De bewerkdialoog gebruikt gecontroleerde keuzes voor contract, contractversie, berichttype, eigenaarrol, systemen, frequentie en mapping-/flowversies. Contractwijzigingen vervangen afhankelijke mapping- of flowkeuzes niet stilzwijgend. Frequentie is monitoringmetadata en geen scheduler.

De definitie verwijst naar actieve mapping- en flowversies, maar embedt geen runtime worklists. Operationele opvolging hoort in Monitoring > Integraties.

Contracten en mappings

De tab Contracten is een read-only catalogus van alle contractversies die binnen de actieve organisatie zichtbaar zijn. Zoek op naam of contractcode, filter op status, sorteer de lijst en blader door begrensde server-side pagina's. De lijst laadt geen zware schemas of gebruiksgegevens.

Open een contract voor metadata, een doorzoekbare boom met volledige veldpaden, de geformatteerde ruwe JSON, gebruik door mappings en integratiedefinities, en andere versies. Vanuit Gebruik navigeer je naar de betreffende mapping of integratie. Concept- en uitgefaseerde versies blijven zichtbaar met hun eigen status. De UI biedt geen acties om contracten te maken, wijzigen, activeren of uit te faseren. Daarvoor blijft het afzonderlijke platformrecht integrations.contracts.manage gelden.

De mapping-MVP gebruikt versieerbare contracten, mappings en regels. PaymentInstructionBatch.v1 is het eerste canonieke doelcontract.

Ondersteunde regeltypen zijn configuratie-only:

Regeltype	Gebruik
FIELD	Bronveld kopiëren
CONSTANT	Vaste waarde zetten
DEFAULT	Default gebruiken wanneer bronwaarde ontbreekt
LOOKUP	Waarde via lookup vertalen
FORMAT_DATE	Datum formatteren
TRIM	Spaties verwijderen
UPPERCASE	Waarde kapitaliseren
REQUIRED	Verplicht veld controleren
SUM_EQUALS	Somcontrole uitvoeren

Mappings voeren geen vrije Python, SQL, shell of JavaScript uit. Preview is read-only en bewaart de testpayload niet.

In de setup-UI opent een mappingrij één grote werkbank met Veldmapping, Testen & resultaat en Versiehistorie. Selecteer bronvelden uit het contractschema, onderhoud regels in de compacte tabel en bewerk de geselecteerde regel rechts. Op kleinere schermen staan bronvelden achter Bronvelden en worden regelinstellingen gestapeld. Alleen DRAFT mappingversies kunnen opnieuw worden geopend en gewijzigd; opslaan gebruikt een stale-edit controle op last_updated_at. Preview test ook niet-opgeslagen conceptregels zonder ze te bewaren. Resultaten worden verouderd zodra regels, contracten, voorbeeldpayload of lookupgegevens wijzigen; opslaan wist het eerdere resultaat. Lookupwaarden zijn via sleutel/waarde-rijen te onderhouden. Sleep regels of gebruik Alt+pijltjestoetsen voor de volgorde. Bij een opslagconflict blijven lokale wijzigingen staan totdat je expliciet opnieuw laadt. ACTIVE en RETIRED versies blijven read-only en dienen hoogstens als basis voor een nieuwe draft.

De mappinglijst toont de actieve versie zonder de detaildialoog te openen. Nieuwe en bestaande conceptversies vragen bevestiging bij het verwerpen van gewijzigde velden of regels. Contractkeuzes hebben een knop voor meer resultaten; de geselecteerde contractversie wordt apart gecontroleerd en blijft geldig als die buiten de eerste pagina staat. Bij een laadfout kan de controle opnieuw worden geprobeerd, zonder de waarde als historisch te markeren.

Flows

Flows bestaan uit versieerbare, geordende stappen. De huidige veilige servicecatalogus bevat de PaymentInstructionBatch-importadapter voor INVOKE_SERVICE-stappen. De UI toont de toegestane service uit /api/integrations/flow-service-catalog, zodat beheerders geen vrije servicenaam hoeven in te voeren.

De importservices voor PaymentInstructionBatch en ReceivableOpenItemBatch zijn alleen geschikt voor INBOUND-definities. De keuzelijsten en backend controleren zowel richting als contract. Hervatten van een gepauzeerde definitie controleert de actuele referenties opnieuw voordat verwerking wordt vrijgegeven, ook bij bulk-hervatten. De tab Referenties maakt onderscheid tussen geen verwerkingen en een mislukte laadactie, met een knop om opnieuw te proberen.

Activeren van een flowversie maakt die versie beschikbaar, maar koppelt deze niet automatisch aan een integratiedefinitie. De definitie bepaalt welke actieve versie daadwerkelijk wordt gebruikt.

In de setup-UI opent een flowrij een detaildialoog met versiehistorie, referenties en een grafische sequentiele canvas-editor. Alleen DRAFT flowversies kunnen opnieuw worden geopend en gewijzigd; opslaan gebruikt een stale-edit controle op last_updated_at. De editor biedt een palet met veilige staptypen, plusknoppen tussen stappen, slepen of toetsenbordbediening voor expliciet herordenen, stapinstellingen binnen dezelfde dialoog, verwijderen en in-/uitschakelen waar toegestaan, zoom, passend-in-beeld en automatische layout.

Het canvas blijft een editor voor de opgeslagen geordende stappen. Grafische positie verandert de uitvoeringsvolgorde niet ongemerkt; herordenen is een expliciete bewerking. De UI toont geen vertakkingen of parallelle uitvoering zolang de engine alleen lineaire stappen ondersteunt. Niet-opgeslagen wijzigingen in mapping- en flowconcepten vragen altijd om expliciet opslaan of verwerpen bij sluiten of wisselen van versie.

Flowconcepten veilig bewerken

Bij een nieuwe flowversie worden ook wijzigingen aan versienaam, status en stappen bewaakt. Annuleren, Escape, de sluitknop en buiten de dialoog klikken vragen om bevestiging zodra er lokale wijzigingen zijn. Weigeren bewaart de invoer.

Een VALIDATE-stap gebruikt Validatiecontract: kies een actieve contractversie binnen de organisatie. De runtime valideert op die positie daadwerkelijk tegen dat schema. Historische niet-oplosbare waarden moeten expliciet worden vervangen; er is geen vrije schemapadinvoer.

Een TRANSFORM-stap gebruikt een zoekbare mappingversiekeuze. De node toont dezelfde leesbare mappingnaam en versie. Rechte verticale lijnen verbinden Start, invoegpunten, stappen en Einde. Alleen actieve versies van actieve mappings binnen de huidige organisatie zijn toegestaan. De geselecteerde waarde wordt apart gecontroleerd, ook als deze niet op de huidige zoekpagina staat. Historische waarden blijven herkenbaar zichtbaar, maar moeten voor opslaan of activeren worden vervangen. Een laadfout biedt opnieuw proberen en wordt niet als historische waarde behandeld.

Het plusmenu opent bij de aangeklikte invoegpositie. Escape sluit het menu en geeft de focus terug aan de plusknop. De opgeslagen stapvolgorde blijft leidend.

Verwerkingen

Een verwerking legt één poging vast, inclusief correlation ID, business idempotency key, contract, mapping, flow, status, duur en foutdetails. Stapverwerkingen maken zichtbaar waar een flow faalde.

Belangrijke statussen:

Status	Betekenis
RECEIVED	Payload ontvangen
RUNNING	Flow wordt uitgevoerd
SUCCEEDED	Verwerking afgerond
FAILED_RETRYABLE	Tijdelijke fout, automatische retry gepland
FAILED_PERMANENT	Definitieve fout, beheeractie nodig
CANCELLED	Verwerking geannuleerd

Automatische retry

Integration Control Center probeert tijdelijke INVOKE_SERVICE-fouten automatisch opnieuw voordat een beheerder werk krijgt. HTTP 429, HTTP 5xx en geïnvalideerde databaseverbindingen worden retryable zolang er pogingen over zijn.

Retrymetadata staat op de execution:

• retry_count;
• max_retry_attempts;
• next_retry_at;
• retry_policy_json;
• interne retry_payload_json voor de retry worker.

Mappingfouten, validatiefouten, unsupported configuratie en idempotency-conflicten blijven permanent en maken direct een uitzondering aan.

Uitzonderingen, repair en replay

Integratie-uitzonderingen zijn beheerwerkitems voor fouten die niet automatisch hersteld kunnen worden. Een beheerder kan:

• een uitzondering toewijzen;
• reparatiepayload vastleggen;
• opnieuw verwerken;
• herstellen en opnieuw verwerken;
• oplossen;
• annuleren.

Replay gebruikt de geconfigureerde PaymentInstructionBatch-flow en behoudt de oorspronkelijke business idempotency key. Daardoor mag replay geen dubbele PaymentBatch- of PaymentInstruction-rijen maken. Replay vanaf een willekeurige geslaagde tussenstap is nog latere scope.

Impactanalyse

Impactanalyse laat zien welke integraties worden geraakt door een wijziging in een connectie, contract, mapping, flow, lookup of endpoint.

De analyse toont onder meer:

• getroffen integraties;
• eigenaren;
• actieve en geplande versies;
• afhankelijke connecties, mappings, flows en contracten;
• laatste succesvolle verwerking;
• open uitzonderingen;
• aanbevolen volgorde voor uitrol.

API's voor beheer

De management-API's staan onder /api/integrations.

Endpointgroep	Gebruik
GET /api/integrations/dashboard	Dashboardstatus lezen
/api/integrations/connections	Connectiemetadata lezen en beheren
/api/integrations/definitions	Integratiedefinities beheren
GET /api/integrations/contracts	Lichte, gefilterde contractlijst lezen
GET /api/integrations/contracts/{contract_id}	Schema, gebruik en versieoverzicht lazy lezen
POST /api/integrations/contracts	Berichtcontracten beheren als platformbeheerder
/api/integrations/mappings	Mappings en mappingversies beheren
/api/integrations/mapping-versions/*	Mappingregels lezen, DRAFT-versies wijzigen en versies activeren
/api/integrations/flows	Flows en flowversies beheren
/api/integrations/flow-versions/*	Flowstappen lezen, DRAFT-versies wijzigen en versies activeren
/api/integrations/flow-service-catalog	Veilige serviceadapters lezen
/api/integrations/executions	Verwerkingen lezen
/api/integrations/exceptions	Uitzonderingen lezen en opvolgen
POST /api/integrations/impact-analysis	Impactanalyse uitvoeren

Alle management-API's zijn interne applicatie-API's met organisatiecontext, RBAC, RLS en audit waar mutaties plaatsvinden.

Public API ingest

Externe systemen gebruiken de Public API onder /api/v1/integrations.

Endpoint	Gebruik
POST /api/v1/integrations/{definition_code}/ingest	Payload aanbieden voor een actieve integratiedefinitie

De Public API gebruikt serviceaccount-authenticatie en vereist integrations.execute. De ingestflow hoort business idempotency te respecteren, zodat herhaalde aanlevering of replay geen dubbele downstream transacties maakt.

Rechten en toegang

Recht	Gebruik
integrations.read	Dashboard, definities, flows en verwerkingen lezen
integrations.manage	Integratiedefinities beheren
integrations.pause	Integraties pauzeren of hervatten
integrations.mapping.read	Contracten, mappings en regels lezen
integrations.mapping.manage	Mappings en mappingversies beheren
integrations.contracts.manage	Berichtcontracten beheren
integrations.flow.manage	Flowconfiguratie beheren
integrations.exceptions.read	Integratie-uitzonderingen bekijken
integrations.exceptions.resolve	Uitzonderingen toewijzen, repareren en oplossen
integrations.replay	Retry/replay-acties uitvoeren
integrations.execute	Public API ingest uitvoeren als serviceaccount
outbound.settings.read	Connectie-instellingen bekijken
outbound.settings.manage	Credentialinstellingen beheren

Status van de implementatie

Aanwezig in de huidige baseline:

• connectiefundering bovenop integration_settings;
• integratiedefinities, execution- en step-executiontabellen;
• PaymentInstructionBatch.v1 contract en mapping-MVP;
• veilige mapping preview;
• versieerbare flows en eerste Oracle EBS naar PaymentInstructionBatch-prototype;
• exception worklist, repair payloads, retry/replay/repair-and-replay acties;
• automatische retry voor tijdelijke servicefouten;
• setup-UI voor Connecties, Integraties, Mappings, Flows, Webhooks en Oracle uitgaand;
• monitoring-UI voor Verwerkingen en Uitzonderingen.

Nog later te implementeren:

• bulk replay, bulk pause en bulk resume;
• operationele analytics en automation alerts;
• extra canonieke contracten;
• replay vanaf een willekeurige succesvolle stap;
• uitgebreidere schema catalogus en designer-UX.

Praktische checklist

• Gebruik Connecties voor technische endpoints en credentialmetadata.
• Gebruik Integraties voor functionele varianten en eigenaarstatus.
• Activeer mapping- en flowversies expliciet voordat je ze aan een definitie koppelt.
• Test mappings met preview voordat een versie actief wordt.
• Controleer Verwerkingen bij foutonderzoek voordat je een uitzondering repareert.
• Gebruik repair en replay alleen met behoud van business idempotency.

Normalisatie van bestaande referenties

Migratie 20260913_integration_reference_normalization zet bekende frequentiealiassen om en vertaalt alleen eenduidige organisatiegebonden schema_ref-waarden naar een contractversie. Onbekende frequenties blijven behouden en krijgen een expliciet monitoringsignaal. Niet-eenduidige schemareferenties blijven historisch zichtbaar voor handmatige correctie. Versie- en executiereferenties worden niet verwijderd. Beheerde oorspronkelijke demoflows kunnen een nieuwe versie krijgen met expliciete contractkeuzes; aangepaste flows worden niet automatisch herschreven.