20. Appendix B - Application examples
Content of this chapter
Appendix B describes with help of specific examples how different methods can be used.
20.1. B.1 General
The following examples show some typical use cases. The examples are written in PHP. Please note that the following code examples need the class WsseSoapClient (file "WSSESoapClient.php"). The file can be downloaded at:
This class is based on the PHP's own SOAP client and implements the WSSE authentication procedure. Interested parties or developers wanting to work with other program languages (particularly those for which no SOAP framework with WSSE authentication is available) will get an insight here into the calculation of the values concerned for the WSSE-SOAP headers.
The examples have been deliberately kept simple; there has been no error or exception handling. A SOAP fault (and, depending on the program language, possibly an exception associated with it) can be generally expected in every web service request.
20.2. B.2 Creating recipient and connecting to mailing list
The following example shows how recipients are created via the web service interface and connected to a mailing list.
Note: Some of the available SOAP clients do not provide information on data types in a SOAP request, and these include the PHP SOAP client. As a consequence, recipient registrations or profile amendments with valid data will fail. A KeyValuePair helper class is therefore necessary, via which the requisite information is defined.
<?php
class KeyValuePair {
public $key;
public $value;
function __construct($key, $value) {
$this->key = new SoapVar(
$key, XSD_STRING, "string", "http://www.w3.org/2001/XMLSchema");
$this->value = new SoapVar(
$value, XSD_STRING, "string", "http://www.w3.org/2001/XMLSchema");
}
}
// ***********************************************************************
// Step 1: Setup
// ***********************************************************************
// Include SOAP client class
include('WSSESoapClient.php');
$url = 'write your WSDL URL here';
$username = 'write your username here';
$password = 'write your password here';
$mailinglistId = 12345; // Write your mailing list ID here
// ***********************************************************************
// Step 2: Create SOAP client
// ***********************************************************************
$client = new WsseSoapClient($url, $username, $password);
// ***********************************************************************
// Step 3: Create a subscriber
// ***********************************************************************
$profileFields = array(
new KeyValuePair("email", "test@example.com"),
new KeyValuePair("mailtype", "0"),
new KeyValuePair("gender", "0")
);
$data = array(
"parameters" => $profileFields,
"doubleCheck" => true,
"keyColumn" => "email",
"overwrite" => true
);
$result = $client->AddSubscriber($data);
$subscriberId = $result->customerID;
echo "Created subscriber $subscriberId\n";
// ***********************************************************************
// Step 4: Bind subscriber to mailing list
// ***********************************************************************
$data = array(
"customerID" => $subscriberId,
"mailinglistID" => $mailinglistId,
"mediatype" => 0,
"status" => 5, // Set to "waiting for DOI confirmation"
"userType" => "T",
"remark" => "Set by webservice",
"exitMailingID" => 0
);
$client->SetSubscriberBinding($data);
echo "Bound subscriber to mailinglist\n";
?>
Explanations
Step 1 comprises merely loading the SOAP client's class and initialising some variables, which will be used in the course of the program.
Step 2 shows the minimum constructor call for the SOAP client with username, password and URL of the WSDL document. Once initialised, the SOAP client can be used again for as many web service request as desired.
Step 3 creates the requisite data structures to enter a new recipient and calls up the AddSubscriber web service. For this purpose, a list of items of class KeyValuePair is created, which contains the profile fields with their associated values ($profileFields). The data for the request of AddSubscriber are stored in a second array, which is transmitted to the AddSubscriber method as a parameter. The return value of the method supplies the new recipient's ID.
This ID is needed in Step 4 in order to register the recipient on a mailing list.
20.3. B.3 Creating, filling and dispatching mailing
The following example shows how a new mailing is created, filled and finally sent.
<?php
// ***********************************************************************
// Step 1: Setup
// ***********************************************************************
// Include SOAP client class
include('WSSESoapClient.php');
$url = 'write your WSDL URL here';
$username = 'write your username here';
$password = 'write your password here';
$mailinglistId = 12345; // Write your mailing list ID here
// ***********************************************************************
// Step 2: Create SOAP client
// ***********************************************************************
$client = new WsseSoapClient($url, $username, $password);
// ***********************************************************************
// Step 3: Create a new mailing
// ***********************************************************************
$data = array(
"shortname" => "This is your new mailing",
"description" => "Description of your new mailing",
"mailinglistID" => $mailinglistId,
"targetIDList" => 0,
"matchTargetGroups" => "one",
"mailingType" => "regular",
"subject" => "Test newsletter",
"senderName" => "Test sender",
"senderAddress" => "sender@example.com",
"replyToName" => "Test reply",
"replyToAddress" => "noreply@example.com",
"charset" => "utf-8",
"linefeed" => 72,
"format" => "offline-html",
"onePixel" => "top"
);
$result = $client->AddMailing($data);
$mailingId = $result->mailingID;
echo "Created mailing $mailingId\n";
// ***********************************************************************
// Step 4: Fill content of mailing
// ***********************************************************************
$textBlockName = "emailText";
$htmlBlockName = "emailHtml";
// First, we will the text block
$data = array(
"mailingID" => $mailingId,
"blockName" => $textBlockName,
"targetID" => 0,
"content" => "This is plain text content.",
"order" => 1
);
$result = $client->AddContentBlock($data);
$textBlockId = $result->contentID;
echo "Created text content $textBlockId\n";
// Then, we create the HTML block
$data["blockName"] = $htmlBlockName;
$data["content"] = "<html><body>HTML content</body></html>";
$result = $client->AddContentBlock($data);
$htmlBlockId = $result->contentID;
echo "Created HTML content $htmlBlockId\n";
// ***********************************************************************
// Step 5: Send mailing
// ***********************************************************************
$now = new DateTime();
$now->add( new DateInterval("PT60S"));
$nowString = $now->format("Y-m-d H:i:s T");
$data = array(
"mailingID" => $mailingId,
"recipientsType" => "test",
"sendDate" => $nowString
);
$result = $client->SendMailing($data);
echo "Sent mailing\n";
?>
Explanations
Step 1 comprises merely loading the class of the SOAP client and initialising some variables, which will be used in the later course of the program.
Step 2 shows the minimum constructor call for the SOAP client with username, password and URL of the WSDL document. Once initialised, the SOAP client can be used again for as many web service requests as desired.
In Step 3 the basic information for the mailing is saved in an array and the array transmitted as a parameter to the request of the AddMailing web service method. The return value of this method contains the new mailing's ID.
A new mailing contains two blocks, "emailText" and "emailHtml", which represent the contents for the mailing's text or HTML display. These blocks are filled in the course of Step 4 through call-ups to the "AddContentBlock" web service method. A separate request is necessary for each block.
Step 5 involves sending of the mailing. In the example, a letter is sent to all test recipients. Although dispatch to test or admin recipients is made immediately, this step shows how a date must be formatted for a world dispatch.
20.4. B.4 Updating recipient data
The following example shows how existing recipients' profile data are updated.
Note: Some of the available SOAP clients do not transfer information on data types in a SOAP request, and these include the PHP SOAP client. As a consequence, recipient registrations or profile amendments with valid data will fail. A KeyValuePair helper class is therefore necessary, via which the requisite information is defined.
<?php
class KeyValuePair {
public $key;
public $value;
function __construct($key, $value) {
$this->key = new SoapVar(
$key, XSD_STRING, "string", "http://www.w3.org/2001/XMLSchema");
$this->value = new SoapVar(
$value, XSD_STRING, "string", "http://www.w3.org/2001/XMLSchema");
}
}
// ***********************************************************************
// Step 1: Setup
// ***********************************************************************
// Include SOAP client class
include('WSSESoapClient.php');
$url = 'write your WSDL URL here';
$username = 'write your username here';
$password = 'write your password here';
// ***********************************************************************
// Step 2: Create SOAP client
// ***********************************************************************
$client = new WsseSoapClient($url, $username, $password);
// ***********************************************************************
// Step 3: Find the subscriber
// ***********************************************************************
$data = array(
"keyColumn" => "email",
"value" => "test@example.com");
$result = $client->FindSubscriber($data);
$subscriberId = $result->value;
if($subscriberId == 0) {
die("Subscriber not found!");
}
// ***********************************************************************
// Step 4: Update subscriber
// ***********************************************************************
$profileFields = array(
new KeyValuePair("firstname", "John"),
new KeyValuePair("lastname", "Doe")
);
$data = array(
"customerID" => $subscriberId,
"parameters" => $profileFields
);
$result = $client->UpdateSubscriber($data);
echo "Updated subscriber\n";
?>
Explanations
Step 1 comprises merely loading the class of the SOAP client and initialising some variables, which will be used in the later course of the program.
Step 2 shows the minimum constructor call for the SOAP client with username, password and URL of the WSDL document. Once initialised, the SOAP client can be used again for as many web service requests as desired.
To amend a recipient's profile data, the latter's ID is required. This is obtained in step 3 via the e-mail address. The ID sent back by the FindSubscriber web service is also checked here, since the e-mail address may not be known.
Step 4 updates the profile fields given for the recipient through request of UpdateSubscriber. The profile fields to be amended are set out in a list ($profileFields) as item of class KeyValuePair category.