Algemene REST API praktijken

Integratie Severaan

Wanneer je begint met het maken van een integratie met Severa, is het belangrijk om naast de functionaliteit van de integratie ook rekening te houden met de technische kant: waar en hoe de integratie zal worden uitgevoerd, hoe deze kan worden getest en hoe je informatie kunt krijgen over wat er gebeurt terwijl de integratie actief is. De integratie kan worden gebouwd met de technologie van jouw keuze, en Severa biedt geen ondersteuning voor de gekozen technologie.

Integratie plannen

De integratie met Severa moet zo worden gebouwd dat deze niet voortdurend de REST API van Severa bevraagt of er nieuwe informatie beschikbaar is. De integratie moet op geplande tijden worden uitgevoerd, en bij het bepalen van het schema moeten de volgende zaken in overweging worden genomen:

1. Welke informatie verplaatst de integratie?
2. Moet elk type informatie volgens hetzelfde schema worden verplaatst, of kunnen sommige vaker worden verplaatst dan andere?
3. Zijn er afhankelijkheden in de gegevens die van invloed zijn op de te verplaatsen gegevens?
4. Wat is de zakelijke behoefte van de integratie, welke zakelijke vereisten zijn er voor de overdracht? Het is belangrijk dat de integratie zijn doel dient binnen het tijdschema dat het bedrijf nodig heeft. Bijvoorbeeld: Het verplaatsen van afwezigheden naar het salarisadministratiesysteem kan eens per week worden gedaan, maar verzonden facturen moeten dagelijks worden verplaatst.
5. Als de overdrachten van de integratie meerdere keren per dag moeten worden uitgevoerd, mag de integratie niet vaker dan eens per uur actief zijn.
6. Bouw geen integratie waarvan de hoofdlogica een lus is die onmiddellijk na voltooiing herhaalt zonder enige vorm van planning.

Integratie testen

Wanneer de integratie wordt ontwikkeld, moet deze worden getest tegen de secure-test-omgeving van Severa. Wanneer is bewezen dat de integratie probleemloos werkt, kan deze worden omgeschakeld naar productie. Meer informatie: Hoe te beginnen met REST API?

Wanneer wijzigingen worden aangebracht in een bestaande integratie, moeten deze worden getest tegen de secure-test-omgeving. De integratie mag nooit rechtstreeks naar productie worden gepubliceerd. Dit zorgt ervoor dat de gegevens van de klant niet worden beschadigd als er problemen zijn met de integratie. Neem de volgende zaken op in het testen van de integratie:

1. De integratie uitvoeren met testgegevens tegen de secure-test-omgeving.
2. Handmatige wijzigingen aanbrengen in gegevens zowel in Severa als in andere geïntegreerde software en ervoor zorgen dat de overdracht correct is.
3. Een voldoende aantal testgevallen om de volledige functionaliteit van de integratie te dekken. Bovendien moeten er verschillen zijn in de testgegevens om de scenario's veelzijdig te dekken.
4. Regressietesten van de volledige functionaliteit van de integratie telkens wanneer de wijzigingen groot genoeg zijn om een volledige regressie te vereisen.
5. Overweeg ook eerdere problemen toe te voegen aan het testplan om te voorkomen dat ze zich opnieuw voordoen.

Integratie configureren

Over het algemeen hebben integraties verschillende parameters nodig om probleemloos te functioneren. Veelvoorkomende parameters zijn bijvoorbeeld:

• Severa API URL: Geeft aan waar de API zich bevindt. De integratie moet mogelijk worden uitgevoerd tegen de secure-test.severa.com- of secure.severa.com Severa-omgeving.
• Klant referenties: Welke klantreferenties en wachtwoorden worden gebruikt in de integratie.
• Verschillende parameters die nodig zijn om de juiste informatie van de API te krijgen. Bijvoorbeeld "gebruik deze factuurstatusnaam om facturen van Severa te krijgen".
• Verschillende standaardwaarden die nodig zijn om de integratie in alle scenario's te laten werken. Bijvoorbeeld "gebruik deze productcode wanneer de productcode niet beschikbaar is", of "gebruik deze persoon als standaardbeheerder als er geen andere gebruiker beschikbaar is".
• Tijdstempels van de laatste gegevensophaling die worden gebruikt bij de volgende uitvoering van de integratie. Bijvoorbeeld bij gebruik van de "GetCasesChangedSince"-methode, moet de tijd van de vorige uitvoering ergens worden opgeslagen, en de configuratie moet automatisch door de integratie en handmatig door de gebruiker kunnen worden gewijzigd.
• API-versie en entiteitsschema versie datums, zodat de integratie bij elke uitvoering de opgeslagen versies kan vergelijken met de API-versies en kan zien of er wijzigingen zijn.
• Configuraties die nodig zijn voor logging, zoals de locaties van logs, e-mailadressen waar berichten naar worden verzonden, enzovoort.

Wanneer de integratie gegevens van meerdere klanten verwerkt, moet elke klant aparte configuraties hebben om te voorkomen dat de verkeerde configuratie wordt gelezen en problemen in de integratie ontstaan.

De configuraties van de integratie moeten zodanig zijn dat ze handmatig kunnen worden gewijzigd, omdat soms tijdstempels die in een fout zijn opgeslagen, naar het verleden moeten worden gewijzigd.

Foutafhandeling

Foutafhandeling in de integratie is cruciaal omdat integraties klantgegevens raken, en die gegevens kunnen niet gemakkelijk worden hersteld als de integratie ze heeft beschadigd. Bij het maken van foutafhandeling moeten de volgende vragen op hoog niveau worden overwogen en opgelost:

1. Welke fouten in de integratie moeten de uitvoering van de integratie stoppen?
2. Welke fouten kunnen optreden zodat de integratie normaal blijft functioneren?
3. Waar worden fouten gelogd?
4. Wie is verantwoordelijk voor het monitoren van foutlogs?
5. Wat wordt er gedaan wanneer er een fout optreedt in de integratie en wie doet dat?

De integratiesoftware zelf moet in staat zijn om verschillende fouten die in de software optreden te verwerken. Alle fouten moeten worden opgevangen, er mag geen ruimte zijn voor niet-verwerkte uitzonderingen. Dit betekent dat naast de gewone foutafhandeling de software ook in staat moet zijn om alle soorten fouten te verwerken die van de REST API van Severa kunnen komen.

Logging

Logging is een van de belangrijkste zaken in de integratie, omdat in geval van een fout uit de log moet kunnen worden gelezen wat de integratie heeft gedaan op het moment van de fout. Logging kan bijvoorbeeld worden gedaan:

• In het gebeurtenislogboek van de server die de integratie uitvoert
• In de database van de applicatie
• Logging naar e-mail. Merk op dat als logging naar e-mail wordt gedaan, de verzonden gegevens niet veilig zijn, omdat e-mail als een ansichtkaart is die door het internet reist. De integratie kan ook veel loggegevens genereren, waardoor e-mail onbruikbaar kan worden.

Logging moet ten minste op deze niveaus worden gedaan:

• De voortgang van de integratie moet worden gelogd
• Fouten moeten worden gelogd

Logging moet tijdstempels bevatten voor alle belangrijke acties. Het is het beste als de tijdstempel op seconden nauwkeurig is, omdat minuten vaak te groot zijn, aangezien overdrachten snel plaatsvinden.

Was dit antwoord nuttig? Ja Nee