Hoe documenteer je software integratie?

Grofweg zijn er 3 gebieden die gedocumenteerd moeten worden

1. Functionele proces beschrijving.
   Het functionele proces wat geautomatiseerd wordt door de integratie. wordt hierin duidelijk.
2. Integratie catalogus.
   Een lijst met integratie die gerealiseerd moeten worden zodat het functionele proces automatisch conform de beschrijving via de integratie wordt gerealiseerd.
3. Integratie Design
   Het technische ontwerp van de integratie(s) die gerealiseerd moeten worden.

Functionele proces beschrijving.

Het begint met een functionele omschrijving wat de integratie precies faciliteert. In gewone mensentaal, iedereen moet deze goed kunnen lezen en begrijpen.

Bijvoorbeeld:Wanneer een factuur is aangemaakt in Salesforce, dan wordt deze automatisch geboekt in Exact. In Salesforce is het mogelijk om de verschillende producten te kiezen voor individuele factuur regels. Deze producten worden beheert in Exact. In Salesforce moet zichtbaar worden of de facturen al betaald zijn. 

Deze omschrijving kan zo kort en bondig zijn, maar hoe gedetailleerder hoe beter.

Integration catalogus:

Overzicht van alle integraties die er nodig zijn. Het doel van dit overzicht is vastleggen welke informatiestromen er aanwezig zijn in je project.

hierin leg je de volgende zaken vast:

• Wat gaat er van A naar B
• Bronsysteem
• Doelsysteem
• Is de informatie Realtime of Batch?
• Hoe vaak moet de informatie over en weer (wekelijks,dagelijks,iedere minuut)
• Welke richting gaat de data uit, is dat van A naar B of B naar A.
• Unieke identifier voor elke integratie (bv int-0001)
• Wie is de master van de data. (system of record)
• Type Data returned:
  • json
  • xml
  • csv

Voorbeeld hier.

Integration design:

Per integratie in de catalogus ga je de de volgende zaken documenteren:

• Mapping: hierin leg je vast hoe de transformatie er uit ziet van het object. Je gaat hierin op veldniveau definiëren hoe de velden gemapped moeten worden. In de mappings ga je ook vastleggen welke informatie er verplicht is.Voorbeeld hier
• Flow: in het flow design leg je vast welke processtappen er gemaakt worden om informatie van A naar B te krijgen. Het is hier van belang dat zowel de happy flow als de niet happy flow worden designed.
• Integration scenario: in het integratie scenario document leg je vast welke stappen er genomen moeten worden en hoe dit getest kan worden.voorbeeld hier.

Voorbeeld van een flow

Punten van belang bij het ontwerpen van een batch job;

• Hoe vaak wil ik een job bij fout herhalen?
• Hoe handel ik transient errors af? Ga ik een re-try doen of laat ik de job gelijk falen en stuur ik een mail.
• Hoe ga ik controleren of een batch gelukt is of niet? Het is vaak een goed idee om success lijsten te maken en deze te mailen onSucces. Een centraal email adress waar het hele team bij kan is dan een goed idee.
• Hoe laat ik de eindgebruiker weten dat een batch gefaald is? Dit kan je bv doen door een automatische mail te sturen onFail of om een error direct terug te geven aan het bronsysteem.

Punten van belang bij het ontwerpen van een API:

• Wat is de maximale laadtijd?
• Wat is de verantwoordelijkheid van mijn api?
• Hoe regel ik de authenticatie [Credentials, Token,etc]
• Het is in de voorfase met name belangrijk dat je bedenkt:
  • Welke data komt er in ?
  • Welke data geef ik terug?
  • Welke codes geef ik terug en hoe test ik dit (200,201,400,401,403,500)
• Zorg er voor dat je voor de consumer van jouw api altijd een OpenApi/Swagger document maakt. Dit maakt communiceren en testen van je api gemakkelijker.
• Tip: start een project in postman. Zorg voor iedere call die er gemaakt kan worden naar jou API dat er een voorbeeld request is + testen.
• Tip: wanneer je third party API’s gaat consumeren kan je het beste postman gebruiken. Alle requests en responses kun je hierin documenteren (en zelfs delen met je teamgenoten).

Downloads

• Kodify 2020 Mapping Template
• Kodify 2020 Master Data Template
• Kodify 2020 integration scenario