Creating Nexxus Marketing Contacts with PHP

Published on Tuesday, May 5, 2015

By Chris Rees

A common use case for the Nexxus Marketing SOAP API is web forms for capturing contact information from website visitors. This requires the creation of Contact resources using the Nexxus Marketing SOAP API Create operation. The Nexxus Marketing SDK provides samples in C# suitable for ASP/MVC web applications. Beyond Microsoft languages though, PHP is a very popular server-side language. With that in mind, here’s a walkthrough showing how PHP can be used to create contacts using the Nexxus Marketing SOAP API 2.0.

Creating Contacts

The pattern for creating a Contact with the Nexxus Marketing SOAP API is:

  1. Create a SoapClient object.
  2. Build a parameters object.
  3. Call the Nexxus Marketing SOAP Create operation.
  4. Parse the results.

Creating a SoapClient Object

The PHP SoapClient class is used to call SOAP operations exposed by a web service. It can read the WSDL exposed by Nexxus Marketing to create a client representation of the Nexxus Marketing SOAP API. The following snippet shows an instance of SoapClient being created with a username, password and WSDL location url read from a configuration file. The trace parameter enables debugging information (discussed later).

$details=parse_ini_file("config.ini");

$options = array(
        'login' => $details['user'],
        'password' => $details['password'],
        'trace' => true
);

try {
    $client = new SoapClient($details['url'],$options);
    echo "<p>Created SoapClient object.</p>";
}
catch (Exception $e) {
    echo "<p>Failed to create SoapClient object - $e.Message.</p>";
    return;
}

The format for the configuration file (“config.ini”) is as follows:

url = "<NexxusMarketingURL>/api/Napier.asmx?WSDL"
user = "<Username>"
password = "<Password>"

You’ll need to create this file, provide the appropriate information and place the file somewhere accessible to the PHP file.

Building the Parameters Object

Once created using the Nexxus Marketing WSDL, the SoapClient object is used to call the Nexxus Marketing SOAP API Create operation. To do that, a parameters object containing the Contact resources has to be created. Each Resource describes a single contact using multiple Field objects. The SOAP envelope for creating two contacts looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.appatureinc.com/api/napier">
    <SOAP-ENV:Body>
        <ns1:Create>
            <ns1:TypeId>Contact</ns1:TypeId>
            <ns1:Resources>
                <ns1:Resource>
                    <ns1:Field Id="FirstName">Chris</ns1:Field>
                    <ns1:Field Id="LastName">Jones</ns1:Field>
                    <ns1:Field Id="Email">cj@fake.com</ns1:Field>
                    <ns1:Field Id="ContactType">Contact</ns1:Field>
                </ns1:Resource>
                <ns1:Resource>
                    <ns1:Field Id="FirstName">John</ns1:Field>
                    <ns1:Field Id="LastName">Smith</ns1:Field>
                    <ns1:Field Id="Email">JS@fake.com</ns1:Field>
                    <ns1:Field Id="ContactType">Contact</ns1:Field>
                </ns1:Resource>
            </ns1:Resources>
        </ns1:Create>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The following snippet builds the resources set of two resource objects needed for two contacts:

//Build contact field objects.

$firstNameObject= (object)array("_" => "Chris", "Id"=>"FirstName");
$lastNameObject = (object)array("_" => "Jones", "Id"=>"LastName");
$emailObject = (object)array("_" => "cj@fake.com", "Id"=>"Email");
$contactTypeObject = (object)array("_" => "Contact", "Id"=>"ContactType");

// Fields structure
$fields = array($firstNameObject,
        $lastNameObject,
        $emailObject,
        $contactTypeObject);

//Build 2nd contact
$firstNameObject2= (object)array("_" => "John", "Id"=>"FirstName");
$lastNameObject2 = (object)array("_" => "Smith", "Id"=>"LastName");
$emailObject2 = (object)array("_" => "JS@fake.com", "Id"=>"Email");
$contactTypeObject2 = (object)array("_" => "Contact", "Id"=>"ContactType");

// Fields structure
$fields2 = array($firstNameObject2,
        $lastNameObject2,
        $emailObject2,
        $contactTypeObject2
);

