Inleiding
Recentelijk heb ik ervaring opgedaan met de SOAP interface van het Timn Enterprise product van Aenova. Omdat er nogal wat mensen in Nederland gebruik maken van dit product leek het me wel leuk om de opgedane kennis te delen.
Er zijn daarbij vooraf een aantal zaken die je moet weten:
- De koppeling “lijkt” op SOAP. De interface kan geen WSDL produceren dus je kunt geen stubs laten genereren op basis van een WSDL (die dus niet bestaat).
- Aenova heeft zelf een document getiteld “TimEnterprise SOAP & SCV” die je kan helpen bij de eerste kleine stapjes. Voor de rest moet je echt een consultant van hun inhuren.
- Als er al error-logging is dan vindt je die in de beheersconsole niet onder SOAP-log, maar onder ‘server-log’.
- Er is op de SOAP-interface zelf geen foutmeldingen te krijgen. Je krijgt bij een import-actie een record-id terug. Een leeg record-id betekent dat er een foutmelding in de server-log staat. Waar die staat is dan weer vers twee. Omdat volgens de XML standaard er geen relatie is tussen de volgorde waarin je records verstuurt, versus de geretourneerde resultaten, heb je hier dus feitelijk niks aan. Tenzij je natuurlijk zelf ook een interface in elkaar flanst.
- Het is erg raadzaam om de normale Java client beschikbaar te hebben (komen we later op) en dat je de rechten hebt om export-definities te maken.
Van start
Nu je dit weet kunnen we van start. Mijn eerste stapjes betekende een script maken dat vanaf Linux (in dit geval een absolute aanrader om te gebruiken) vragen te kunnen stellen aan de Tim server.
Op de Tim server dien je de SOAP interface “aan” te zetten. Je moet daarbij een userid en wachtwoord instellen die je later nodig hebt.
Mijn script zag er als volgt uit:
#!/bin/bash wget --debug --http-user=timnsoap --http-password=aenova --post-file=$1 -O - http://servernaam:10980/impexp/ | xmllint --format - | less
Voor de duidelijkheid: het script bestaat uit 2 regels. Dus van “wget” tot “less” is 1 regel!
Als je het aanroept vertel je op de commandline welk xml bestand je wilt verzenden, op basis waarvan Tim je vervolgens een antwoord zal geven.
Voorbeeld 1
Een voorbeeld van zo’n XML bestand is het volgende voorbeeld.
Stel dat je een overzicht wil van de mensen die een aanvraag voor een bepaald type verlof hebben ingediend. Als je met behulp van bovenstaand scriptje het volgende bestand naar de Tim server stuurt (pas wel even het email-adres aan dat er in staat), krijg je het antwoord daarop retour (als alles goed gaat).
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <export soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns="impexp.timn.aenova.nl"> <data> <Aanvraag> <filter><Persoon><EmailAdres>username@domain.tld</EmailAdres></Persoon></filter> <Persoon><EmailAdres></EmailAdres></Persoon> <Periode><Start/><Eind/></Periode> <Roostercategorie><Naam/><Aanwezigheid/><Status/></Roostercategorie> </Aanvraag> </data> </export> </soapenv:Body> </soapenv:Envelope>
Tot zover de export van gegevens. Je kunt ook zaken importeren, maar realiseer je dus wel dat de feedback die je krijgt minimaal is. Geen error-strings retour voor ons sterfelijke zielen :-).
Voorbeeld 2
In het volgende voorbeeld krijgen we uit een andere applicatie een bepaald tijdsbeslag wat we vervolgens bij Tim willen invoeren. Dus wie heeft wanneer wat en hoe lang gedaan?
In XML ziet dat er dan als volgt uit:
<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <import soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns="impexp.timn.aenova.nl"> <data> <Tijdregistratie> <Persoon><EmailAdres>gebruiker@domein.nl</EmailAdres></Persoon> <Product><Code>6200</Code></Product> <Datum>31-10-2012</Datum> <Duur>7:30</Duur> </Tijdregistratie> </data> </import> </soapenv:Body> </soapenv:Envelope>
Waar vind je de veldnamen?
Maar hoe kom je er nu achter welke velden er allemaal bestaan?
Eigenlijk is dat nog best eenvoudig (als je het weet). Je gaat namelijk naar de normale Tim Java-applicatie, en kiest dan Bestand->Import/Export->Import/Export definities (let op de gebruikersrechten!).
In dit scherm is het mogelijk een nieuwe definitie te definiëren. Men kiest een tabel en vervolgens het veld of eventueel het subveld. Als de set met gewenste gegevens naar wens is kan men een export van de gegevens maken. De eerste regel van deze export bevat vervolgens een overzicht van de diverse velden die in de gegevensset staan. Deze kan dan weer als basis dienen voor een SOAP im- of export.
Unieke keys
Als je een bestand steeds opnieuw inleest, bijvoorbeeld met een combinatie van gebruikersnaam, datum, productcode en aantal uur, dan zullen er steeds records worden toegevoegd. Om aan te geven dat een bepaalde combinatie van velden leidt tot een unieke key voorzie je het betreffende veld van de tag “@”, dus bijvoorbeeld <product “@”>.
Afsluitend
Met de kennis die we nu hebben kunnen we zelf aan de slag om uit Tim te halen wat iemands beschikbaarheid is zodat we daar in het project planningspakket rekening mee kunnen houden. Omgekeerd kunnen we de in ons bug-management systeem ingevoerde uren automatisch importeren in Tim zodat iemand slechts éénmalig zijn uren hoeft te registeren.