Stappenplannen MailPlus SOAP API

Stappenplannen MailPlus SOAP API Stappenplannen MailPlus SOAP API oktober 2009

Introductie Dit document bevat stappenplannen welke u als technische gebruiker van MailPlus op weg kunnen helpen met de koppeling van uw eigen software omgeving met de SOAP API van MailPlus. 2

H1 Voorbereiding 1.1 Doelstelling Dit document toont door middel van stappenplannen aan dat er met behulp van de meest voorkomende ontwikkel omgevingen een implementatie van de MailPlus SOAP API mogelijk is. Daarnaast helpt het technische gebruikers op weg bij het implementatie traject, door middel van concrete voorbeelden. 1.2 Doelgroep Deze stappenplannen zijn bedoeld voor ontwikkelaars die aan de slag willen met het integreren van software systemen van met MailPlus door middel van diens SOAP API. Enige kennis van en ervaring met de taal en ontwikkel omgeving in kwestie wordt aangenomen. 1.3 Aannames Vereiste voor gebruik van de MailPlus SOAP API is een MailPlus account waarin de SOAP API voor u is ingeschakeld, het externalid veld voor uw contacten beschikbaar is en de IP controle (tijdelijk) is uitgeschakeld. Daarnaast wordt aangenomen dat u bekend bent met de concepten en werking van MailPlus en beschikt over de referentie handleiding van de MailPlus SOAP API. 1.4 Aanpak Voor elke uitgewerkte combinatie van taal en ontwikkel omgeving wordt zoveel mogelijk de werkwijze voor het implementeren van Web Service Clients gebruikt die daar gebruikelijk is. Hierbij wordt zoveel mogelijk gebruik gemaakt grafische Stappenplannen MailPlus SOAP API 1

componenten beschikbaar in de ontwikkel omgeving. Steeds wordt op basis van een externalid een Contact opgehaald, waarbij het encryptedid wordt getoond. Stappenplannen MailPlus SOAP API 2

H2 Stappenplannen 2.1 Java (Netbeans) 2.1.1 Vereisten - NetBeans IDE 6.x met Web & Java EE versie 6.0 or 6.1 - Java Development Kit (JDK) versie 5 of 6 (als u JDK 6 gebruikt heeft u Update 7 of later nodig) - Een web- of applicatie server met Java EE ondersteuning (aangeraden wordt GlassFish v2+ of Tomcat 6+) 2.1.2 Stappen 1 Nieuw Project Klik in Netbeans op het New Project icoon of toets Ctrl-Shift-N voor het volgende scherm. Kies vervolgens onder Categories: voor Java Web en onder Projects: voor Web Application. Klik daarna op Next >. Stappenplannen MailPlus SOAP API 3

2 Nieuwe Web Applicatie Vul bij Project Name: de naam van het nieuwe Project in, bijvoorbeeld MailPlusSoapClient. Klik daarna op Next >. 3 Applicatie Server instellen Kies achter Server: voor een van de ingestelde applicatie servers. Bij een standaard installatie van Netbeans is hierbij GlassFish v2.1 beschikbaar, welke hier verder gebruikt zal worden. Klik eventueel op Add om een andere Applicatie Server in te stellen. Klik daarna op Finish. Stappenplannen MailPlus SOAP API 4

4 Nieuwe Web Service Client Klik vervolgens met de rechter muisknop op het MailPlusSoapClient Project dat links is verschenen, beweeg via New naar Web Service Client en klik daarop. In het venster dat daarop opent selecteert u WSDL URL: zoals hieronder weergegeven. In het vak daarnaast vult u de WSDL URL in van de Contacts service: Stappenplannen MailPlus SOAP API 5

http://api.mailplus.nl/apiservice/soap/contacts_v1?wsdl Klik daarna op Finish. 5 Nieuwe Servlet Klik vervolgens nogmaals met de rechter muisknop op het MailPlusSoapClient Project, beweeg via New naar Servlet en klik daarop. Stappenplannen MailPlus SOAP API 6

