Reading Nexxus Marketing entities with PHP and SOAP

Published on Wednesday, July 1, 2015

By Chris Rees

Welcome back, my previous article looked at creating Nexxus Marketing contacts with PHP and SOAP. How do you read those contacts, and Nexxus Marketing resources/entities in general, at a later time? Well, this is how its done... ##It's all about GET The Nexxus Marketing SOAP provides a Get operation for retrieving one or more known resources. In this case, Contact resources. To retrieve a Contact using Get and PHP, you'll need to provide the type of entity you want to retrieve (Contact) and a list of resource identifiers for each contact you want returned. The resource identifier is created when the Contact resource is created within the Nexxus Marketing application or by using the Nexxus Marketing API. Within the Nexus Marketing application, the resource identifier can be viewed on the contact page. For SOAP operations, its part of the return structure from a call to Create. If you don't know a contact's resource identifier you can use the Bulk Find REST API to query resource fields based on other criteria such as First Name, Last Name and Email. The SDK documentation provides coverage for the public fields of each API accessible resource. As discussed in Creating Nexxus Marketing Contacts with PHP, the SoapClient object can be used to call Nexxus Marketing SOAP operations. ###Creating a SoapClient object The following code shows how to create a SoapClient object:

$options = array(
		'login' => "Nexxus User Name with API Privileges",
		'password' => "Nexxus User Password"
		//	'proxy_host' =>'localhost',
		//	'proxy_port' => '3128'
);

$url="https://api.appatureinc.com/api/Napier.asmx?WSDL";

try {

	$client = new SoapClient($url,$options);
}
catch (Exception $e) {
	http_response_code(500);
	error_log("Couldn't create SOAP Object - $e.Message");
	echo "Couldn't create SOAP object";
	exit;
}

Depending on your situation, you may need to provide proxy host and port information. This is commented out in this snippet. ###Getting the Contact Building the parameter for Get is straightforward; its an object containing the type identifier and a list of resource identifiers to retrieve. The SOAP body will look like this for a call to retrieve two Contact resources with the identifiers 5 and 10:

<soap:Body>
<Get xmlns="http://www.appatureinc.com/api/napier">
  <TypeId>Contact</TypeId>
	<Ids>
			<Id>5</Id>
			<Id>10</Id>
	</Ids>
</Get>

</soap:Body> </soap:Envelope> In PHP this is represented as follows:

$idsArray = array("5","10");
$parameters = array("TypeId"=>"Contact",
		"Ids" => array('Id'=>$idsArray));

A call to Get returns a result object containing the requested resource object(s) and error information for any resources that couldn't be retrieved. If the operation completely fails, For example if the server was contacted but a Nexxus Marketing API error occurred (for example, if an unknown resource type is requested) then Nexxus Marketing error information is returned. If a general operation failure occurs, such as a failure to contact the server, PHP raises an exception.

try{

	$idsArray = array("5","10");

	$parameters = array("TypeId"=>"Contact",
			"Ids" => array('Id'=>$idsArray)
			);

	$result=$client->Get($parameters);
}
catch(Exception $e){
	echo "Error - $e";
	exit;
}
$r=print_r($result,true);
echo "<pre>$r</pre>";

If the call is successful, $r in this snippet should give you a representation of the returned resources or error information. Parsing the result takes a little more effort... ###Parsing the result object As described in [/posts/create-contacts-with-php/](Creating Nexxus Marketing Contacts with PHP) The result object contains a complete breakdown of the operation result. For a Get operation, a GetResult object is returned as opposed to CreateResult in a Create operation. That difference aside, parsing a Get operation result is the same as parsing the result of a Create operation; successfully retrieved resources are returned in an array of StdClass objects with each StdClass object containing a contact field. The following snippet takes the $result from Get and displays the contact fields and their values in a table:

	if ($result->GetResult->BatchCompleted){

	foreach ($result->GetResult->Resources->ResourceStatus as $resultResource)
	{
		echo "<h2>Contact</h2>";
		if ($resultResource->OperationSucceeded == true){
			$fieldArray=(array)$resultResource->Resource->Field;
			echo "<table>";
			echo "<tr><th align='left'>Field</th><th align='left'>Value</th></tr>";

			foreach ($fieldArray as $field)
			{
				echo "<tr>";
				echo "<td>{$field->Id} </td><td>{$field->_}</td>";
				echo "</tr>";
			}
			echo "</table>";
		}
		else{
			$errorMessage=$resultResource->ErrorMessage;
			echo "<p>Couldn't read contact  - $errorMessage</p>";

		}
	}
}
else {
	$errorMessage = $result->CreateResult->ErrorMessage;
	echo "<p>Couldn't read contact  - $errorMessage</p>";
	return;
}

And that's pretty much it. The same approach will work for other Nexxus Marketing resources exposed by the API. For example, you could use Get to retrieve campaign information via the Campaign resource or view opt in preferences for a contact using OptIn resources. That scenario will be covered as a solution in an upcoming release of the Nexxus Marketing API documentation. Earlier I mentioned using Bulk Find to get resources identifiers. I'll discuss that, and REST API in general, next time...