Startseite     FAQ     Letzte Änderungen

Webservice

Aus Melin WebHelp

Wechseln zu: Navigation, Suche

Die Melin WebService Schnittstelle ermöglicht den Zugriff auf Melin-Funktionen über SOAP (Simple Object Access Protokoll). Die Implementierung erfolgt in Java AXIS, alle Aufrufe gehen über das Script „ws.jws“ das sich in tomcat/webapps/axis befindet.

Die vollständige Webservice-Dokumentation ist auch als PDF zum Download verfügbar

Das Script benötigt nur eine einzige Konfiguration - den Pfad zum Melin-Daemon in Zeile 17. 

String siteDir = "/home/melin/msite";

Die WSDL kann mit http://127.0.0.1:8200/axis/melin.jws?wdsl abgerufen werden (statt 127.0.0.1 ist die URL der Melin-Installation anzugeben, alternativ steht eine Web-Installation unter http://www.melin.de:8200/axis/melin.jws?wdsl zur Verfügung).

Als zentrales Hilfsmittel in der Implementierungsphase wird ein Logfile geschrieben: 

SITE-DIR/demon/logs/melin_jws[yyyyMMdd].log

Das SITE-DIR ergibt sich aus der allgemeinen Melin-Konfiguration.

Inhaltsverzeichnis


[bearbeiten] Funktionstest

Vor Inbetriebnahme sollte geprüft werden ob der Webservice aufgerufen werden kann und auch Zugriff auf die Datenbank hat:

[bearbeiten] ReadyCheck

Ein Funktionstest kann über die Methode readycheck via SOAP, oder mit jedem Webbrowser erfolgen: 

http://127.0.0.1:8200/axis/melin.jws?method=readyCheck

Als Rückgabe wird ein „ok“ geliefert: 

 <soapenv:Envelope
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:Body>
 <ns1:readyCheckResponse xmlns:ns1="http://127.0.0.1:8200/axis/melin.jws"
 soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <readyCheckReturn xsi:type="xsd:string">ok</readyCheckReturn>
 </ns1:readyCheckResponse>
 </soapenv:Body>
 </soapenv:Envelope>

ReadyCheck prüft ob die Datenbank erreichbar ist und damit auch ob alle Konfigurationsdateien gefunden werden können.

[bearbeiten] Version

Die Methode version liefert die Versionsnummer des Webservice als String zurück und ist ab 4.00.627 verfügbar. 

<versionReturn xsi:type="xsd:string">4.00.629</versionReturn>

Version und ReadyCheck benötigen keine zusätzlichen Parameter.

[bearbeiten] Abruf mit Webbrowser

Die meisten Funktionen des Webservice lassen sich auch einfach über den Browser testweise aufrufen. Von Vorteil ist diese Art des Aufrufs wenn von einer Website direkt Funktionen aktiviert werden sollen, zum Beispiel über JavaScript.

http://127.0.0.1:8200/axis/melin.jws?method=deleteClientByID&clientID=12

Die Rückgabe erscheint wie folgt: 

<?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>
<deleteClientByIDResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<deleteClientByIDReturn xsi:type="xsd:string">ok</deleteClientByIDReturn>
</deleteClientByIDResponse>
</soapenv:Body>
</soapenv:Envelope>


Damit lässt sich der Webservice auch ohne komplettes SOAP-Framework nutzen. In PHP, Perl oder Java reicht es die Ergebniszeile herauszufiltern, im Beispiel oben: 

<deleteClientByIDReturn xsi:type="xsd:string">ok</deleteClientByIDReturn>

[bearbeiten] An- und Abmelden von Abonnenten

Die meisten Funktionen des Webservice werden via SOAP aufgerufen, jedoch gibt es für Standardfälle auch die Möglichkeit per URL die Parameter zu übergeben. Speziell wenn es darum geht einfache An- und Abmeldungen vorzunehmen ist diese Methode gut geeignet, oder um abzufragen welche Newsletter ein Abonnent abonniert hat. Für komplexe Anmeldungen die über die Parameter hier hinausgehen ist SOAP zwingend erforderlich.