In het New Servlet venster vult u het veld Class Name: in. In dit voorbeeld gebruiken wij ClientServlet. Voor test doeleinden kan het veld Package: leeg worden gelaten en de waarschuwing die Netbeans hierover weergeeft worden genegeerd. Klik daarna op Finish. 6 API aanroepen Nu de webservice bekend is in Netbeans en de Servlet om mee te werken is aangemaakt kan er een API methode worden aangeroepen. Schoon de processrequest methode zoals in het voorbeeld, de inhoud van deze methode moet er uit zien als: response.setcontenttype( text/html:charset=utf-8 ); PrintWriter out = response.getwriter(); out.close(); Klik daarna met de rechter muisknop op de lege regel en kies voor Insert Code in het daarop verschenen menu. Stappenplannen MailPlus SOAP API 7

Scroll indien nodig naar beneden in het lijstje dat vervolgens verschijnt en kies voor Call Web Service Operation door hierop te klikken. Klap in het verschenen venster achtereenvolgens MailPlusSoapClient, Contacts_v1, Contacts_v1Service en Contacts_v1Port uit en selecteer getcontactbyexternalid. Klik daarna op OK. Stappenplannen MailPlus SOAP API 8

Netbeans genereert vervolgens de nodige code voor het aanroepen van de geselecteerde methode. Vul de waarden id, password en externalid met waarden die bij u bekend zijn. Om te kunnen controleren of het verwachte resultaat goed wordt opgehaald voegt u de volgende regel toe: out.println( EncryptedId: + result.getencryptedid()); Voor correct functioneren is het van belang dat uw code overeenkomt met de onderstaande afbeelding. Klik daarna op Run Project (of toets F6). Stappenplannen MailPlus SOAP API 9

7 Testen Open een browser venster en bezoek het adres (als u Tomcat gebruikt draait deze standaard op poort 8084 in plaats van 8080): http://localhost:8080/mailplussoapclient/clientservlet Als alles goed is gegaan geeft dit een resultaat vergelijkbaar met onderstaande, waarin het door MailPlus gegenereerde encryptedid van deze specifieke contact wordt getoond. 2.1.3 Opmerkingen Stappenplannen MailPlus SOAP API 10

- Als u JDK 5 gebruikt dient u bovenaan de ClientServlet class toe te voegen: private nl.mailplus.api.services.soap.contactsv1service service = new nl.mailplus.api.services.soap.contactsv1service(); - Het is mogelijk dat er na het aanpassen van de code een aantal regels rood onderstreept worden en er fout iconen getoond worden, met de melding dat er classes in nl.mailplus.api.* niet gevonden kunnen worden (zelfs als u Fix Imports gebruikt heeft). In dit geval heeft Netbeans de WSDL nog niet goed verwerkt. Dit lost zichzelf op wanneer u het project probeert te builden. 2.2 Java (Eclipse) 2.2.1 Vereisten - Eclipse Galileo - Tomcat 6 (ingesteld in Eclipse) - Axis2 1.5 binary (ingesteld in Eclipse) - Axis2 1.5 webapp (gedeployed in Tomcat) - Axis2 in plaats van Axis ingesteld als standaard in Eclipse - Apache HttpComponents 4 (httpcore-4.0-alpha6.jar in de lib folder van Tomcat) 2.2.2 Stappen 1 Nieuw Project Klik in Eclipse op het New icoon en klik op Dynamic Web Project voor het volgende scherm: Stappenplannen MailPlus SOAP API 11

Vul bij Project name: de naam van het nieuwe project in (hier MailPlusSoapClient). Kies onder Target Runtime voor een ingestelde Tomcat 6.0 server en klik op Finish. Stappenplannen MailPlus SOAP API 12

2 Axis Ondersteuning Klik met de rechter muisknop op het Project dat links is verschenen en kies in het menu voor Properties door hierop te klikken. Stappenplannen MailPlus SOAP API 13

Klik daarna in het verschenen venster aan de linker kant op Project Facets en vink Axis2 Web Services aan. Klik daarna op OK. 3 WebService Client Het Project is nu juist ingericht om met Web Services te kunnen werken. Voeg een referentie toe door met de rechter muisknop op het Project te klikken en via het menu New te bewegen naar Other. Stappenplannen MailPlus SOAP API 14

Klap in het verschenen venster het mapje Web Services uit en selecteer Web Service Client. Klik vervolgens op Next >. Stappenplannen MailPlus SOAP API 15