//Build resources structure
$resource = array('Field'=>$fields);
$resource2 = array('Field'=>$fields2);
$resources = array('Resource' => array((object)$resource, (object)$resource2));

$parameters = array("TypeId"=>"Contact",
        "Resources" => $resources);

Create the Contact

To create the contacts, you’ll call the Nexxus Marketing SOAP API Create operation using the previously created SoapClient object.

//Make Nexxus Marketing SOAP Create contact call.
try {
    $result = $client->Create($parameters);
    //$text=htmlentities($client->__getLastRequest());
    //echo "<pre>$text</pre>";
    echo "<p>Called Create.</p>";
}
catch (Exception $e) {
    echo "<p>Call to Create failed - $e.Message</p>";
    return;
}
//$resultString = print_r($result,true);
//echo"<p><pre>$resultString</pre></p>";

Debugging Tips

A useful debugging option is the SoapClient __getLastRequest method which can be used to display the XML passed from the Create call to the SOAP service. Use it to check the formatting of the resources against the Nexxus Marketing SDK documentation. To use __getLastRequest set the SoapClient trace parameter to true and call __getLastRequest after you call Create. print_r is another debugging option useful for displaying the results of a Create call. It displays every field for every resource created, so expect a long list.

Parsing the Results

The return from Create includes information about the success of the operation, a set of created resources and error information for each resource that failed to be created. The information Create returns is formatted similar to the following example. In this case, one Contact has been created whilst the second Contact has an error. Note. Most of the resource fields have been removed for brevity.

stdClass Object
(
[CreateResult] => stdClass Object
    (
        [Resources] => stdClass Object
            (
                [ResourceStatus] => Array
                    (
                        [0] => stdClass Object
                            (
                                [Resource] => stdClass Object
                                    (
                                        [Field] => Array
                                            (
                                                [0] => stdClass Object
                                                    (
                                                        [_] => 1263249
                                                        [Id] => Id
                                                    )

                                                [1] => stdClass Object
                                                    (
                                                        [_] =>
                                                        [Id] => ExternalContactId
                                                    )

                                                [2] => stdClass Object
                                                    (
                                                        [_] => Chris
                                                        [Id] => FirstName
                                                    )

                                                [3] => stdClass Object
                                                    (
                                                        [_] =>
                                                        [Id] => MiddleName
                                                    )

                                                [4] => stdClass Object
                                                    (
                                                        [_] => Jones
                                                        [Id] => LastName
                                                    )

                                            )

                                    )

                                [OperationSucceeded] => 1
                            )

                        [1] => stdClass Object
                            (
                                [ErrorMessage] => No Field Id is specified for use with Type Id 'Contact'.
                                [OperationSucceeded] =>
                                [ErrorString] => INVALID_FIELD_ID
                            )

                    )

            )

        [BatchCompleted] => 1
        [RequestId] => fe356807-4f15-45ad-ab2c-7fe8914c65c9
    )

)

The following snippet shows tests for operation success and displays the identifiers for newly created contacts. These identifiers can be used with the other Nexxus Marketing SOAP API such as the Get operation.

//Display id for each contact created.
if ($result->CreateResult->BatchCompleted){

    foreach ($result->CreateResult->Resources->ResourceStatus as $resultResource)
    {
        if ($resultResource->OperationSucceeded == true){
            $fieldarray=(array)$resultResource->Resource->Field;
            $key=array_search("Id", $fieldarray);
            $id=$fieldarray[$key]->{"_"};
            echo "<p>Contact created with ID $id created.</p>";

        }
        else{
            $errorMessage=$resultResource->ErrorMessage;
            echo "<p>Couldn't create contact (Row level error) - $errorMessage</p>";

        }
    }
}
else {
    $errorMessage = $result->CreateResult->ErrorMessage;
    echo "<p>Couldn't create contact (Top level error) - $errorMessage</p>";
    return;
}

That’s it. A lot more information about the Nexxus Marketing API is in the SDK documentation, but for creating Contacts with PHP you should be good to go with these snippets. Next time we’ll take a look at the other Nexxus Marketing SOAP operations such as Get, Describe, Show and Delete. Down the road we’ll also take a look at calling the Bulk REST API with PHP.