[bearbeiten] Anmeldung - simpleAddSubscription

Neuanlage eines Abonnenten bezw. hinzufügen eines neuen Abonnements.

Der Aufruf kann einfach per URL erfolgen, zum Beispiel: 

http://127.0.0.1:8200/axis/melin.jws?method=simpleAddSubscription&newsletter_id=5&email=seb@melin.de

Die Felder „email“ und „newsletter_id“ sind Pflichtfelder, alle weiteren Felder sind optional. Im Feld useDoubleOptIn kann entweder der String „true“ oder eine „1“ übergeben werden wenn der Datensatz nicht direkt in die Datenbank geschrieben werden soll sondern stattdessen vorab eine DoubleOptIn-Mail verschickt werden soll.

Der Aufruf von simpleAddSubscription kann noch um die Parameter returnCustomFieldOK und returnCustomFieldFalse erweitert werden. Beide Parameter können einen Wert von 1-5 haben. Im Erfolgsfall wird der Wert aus der Spalte CUSTOM[1-5] in der Tabelle NEWSLETTER_INDEX ausgelesen und zurückgegeben.

Diese Werte können in Melin in der Empfängerlistenverwaltung gesetzt werden (siehe auch SimpleRemoveSubscription).

[bearbeiten] Abmeldung - simpleRemoveSubscription

Abmelden eines Abonnenten von einem Newsletter.

Der Aufruf kann einfach per URL erfolgen, zum Beispiel: 

http://127.0.0.1:8200/axis/melin.jws?method=simpleRemoveSubscription
&newsletter_id=5&email=seb@melin.de

Die Felder „email“ und „newsletter_id“ sind Pflichtfelder.

Die Funktion simpleRemoveSubscription wird manchmal auch für indirekte Abmeldungen genutzt (siehe auch simpleAddSubscription). Auf der Website wird ein einfaches Abmeldescript (z.B. „unsubscribe.php“) installiert das als Parameter die Emailadresse und die NewsletterID für eine Abmeldung erhält. Der Aufruf kann so aussehen und direkt aus der Mail erfolgen: 

http://mhv-newsletter.de/unsubscribe.php?email=ld@melin.de&nl=6

Bei einer Abmeldung über einen Link wird auch immer eine Weiterleitung auf zwei Bestätigungsseiten benötigt. Diese kann man elegant über Melin in der Empfängerlistenverwaltung hinterlegen:

Hinweis: Die Zusatzparameter sind konfigurierbar, in diesem Beispiel wurden die Felder CUSTOM4 und CUSTOM5 dazu verwendet und die Beschreibung „Abmeldung-OK“ und „Abmeldung-Fehler“ dazu in der Konfigurationsdatei msite/demon/config/nl_customfields.xml eingetragen.

Intern ruft das Abmeldescript den Webservice auf und ergänzt den Aufruf um die beiden Parameter returnCustomFieldOK und returnCustomFieldFailed. Als Wert wird eine Spalte aus der Tabelle NEWSLETTER_INDEX angeben, in unserem Fall CUSTOM4 und CUSTOM5.

In PHP kann das so aussehen: 

if (($NEWSLETTER_ID>0) && (trim($email))) {
// Connect to Webservice and grab request
$request = "http://127.0.0.1:8200/axis/melin.jws?";
$request .= "method=simpleRemoveSubscription&";
$request .= "newsletter_id=".$NEWSLETTER_ID."&email=$email";		
$request .= "&returnCustomFieldOK=CUSTOM4&returnCustomFieldFailed=CUSTOM5";		
	$link = file_get_contents($request); 
	$link = preg_replace("/\<[^\>\<]*\>/", "", $link);
	$link = preg_replace("/\s/", "", $link);		
} // Unsubscribe
header('Location: '. $link);

Als Rückgabe liefert der Webservice dann eine URL zu der weitergeleitet werden soll.

[bearbeiten] Abmeldung - simpleRemoveSubscriptionByID

Abmelden eines Abonnenten von einem Newsletter mit Melin-Interner ID (SYSTEM_CUSTOMER_ID) und NewsletterID.

Der Aufruf kann einfach per URL erfolgen, zum Beispiel: 

