Recentelijk werkte ik aan een project rond ITSM voor een van onze cliënten, waarbij ik de vraag kreeg om ServiceNow met een extern systeem te integreren via de REST API.
Voor wie ServiceNow nog niet kent, kan ik aanraden om eerst hun website te bekijken. In het kort: ServiceNow is een heel breed technologieplatform dat gebruikt kan worden om digitale workflows te creëren voor bijna elk deel van je bedrijf. In mijn geval was ik bezig met het integreren van het incidentensysteem (ticketing) met een externe partij om beide partijen een betere workflow te bieden.
Je zou je je af kunnen vragen hoe zou je dat kunt realiseren met het huidige aanbod aan WSO2 producten? Om dit veilig te doen nemen we de WSO2 API Manager (APIM) om verkeer en beveiliging te beheren, de WSO2 Identity Server (IS) om de authenticatie (of autorisatie) te behandelen en de WSO2 Enterprise Integrator (EI) om alle verschillende bemiddelingsscenarios tussen de verschillende eindpunten te behandelen.
In ons geval gaat er informatie van ServiceNow naar het externe systeem en komt er weer informatie terug. Ik ga deze flows apart beschrijven omdat de werking kleine verschillen vertoond wat betreft de authenticatie in ServiceNow.
Integratie van ServiceNow in een extern systeem
Binnen ServiceNow kan je scripts schrijven die aansluiten bij je situatie. In ons geval was dat het activeren van het integratieplatform op het moment dat er een nieuw incident aangemaakt wordt. Om dit te laten werken moest het op zo’n manier geconfigureerd worden dat de authenticatie tussen de 2 naadloos zou verlopen. Deze authenticatie kan met ServiceNow op twee manieren gedaan worden. Eenvoudige authenticatie is toegestaan (met een optie voor wederzijdse authenticatie via specifieke profielen in ServiceNow) en daarnaast is er voor verschillende configuraties OAuth2.0 beschikbaar.
Voor dit uitgaande verkeer kan je een OAuth2.0 provider binnen ServiceNow opzetten, die gebruikt kan worden voor authenticatie met de WSO2 APIM via de WSO2 IS. Deze provider is verbonden met de WSO2 IS waar het de tokens ontvangt die gebruikt worden voor de authenticatie van de aanvraag die bij de WSO2 APIM binnenkomt. Als de verbinding opgezet is en de token in de APIM gevalideerd is, kan de inhoud van het bericht door de bewuste API die door ServiceNow aangeroepen wordt naar de WSO2 EI doorgestuurd worden.
Binnen de WSO2 EI kun je voor de bemiddeling van berichten de Enterprise Service Bus gebruiken en zo de benodigde payloads creëren voor het gewenste externe systeem. Waarbij het bericht onderweg van JSON naar XML omgezet wordt. En om ervoor te zorgen dat deze berichten aankomen, is het mogelijk om leveringsgaranties op te zetten met een messaging component, zoals Apache ActiveMQ.
Integratie van een extern systeem in ServiceNow
Voor het versturen van gegevens naar ServiceNow werkt de flow vergelijkbaar, maar met enkele aanpassingen. In ons geval kijken wij of het externe systeem nieuwe data beschikbaar heeft, maar dezelfde integratie is ook mogelijk met een externe partij die actief het integratieplatform aanroept. Het enige verschil is dat je ervoor kunt kiezen om een extra API operatie toe te voegen die aan te roepen is door de externe partij.
In dit geval zal ik maar aannemen dat de WSO2 EI de data al ontvangen heeft, omdat de externe partij bijna elk systeem in de wereld zou kunnen zijn en het bespreken van de verbinding dus te ver gaat voor deze blog. Laten we zeggen dat je een bericht ontvangt dat een gebruikersnaam, een titel en een beschrijving van een extern systeem bevat, en dat je wil gebruiken om een incident in ServiceNow aan te maken dat gekoppeld is aan een specifieke gebruikersnaam.
Deze flow vereist twee aparte aanroepen van de ServiceNow REST API:
- Een GET request aan de ServiceNow gebruikerstabel om de user id op te vragen
- Een POST request aan de ServiceNow incidententabel
Maar voordat je de API kan aanroepen heb je een toegangstoken nodig. Deze kan ook opgehaald worden door de REST API, maar in plaats van het opzetten van een OAuth2.0 provider, moet je een OAuth2.0 client opzetten en de Client Secret/Client Id combinatie gebruiken die door door de client aangeboden wordt om een token te krijgen van de EI. Nadat de authenticatie opgezet is kun je de REST API gaan gebruiken. De ServiceNow REST API heeft een uitgebreide functionaliteit en is (naar mijn mening) erg fijn om mee te werken in combinatie met de WSO2 producten, omdat het makkelijk is om tussen de berichtformaten te bemiddelen en de juiste aanroepen aan de API op te zetten om daarmee de gewenste gegevens op te halen. Het kost alleen wat zoekwerk naar welke gegevens in welke tabel staan. Met de grote aanbod aan ServiceNow documentatie en hun REST API Explorer is dit niet moeilijk om uit te vinden.
Laten we het voorbeeld afmaken. Omdat we alleen de gebruikersnaam hebben, zullen we de user id moeten opvragen. De GET request URL zal er ongeveer zo uitzien:
GET <em>https://{ServiceNowHost}/api/now/table/sys_user?sysparm_query=user_name={the username}</em>
Dit zal een JSON bericht teruggeven met verschillende gegevens van de gebruiker, inclusief de id.
Nadat je de id uit het antwoord gehaald hebt, kun je beginnen met het samenstellen van het payload om het incident mee aan te maken.
Dat ziet er dan ongeveer zo uit:
{ "caller_id":"The user id", "short_description":"The Title", "description":"The description" }
Met het overeenkomstige eindpunt:
POST <em>https://{ServiceNowHost}/api/now/table/incident</em>
Nadat het juiste bericht naar het eindpunt verstuurd is, zal ServiceNow een incident payload teruggeven dat een incidentnummer en een incident ID bevat om te bevestigen dat het incident succesvol gecreëerd is.
En zo is de cirkel in dit voorbeeld rond. Er zijn uiteraard veel meer mogelijkheden met deze setup van allebei de beschreven flows. Het hoeft niet te stoppen bij een enkele aanroep voor informatie, want als er meer aanroepen noodzakelijk zijn is dat ook mogelijk. Als deze blog vragen oproept, aarzel niet om ze in de opmerkingen te stellen of contact met ons op te nemen via een van onze kanalen.