Vul in het vakje Service definition: de link naar de WSDL in: http://api.mailplus.nl/apiservice/soap/contacts_v1?wsdl Zet de slider aan de linker kant van het scherm omlaag tot er Assemble client wordt aangegeven. Controleer dat er rechts onder Configuration: het juiste staat ingesteld, pas dit aan indien nodig. De juiste instellingen, zoals zichtbaar in de onderstaande afbeelding, zouden moeten zijn: - Server: Tomcat 6.0 Server (of de naam van uw Tomcat 6.0 server indien anders) - Web service runtime: Apache Axis2 (let hier op de 2 aan het eind) - Client Project: MailPlusSoapClient (of de naam die u uw Project gegeven heeft) Klik vervolgens op Finish. Stappenplannen MailPlus SOAP API 16

4 Servlet Aanmaken Klik nogmaals met de rechter muisknop op uw Project en beweeg via New naar Servlet en klik hierop. Stappenplannen MailPlus SOAP API 17

In het venster dat nu verschijnt vult u in ieder geval de naam van uw Servlet in, zoals in het voorbeeld ClientServlet in het vakje Class name:. Laat alle overige instellingen voor test doeleinden zoals ze zijn en klik op Finish. Stappenplannen MailPlus SOAP API 18

5 API aanroepen Om vervolgens de SOAP API aan te roepen past u de nieuwe Servlet aan zoals in het onderstaande voorbeeld te zien is. Hiervoor voegt u de volgende code toe in de methode doget : Contacts_v1ServiceStub stub = new Contacts_v1ServiceStub(); GetContactByExternalId soaprequest = new GetContactByExternalId(); soaprequest.setid("123456"); soaprequest.setpassword("abcdefgh"); soaprequest.setexternalid("1"); GetContactByExternalIdE requestwrapper = new GetContactByExternalIdE(); requestwrapper.setgetcontactbyexternalid(soaprequest); try { Contact contact = stub.getcontactbyexternalid(requestwrapper).getgetcontactbyexternalidresponse().get_return( ); PrintWriter out = response.getwriter(); out.write("encryptedid: " + contact.getencryptedid()); out.close(); } catch (ThrowableException e) { e.printstacktrace(); } Stappenplannen MailPlus SOAP API 19

Uiteraard dient u het id, password en externalid te vervangen met de gegevens die bij u bekend zijn. Stappenplannen MailPlus SOAP API 20

6 Test Open vervolgens uw browser en open de zojuist aangemaakte Servlet. In principe kunt u deze benaderen via http://localhost:8080/mailplussoapclient/clientservlet tenzij uw opstelling afwijkt van het voorbeeld. 2.2.3 Opmerkingen - De volgende fout kan optreden bij deployment: java.lang.classnotfoundexception: org.apache.axis2.transport.http.axisadminservlet Vervangt u dan in WebContent/WEB-INF/web.xml van het Eclipse project de volgende tekst: org.apache.axis2.transport.http.axisadminservlet Met het volgende: org.apache.axis2.webapp.axisadminservlet 2.3 PHP 2.3.1 Vereisten - PHP5 of hoger met SOAP extensie (configureren met enable-soap). Onder Linux kan dit vaak gerealiseerd worden door een package als php-soap te installeren. - Een tekstverwerker waarmee u PHP bestanden kunt verwerken. Voor eenvoud wordt voor Windows gebruikers Notepad++ en voor Linux gedit aangeraden. Eventueel kan er ook gebruik gemaakt worden van een IDE zoals Zend Studio. Stappenplannen MailPlus SOAP API 21

- Een webserver (zoals Apache) waarin PHP en diens SOAP extensie juist is geconfigureerd, waarop uw script geplaatst kan worden en u kunt benaderen door middel van uw browser. 2.3.2 Stappen 1 Scripten Maak een nieuw PHP bestand aan (bijvoorbeeld MailPlusSoapClient.php) en plaats daar de volgende regels in: Stappenplannen MailPlus SOAP API 22

<?php $client = new SoapClient('http://api.mailplus.nl/ApiService/soap/Contacts_v1?wsdl'); $params = array('id' => '123456', 'password' => 'abcdefgh', 'externalid' => '1'); echo('encryptedid: '. $client->getcontactbyexternalid($params)->return->encryptedid);?> Vervang in dit voorbeeld het id, password en externalid met de gegevens die bij u bekend zijn. 2 Uploaden Plaats vervolgens het gemaakte PHP bestand in een via HTTP benaderbare map op de server, bijvoorbeeld via (s)ftp. Let erop dat het bestand leesbaar is voor de webserver. 3 Testen Voer de URL van het zojuist nieuw op de server geplaatste bestand in in een browser venster. Als alles goed is gegaan moet het encryptedid van het door u opgegeven contact worden weergegeven, zoals in het onderstaande voorbeeld. Stappenplannen MailPlus SOAP API 23