http://127.0.0.1:8200/axis/melin.jws?method=simpleRemoveSubscription
&newsletter_id=5&SYSTEM_CUSTOMER_ID=100001
  • Die Felder „SYSTEM_CUSTOMER_ID“ und „newsletter_id“ sind Pflichtfelder.

Wird zur Kundennummer keine E-Mail-Adresse gefunden so wird „No e-Mail for SYSTEM_CUSTOMER_ID “ zurückgegeben. Bei erfolgreicher Abmeldung „ok“. Besteht kein Abonnement wird „no subscription“ zurückgegeben. Prüfen - simpleCheckSubscription

[bearbeiten] Prüfen ob für eine Emailadresse und eine Newsletter ID ein Abonnement besteht.

Der Aufruf kann einfach per URL erfolgen, zum Beispiel: 

http://127.0.0.1:8200/axis/melin.jws?method=simpleCheckSubscription
&newsletter_id=5&email=seb@melin.de
  • Die Felder „email“ und „newsletter_id“ sind Pflichtfelder.


[bearbeiten] Mandantenfunktionen

Über den Webservice lassen sich auch Melin-Nutzeraccounts verwalten. Eingesetzt wird diese Schnittstelle in Hosting-Installationen die über den Webservice automatisch neue Accounts erstellen und wieder löschnen.

[bearbeiten] Mandant anlegen 

public String createClient( String clientName )

Hinweis. Mandanten-Name muss eindeutig sein. Rückgabe ist die interne ID

<?xml version="1.0" encoding="UTF-8"?> <DOCUMENT> <ID>15</ID> </DOCUMENT>

[bearbeiten] Mandant anlegen mit ID 

public String createClientByID( String clientName, String clientID )

Hinweis. Mandanten-Name muss eindeutig sein. Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“.


[bearbeiten] Mandanteninfo holen 

