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


1

componenten beschikbaar in de ontwikkel omgeving. Steeds wordt op basis van een ‘externalId’ een Contact opgehaald, waarbij het ‘encryptedId’ wordt getoond.


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 >’.


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’.


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:


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.


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.


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’.


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).


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


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:


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’.


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.


13

Klik daarna in het verschenen venster aan de linker kant op ´Project Facets´ en vink Áxis2 Web Services´ aan. Klik daarna op ÓK´.

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 Ńew´ te bewegen naar Óther´.


14

Klap in het verschenen venster het mapje ´Web Services´ uit en selecteer ´Web Service Client´. Klik vervolgens op Ńext >´.


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’.


16

4 Servlet Aanmaken Klik nogmaals met de rechter muisknop op uw Project en beweeg via ‘New’ naar ‘Servlet’ en klik hierop.


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’.


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(); }


19

Uiteraard dient u het ‘id’, ‘password’ en ‘externalId’ te vervangen met de gegevens die bij u bekend zijn.


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:

2.3 2.3.1 -

org.apache.axis2.webapp.AxisAdminServlet

PHP 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.


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:


22

'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.


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 2.4.1

C# .NET 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’.


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’.


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.


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);


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.


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.


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


30

Stappenplannen MailPlus SOAP API

Recommend Documents