2.3.3 Opmerkingen - Standaard maakt PHP gebruik van een stdclass object voor het resultaat. Deze is als multidimensionale array uit te lezen zoals in het voorbeeld te zien is. Het is echter ook mogelijk om een mapping naar native PHP objecten uit te voeren. Meer hierover kunt u lezen op: http://nl.php.net/soapclient.soapclient (let op de optionele parameter classmap ). 2.4 C#.NET 2.4.1 Vereisten - Microsoft Visual C# 2008 Express Edition - Microsoft.NET Framework (in dit document wordt versie 3.5 SP1 gebruikt) 2.4.2 Stappen 1 Nieuw project Klik op New Project (of druk op Ctrl-Shift-N). In het venster dat nu verschijnt kiest u voor Console Application en vult u onderin bij Name: een naam in voor het nieuwe project (hier MailPlusClient ). Klik daarna op OK. Stappenplannen MailPlus SOAP API 24

2 Web Service Ondersteuning Klik vervolgens met de rechter muisknop op het rechts verschenen Project en kies in het menu op Add Reference. Scroll in de lijst die nu verschijnt naar beneden en selecteer System.Web.Services door hierop te klikken. Klik daarna op OK. Stappenplannen MailPlus SOAP API 25

3 Web Service Referentie toevoegen Klik nogmaals met de rechter muisknop op het project en kies nu voor Add Service Reference door hierop te klikken. Stappenplannen MailPlus SOAP API 26

Vul in het vak Address: de URL naar het benodigde WSDL bestand in en klik daarna op Go : http://api.mailplus.nl/apiservice/soap/contacts_v1.wsdl De benodigde informatie wordt nu opgehaald en Contacts_v1Service wordt in het witte vak getoond. Vul onderaan bij Namespace: de waarde ContactsService in. Klik daarna op OK. 4 API aanroepen Plaats de volgende code in de Main methode, zoals in de onderstaande afbeelding. Let erop dat u he juiste id, password en externalid meegeeft aan de getcontactbyexternalid methode. ContactsService.Contacts_v1Client client = new ContactsService.Contacts_v1Client(); ContactsService.contact contact = client.getcontactbyexternalid("123456", "abcdefgh", "1"); Console.WriteLine("EncryptedId: " + contact.encryptedid); System.Threading.Thread.Sleep(10000); Stappenplannen MailPlus SOAP API 27

5 Testen Klik daarna op Start Debugging of toets F5 om de applicatie te testen. Als alles naar behoren functioneert wordt het MailPlus encryptedid van het gekozen Contact gedurende 10 seconden weergegeven. Stappenplannen MailPlus SOAP API 28

2.4.3 Opmerkingen - C# Kent meerdere manieren om op basis van WSDL bestanden code te genereren en te integreren in uw projecten. Zo kan er ook direct gebruik gemaakt worden van wsdl.exe. De hier gedemonstreerde benadering is slechts een van de vele mogelijke. Stappenplannen MailPlus SOAP API 29

H3 Conclusie 3.1 Evaluatie De voorgaande stappenplannen laten zien dat het in de meeste courante ontwikkel omgevingen en talen relatief eenvoudig mogelijk is om een koppeling te kunnen realiseren met de MailPlus SOAP API. Dit stelt u als gebruiker van MailPlus in staat om een naadloze integratie met uw eigen software omgeving te (laten) realiseren. 3.2 Links - Java http://java.sun.com/ - PHP http://php.net/ -.Net Framework - Netbeans http://www.netbeans.org/ - Eclipse - Visual Studio.NET (Express) http://www.microsoft.com/express/vcsharp/ - Glassfish https://glassfish.dev.java.net/ - Tomcat http://tomcat.apache.org/ - Axis http://ws.apache.org/axis/ - Netbeans: Developing JAX-WS Web Service Clients http://www.netbeans.org/kb/docs/websvc/client.html Stappenplannen MailPlus SOAP API 30