public String getClientInfo( String clientName ) {

Hinweis: Mandanten-Name muss eindeutig sein. Rückgabe ist die interne ID (ClientID)


[bearbeiten] Mandant löschen

public String deleteClient( String ClientID) {

Hinweis. Mandanten-Name muss eindeutig sein. Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“.


[bearbeiten] Empfängerlisten

Empfängelisten (anderer Name: Verteilerlisten, Newsletter) können vollständig über den Webservice administriert werden.

[bearbeiten] Verteilerliste anlegen ohne ID

Erforderliche Parameter: Name des Newsletters, Mandanten-ID

public String createNewsletterByName( String newsletterName, String ClientID ) {

Rückgabewert ist die NewsletterID.


[bearbeiten] Verteilerliste anlegen mit ID

Erforderliche Parameter: NewsletterID, Name des Newsletters, Mandanten-ID

public String createNewsletterByID( String newsletterID, String newsletterName, String ClientID )

Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“.

[bearbeiten] Verteilerliste löschen nach Name

public String deleteNewsletterByName( String newsletterName )

Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“. Der Name muss eindeutig sein.


[bearbeiten] Verteilerliste löschen nach NewsletterID 

public String deleteNewsletterByID( String newsletterID )

Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“.

[bearbeiten] Verteilerliste umbenennen 

public String renameNewsletterByName( String newsletterName, String newsletterNewName )

Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“.

[bearbeiten] Verteilerliste umbenennen nach ID 

public String renameNewsletterByID( String newsletterID, String newsletterNewName )

Rückgabe ist „ok“ wenn erfolgreich oder ein Fehler-String beginnend mit „error“.

[bearbeiten] Prüfen ob Emailadresse einen Newsletter abonniert hat 

public String checkSubscription( String email, String NEWSLETTER_ID )

Rückgabe ist „true“ wenn ja, „false“ wenn nein. Die komplette Rückgabe lautet: 

<?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&>
<checkSubscriptionResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&>
<checkSubscriptionReturn xsi:type="xsd:string"&>
<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>true</DOCUMENT>
</checkSubscriptionReturn>
</checkSubscriptionResponse>
</soapenv:Body>
</soapenv:Envelope>

Auf diese Weise kann nur durch den Aufruf einer URL geprüft werden ob ein User bereits ein Abo hat: 

http://melin.de:8200/axis/melin.jws?method=checkSubscription&email=
seb@melin.de&NEWSLETTER_ID=2101&pw=sendling

[bearbeiten] Abruf aller Newsletter auf die ein Mandant Zugriff hat 

public String getNewsletterIDsByClientID ( int clientID )

Übergeben wird die MandantenID (clientID). Als Rückgabe erhält man einen String mit allen NewsletterIDs durch Komma getrennt.

Beispiel für die Rückgabe: 

<getNewsletterIDsByClientIDReturn xsi:type="xsd:string">26,38,34,52,45,57</getNewsletterIDsByClientIDReturn>
</ns1:getNewsletterIDsByClientIDResponse>


[bearbeiten] Abruf des Namens eines Newsletters mit ID 

public String getNewsletterNameByNewsletterID ( String newsletterID)

Übergeben wird die ID des Newsletters. Als Rückgabe erhält man einen String mit dem Namen des Newsletters.

Beispiel für die Rückgabe: 

<getNewsletterNameByNewsletterIDReturn xsi:type="xsd:string">
    TestNL
</getNewsletterNameByNewsletterIDReturn>

[bearbeiten] Funktionen mit Kundennummer

Die Funktionen mit Kundennummer ermöglichen den Zugriff auf die Melin-Abonnentendaten mit Hilfe einer Kundennummer statt der E-Mail-Adresse.

[bearbeiten] Hinzufügen eines neuen Abonnenten mit Kundennummer 

public String addSubscriberByCustomerID ( 
		String kunde_nr, 
		String email, 
		String newsletter_id,
		String first_name, 
		String last_name, 
		String salutation, 
		String gender, 
		String title, 
		String city, 
		String zip_code, 
		String ad_permission, 
		String affiliate,
		String company, 
		String language,
		String area,
		String custStatus,
		String kpnr,
		String country,
		String branchenverteiler,
		String branchenkennzeichenKD,			
		String branchenkennzeichenKP)

Notwendige Parameter sind E-Mail-Adresse und Kundennummer. Alle weiteren Parameter sind optional.

Wenn bereits ein Datensatz hinter der Kundennummer hinterlegt ist werden die Daten aktualisiert. Wenn bereits ein Abonnement des Newsletters mit der Kundennummer besteht, werden die Daten ebenfalls nur aktualisiert, es wird keine Doublette erzeugt, auch wenn die Funktion mehrfach aufgerufen wird.

Um ein bestehendes Feld zu leeren übergibt man einen leeren Wert.

  • Das Feld „Gender“ erwartet einen Parameter „M“ oder „F“ (für Männlich/Male oder Weiblich/Female). Der Parameter ist optional.
  • Das Feld "ad_permission" ist für eine Werbefreigabe. Oftmals wird eine Werbeerlaubnis bei der Newsletter-Anlage mit abgefragt, diese kann hier hinterlegt werden.

Ein Beispiel beim dem Felder nur teilewise befüllt sind kann so aussehen:

Die Rückgabe ist "ok" wenn die Operation erfolgreich war. Weitere Hinweise im Fehlerfall finden sich im Logfile. Im Feld useDoubleOptIn kann entweder der String „true“ oder eine „1“ übergeben werden wenn der Datensatz nicht direkt in die Datenbank geschrieben werden soll sondern stattdessen vorab eine DoubleOptIn-Mail verschickt werden soll.

[bearbeiten] Stammdatenabfrage mit Kundennummer 

public String getSubscriberDetailByCustomerID( String kunde_nr )

Einziger Parameter ist die Kundennummer.

Die Kundennummer kann bis zu 50 Zeichen umfassen und ist frei wählbar. Zum Test kann auch über die Oberfläche ein Abonnent hinzugefügt werden und dort im Feld „Kunde Nr“ ein Wert hinterlegt werden. Anschließend kann der Datensatz ebenfalls direkt über den Webservice abgerufen werden.

Es werden alle Basisdaten zum Benutzer zurückgeliefert als Array inklusive der benutzerdefinierten Felder, sowie alle aktiven Abonnenements.

Beispiel für einen Abonnenten der einen Newsletter (z.B. mit ID 100) abonniert hat: 

<getSubscriberDetailByCustomerIDReturn xsi:type="xsd:string">
<?xml version="1.0" encoding="UTF-8"?&>
<document&>
<SYSTEM_CUSTOMER_ID>1000017</SYSTEM_CUSTOMER_ID&>
<EMAIL>ld@melin.de</EMAIL&>
<GENDER>M</GENDER&>
<ANREDE>Herr</ANREDE&>
<COUNTRY>DE</COUNTRY&>
<KUNDE_NR>MELIN010</KUNDE_NR&>
<CREATED>20080712212854</CREATED&>
<LAST_MODIFIED>20080712212854</LAST_MODIFIED&>
<AREA>Bayern</AREA&>
<CUST_STATUS>5</CUST_STATUS&>
<KPNR>0123456</KPNR&>
<BRANCHENVERTEILER>nielsen9</BRANCHENVERTEILER&>
<BRANCHENKENNZEICHEN>xyz1234</BRANCHENKENNZEICHEN&>
<BRANCHENKENNZEICHEN_KP>abcd-1234</BRANCHENKENNZEICHEN_KP&>
<NEWSLETTER_ID100>1</NEWSLETTER_ID100&>
</document>
</getSubscriberDetailByCustomerIDReturn>
</ns1:getSubscriberDetailByCustomerIDResponse>

[bearbeiten] Abmelden von einem Newsletter mit Kundennummer 

public String unsubscribeByCustomerID( String kunde_nr, String newsletter_id)

Diese Funktion meldet einen Kunden von einem Newsletter ab. Pflicht-Parameter ist die Kundennummer und die NewsletterID. Die NewsletterID wird innerhalb von Melin bei der Anlage einers Newsletters (=Empfängerliste, Verteilerliste) vergeben.

Rückgabe der Funktion ist „ok“ wenn kein Fehler aufgetreten ist, ansonsten wird der Fehler im Klartext übergeben, beginnend mit dem Schlüsselwort „Error:“.


[bearbeiten] Löschen eines kompletten Abonnentendatensatzes mit Kundennummer 

public String deleteSubscriberByCustomerID (
String kunde_nr, String affiliate, String remote_ip )

Diese Funktion löscht einen kompletten Abonnenten und meldet ihn von allen Newslettern ab. Einziger Pflicht-Parameter ist die Kundennummer.

  • „Affiliate“ ist eine beliebige Kennung, hier kann ein Abmeldegrund oder eine Abmeldequelle hinterlegt werden (50 Zeichen maximal).
  • „RemoteIP“ kann verwendet werden um die IP-Adresse zu hinterlegen von der die Abmeldung kam. Dieser Wert kann ebenfalls null sein.
  • Rückgabe der Funktion ist „ok“ wenn kein Fehler aufgetreten ist, ansonsten wird der Fehler im Klartext übergeben, beginnend mit dem Schlüsselwort „Error:“.

[bearbeiten] Abfragen von Mailings

Verschickte Mailings werden alle in der Datenbank abgelegt. Über einfache Funktionen lassen sich Listen der versandten Mailings abrufen, und Details zu jedem Mailing.

[bearbeiten] Abruf aller Mailings an eine bestimmte NewsletterID 

public String getMailingHeader(int newsletter_id)

Liefert eine Liste von Mailings die an eine bestimmte NewsletterID geschickt wurden. Die Rückgabe erfolgt in einer XML-Datei die für jedes Mailing einen Eintrag <MAILING> enthält. 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<MAILING id='NL87264572'> 
   <SUBJECT>News Aktuell, Dezember 2008</SUBJECT> 
   <M_FROM>news@melin.com</M_FROM> 
   <M_SENDER>NewsAktuell</M_SENDER> 
   <NEWSLETTER_ID>5</NEWSLETTER_ID> 
   <USERCOUNT>2322</USERCOUNT> 
   <MAILING_ID>NL87264572</MAILING_ID> 
   <CREATED>20081215073000</CREATED> 
   <ABSTRACT>News Aktuell 12/2008

--------------------

Sehr geehrte Frau Mustermann, anbei die neuesten Informationen aus Funk und 
Fernsehen....</ABSTRACT> 
</MAILING>
<MAILING id='NL87264576'> 
   <SUBJECT>News Aktuell, November 2008</SUBJECT> 
   <M_FROM>news@melin.com</M_FROM> 
   <M_SENDER>NewsAktuell</M_SENDER>
...
</DOCUMENT>

[bearbeiten] Abfragen von Mailing-Details 

public String getMailingDetails(String mailing_id)

Der Volltext (Text und HTML) kann mit Hilfe der MailingID abgefragt werden. Die Rückgabe ist wieder eine XML-Datei, die ähnliche Felder enthält wie die Liste der Mailings, plus die Felder M_FULLTEXT (Textversion), M_FULLHTML (HTML-Version) und ggf. M_PDF, ein Link auf eine PDF-Version. 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<MAILING id='NL87264572'> 
   <SUBJECT>News Aktuell, Dezember 2008</SUBJECT> 
   <M_FROM>news@melin.com</M_FROM> 
   <M_SENDER>NewsAktuell</M_SENDER> 
   <NEWSLETTER_ID>5</NEWSLETTER_ID> 
   <USERCOUNT>2322</USERCOUNT> 
   <MAILING_ID>NL87264572</MAILING_ID> 
   <CREATED>20081215073000</CREATED> 
   <ABSTRACT>News Aktuell 12/2008 
-------------------- 
Sehr geehrte Frau Mustermann, anbei die neuesten 
Informationen aus Funk und Fernsehenen....
</ABSTRACT> 
<M_FULLTEXT>News Aktuell 12/2008
--------------------
Sehr geehrte Frau Mustermann, anbei die neuesten 
Informationen aus Funk und Fernsehenen, für Sie
</FULLTEXT> 
<M_FULLHTML><html> <body>News Aktuell 12/2008
--------------------
Sehr geehrte Frau Mustermann, anbei die neuesten Informationen 
aus Funk und Fernsehenen, für Sie 
</body> </html></FULLHTML> 
<M_PDF>/melin/tmp/234zu23t4u.pdf</M_PDF>
</MAILING>

[bearbeiten] Volltextsuche in Mailings 

public String mailingFulltextSearch(String searchString)

Liefert eine Liste von MailingIDs zurück die den gewünschten Suchtext enthalten. 

<RESULT> 
	<MAILING id='NL87264572'>
	<SUBJECT>News Aktuell, Dezember 2008</SUBJECT> 
	<M_FROM>news@melin.com</M_FROM>
	<M_SENDER>NewsAktuell</M_SENDER> 
	<NEWSLETTER_ID>5</NEWSLETTER_ID>
	<USERCOUNT>2322</USERCOUNT>
	<MAILING_ID>NL87264572</MAILING_ID>
	<CREATED>20081215073000</CREATED> 
	<ABSTRACT>News Aktuell 12/2008 -------------------- 
 	Sehr geehrte Frau Mustermann, anbei die neuesten 
 	Informationen aus Funk und Fernsehenen....</ABSTRACT>
	</MAILING> 

	<MAILING id='NL87264575'>
	<SUBJECT>News Aktuell, November 2008</SUBJECT> 
	<M_FROM>news@melin.com</M_FROM>
	<M_SENDER>NewsAktuell</M_SENDER> 
	<NEWSLETTER_ID>5</NEWSLETTER_ID>
	<USERCOUNT>2322</USERCOUNT>
	<MAILING_ID>NL87264575</MAILING_ID>
	<CREATED>20081115073000</CREATED> 
	<ABSTRACT>News Aktuell 11/2008 --------------------
 	Sehr geehrte Frau Mustermann, anbei wieder die 
 	neuesten Informationen aus Funk und Fernsehenen....
	 </ABSTRACT>
	</MAILING> 
	
</RESULT>

[bearbeiten] Robinsonliste

Melin führt eine Unternehmensweite Robinsonliste die alle Adressen beinhaltet die nicht bemailt werden dürfen. Adressen die in dieser Liste enthalten sind erhalten keine E-Mails, auch keine Anmelde-Mails (Double-Opt-In). Groß/Kleinschreibung ist bei der E-Mail Adresse egal.

[bearbeiten] Suche nach Email in der Robinsonliste 

public String robinsonSearchByEmail(String email)

Sucht nach einer gegebenen E-Mail-Adresse in der Datenbank. Die Rückgabe ist „1“ wenn die Adresse gefunden wurde und „0“ wenn sie nicht in der Liste enthalten ist. Bei einem Datenbank-Ausfall wird „ERROR“ gefolgt von einer Fehlermeldung zurückgegeben.

[bearbeiten] Hinzufügen einer Adresse in die Robinsonliste 

public String robinsonAddEmail (String email)

Fügt eine Emailadresse zur Robinsonliste hinzu. Rückgabe ist „1“ wenn die Operation erfolgreich ist, ansonsten 0. Wenn die Adresse bereits vorhanden ist wird ebenfalls eine „1“ zurückgegeben.

[bearbeiten] Löschen einer Adresse aus der Robinsonliste 

public String robinsoRemoveEmail (String email)

Löscht eine Emailadresse aus der Robinsonliste. Rückgabe ist „1“ wenn die Operation erfolgreich ist. Ist die Adresse nicht vorhanden wird eine „0“ zurückgegeben.

Die Robinson-Funktionen im Webservice arbeiten immer mit der MMDB und nicht mit eventuell zusätzlich konfigurierten Sperrdatenbanken.



[bearbeiten] Anliefern von Daten via XML im SOAP-Request

Eine Beispielimplementierung für die Anlieferung eines Mailings findet sich hier: 

http://127.0.0.1:8200/melin/ws_test.jsp

Der Webservice stellt für die meisten Anforderungen eine generische Funktion workflowSubmit zur Verfügung, die zwei Parameter erwartet und den zweiten Parameter an den Melin-Workflow übergibt:

workflowDir Dateipfad innerhalb des „msite“-Verzeichnis in dem die Datei abgelegt werden soll.

xmlCode Code der an den Workflow übergeben werden soll.

Beispiel für XML-Code: 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<EMAIL>muster@melin.de</EMAIL>
</DOCUMENT>


[bearbeiten] Felder für Newsletter

  • M_RECEIVER Test-Empfänger
  • FROM Absender-Email
  • M_SENDER Absender-Name
  • __CREATOR NANOCMS (Konstante)
  • M_TEMPLATE SITE-DIR/templates/multipart.txt (Konstante)
  • M_IS_MULTIPART 1 (Konstante)
  • MAILING_ID Bezeichner (255 Zeichen)
  • SUBJECT Betreff
  • NEWSLETTER_ID ID des Verteilers (optional)
  • X_BODY Body der Mail
  • __DOCID ID (Beliebig, muss mit Wert gesetzt sein)

Beispiel-Datei 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<X_BODY>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<title>webBank Newsletter</title>
</head>
<body>

Ein erstes HTML-Mailing 

</body>
</html>

<!--TEXT_REPRESENTATION-->

webBank Newsletter vom 08.12.2006
------------------------------------------------------------------

Das hier ist die Textversion.

<!--/TEXT_REPRESENTATION-->

</X_BODY>
<__DOCID>1170414791114</__DOCID>
<M_RECEIVER>seb@localhost</M_RECEIVER>
<FROM>absender@localhost</FROM>
<M_SENDER>Melin Demo</M_SENDER>
<__CREATOR>NANOCMS</__CREATOR>
<M_TEMPLATE>SITE-DIR/templates/multipart.txt</M_TEMPLATE>
<M_IS_MULTIPART>1</M_IS_MULTIPART>
<MAILING_ID>1170414791114</MAILING_ID>
<SUBJECT>webBank Newsletter vom 08.12.2006</SUBJECT>
<NEWSLETTER_ID>webBank Newsletter vom 08.12.2006</NEWSLETTER_ID>
</DOCUMENT>

Beispiel-Werte für workflowDir 

Vorschau	/cms/preview/preview/sample.xml

Live-Versand	/cms/export/sample.xml
(Muss eine NEWSLETTER_ID enthalten)


[bearbeiten] Felder für Anmeldung

  • EMAIL Emailadresse
  • NEWSLETTER_ID Newsletter ID
  • FIRST_NAME Vorname (optional)
  • LAST_NAME Nachname (optional)
  • SC_TITLE Titel (optional)
  • ANREDE Anrede (optional)
  • PAGE Kennung für Anmeldebestätigungsdaten (optional)
  • aus Melin An/Abmeldeseiten, z.B.
  • localhost,index.html,1159359181080,1172435315864
  • TYP 1
  • LOCATION_REDIRECT Optional, Weiterleitungsziel

Wert für workflowDir: 

/usv/web/*.xml

[bearbeiten] Felder für Abmeldung

  • EMAIL Emailadresse
  • NEWSLETTER_ID Newsletter ID
  • PAGE Kennung für Abmeldemail (optional) aus Melin An/Abmeldeseiten, z.B. localhost,index.html,1159359181080,1172435315864
  • TYP 2
  • LOCATION_REDIRECT Optional, Weiterleitungsziel

Wert für workflowDir: 

/usv/web/*.delete


[bearbeiten] Felder für Nachprofilierung

  • EMAIL Emailadresse
  • NEWSLETTER_ID Newsletter ID
  • FIRST_NAME Vorname (optional)
  • LAST_NAME Nachname (optional)
  • SC_TITLE Titel (optional)
  • ANREDE Anrede (optional)
  • PAGE Kennung für Anmeldebestätigungsdaten
  • aus Melin An/Abmeldeseiten, z.B.
  • localhost,index.html,1159359181080,1172435315864
  • TYP 3
  • REMOVE_NEWSLETTER_IDxxx Xxx (NewsletterID, zum Austragen)
  • LOCATION_REDIRECT Optional, Weiterleitungsziel

Wert für workflowDir: 

/usv/web/*.modify

[bearbeiten] Allgemeine Funktionen des Webservice

[bearbeiten] Details zu einem Mailing abfragen 

public String getMailingInformation( String mailingID )

Gibt eine XML-Datei zurück mit Anzahl Empfänger, Öffnungen, Clicks, Clicks Unique, allen gemessenen Links mit Anzahl klicks.

Beispiel: 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<OPEN>112</OPEN>
<RECIPIENTS>112</RECIPIENTS>
<CLICKS>112</ CLICKS >
<CLICKS_UNIQUE>97</CLICKS_UNIQUE>
<LINK1>http://www.melin.de</LINK1>
<COUNT1>51</COUNT1>
<LINK2>http://www.melin.de/news</LINK2>
<COUNT2>51</COUNT2>
</DOCUMENT>

[bearbeiten] Empfängerliste eines Newsletters

Zurückliefern der Empfängerliste auf Basis der newsletterID 

public String public String getSubscriberListByID( String newsletterID )  {

Beispiel: 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<EMAIL>seb@melin.de</EMAIL>
<EMAIL>john@nanocms.com</EMAIL>
<EMAIL>john12@nanocms.com</EMAIL>
</DOCUMENT>

[bearbeiten] Zurückliefern der Empfängerliste auf Basis des Empfängerlisten-Namen 

public String getSubscriberListByName( String newsletterName ) {

Beispiel: 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<EMAIL1>seb@melin.de</EMAIL1>
<EMAIL2>john@nanocms.com</EMAIL2>
<EMAIL3>john12@nanocms.com</EMAIL3>
</DOCUMENT>

[bearbeiten] Details eines Abonnenten 

public String getSubscriberDetails( String email )

Beispiel: 

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
<EMAIL>seb@melin.de</EMAIL>
<LAST_NAME>Böttger</LAST_NAME>
<NEWSLETTER_ID100>100</NEWSLETTER_ID100>
<NEWSLETTER_ID105>105</NEWSLETTER_ID105>
</DOCUMENT>



[bearbeiten] Änderungshistorie

Die Änderungshistorie des Webservice wurde auf eine eigene Seite ausgelagert.
Von „http://www.melin.com/de/wiki_help/index.php/Webservice“