Brightdoor
Call Us 1-800-894-5982
HOME | BLOG | PRESS ROOM | CONTACT US
BrightDoor in Focus
 
You can access the BrightDoor BrightBase Web Service API from any programming language which supports the HTTP protocol. The more sophisticated languages allow object-based control while others may require that you handles things as Hashmaps. Regardless, you can probably find a Web Service or SOAP library for just about every programming language out there. This page will show a brief example in C#, Java, ActionScript, PHP5, and Perl.

C# Example

  • Add a 'Web Reference' to you project (in Visual Studio right-click on your project and select 'Add Web Reference'
  • In the URL, enter the endpoint provided by your Account manager (e.g. https://--YOUR--DEPLOYMENT--)
  • One service should be found: WS. For the "Web Reference Name" use "BdWsApi" and cliick "Add Reference"
  • In your application you can now access the 'BdWsApi' object
class Program
{
   static void Main(string[] args)
   {
      BdWsApi.BdWsApi proxy = new BdWsApi.BdWsApi();
      proxy.PreAuthenticate = true;
      proxy.Credentials = new NetworkCredential(
           "--YOUR WEBSERVICE USERNAME--", "--YOUR WEBSERVICE PASSWORD--");

      Console.WriteLine("proxy.getSystemTime()=" + proxy.GetSystemTime());
			
      BdWsApi.DeviceTo device = (BdWsApi.DeviceTo)proxy.FindById(BdWsApi.EntityTypes.Device, 10);
      Console.WriteLine(device.Description);
			
      double odVersion = proxy.GetVersion();
      Console.WriteLine("odVersion=" + odVersion);
			
      BdWsApi.BaseTransportObject[] devices = proxy.FindObjects(0, 10,
                "from Device d where d.DeviceType.BdCode = 'BRIGHTLEAD' order by d.Id");
      for (int x = 0; x < devices.Length; x++)
      {
         Console.WriteLine(((BdWsApi.DeviceTo)devices[x]).CreateDate);
      }
   }
}

Java Example

The code below uses the Axis Web Service library (http://ws.apache.org/axis/). A build.xml file to generate the proxy objects and transfer objects would look like: 
<project>
   <path id="axis.classpath">
      <fileset dir="${axis.lib.dir}">
         <include name="*.jar" />
      </fileset>
   </path>

   <taskdef resource="axis-tasks.properties" classpathref="axis.classpath" />

   <target name="wsdl">
      <axis-wsdl2java username="--YOUR WEBSERVICE USERNAME--"
                      password="--YOUR WEBSERVICE PASSWORD--"
                      output="src" testcase="false" verbose="true" 
                      url="https://--YOUR--DEPLOYMENT--?WSDL"/>
   </target>
</project>
Once you have created the Java stub classes, you can access the Web Methods like: 
package com.brightdoor.ws.client;

import org.apache.axis.client.Call;
import org.apache.axis.client.Stub;

import com.brightdoor.ws.BaseTransportObject;
import com.brightdoor.ws.BdWsApi;
import com.brightdoor.ws.BdWsApiLocator;
import com.brightdoor.ws.BdWsApiSoap;
import com.brightdoor.ws.DeviceTo;
import com.brightdoor.ws.EntityTypes;

public class BdWsApiTestClient
{
   public static void main(String[] args)
   {
      new BdWsApiTestClient();
   }
	
   public BdWsApiTestClient()
   {
      try
      {
         BdWsApi locator = new BdWsApiLocator();
         BdWsApiSoap proxy = locator.getBdWsApiSoap();
         ((Stub)proxy)._setProperty(Call.USERNAME_PROPERTY, "--YOUR WEBSERVICE USERNAME--");
         ((Stub)proxy)._setProperty(Call.PASSWORD_PROPERTY, "--YOUR WEBSERVICE PASSWORD--");
         System.out.println("proxy.getSystemTime()=" + proxy.getSystemTime().getTime());

         DeviceTo device = (DeviceTo)proxy.findById(EntityTypes.Device, 10);
         System.out.println(device.getDescription());
			
         double odVersion = proxy.getVersion();
         System.out.println("odVersion=" + odVersion);
			
         BaseTransportObject[] devices = proxy.findObjects(0, 10,
                   "from Device d where d.DeviceType.BdCode = 'BRIGHTLEAD' order by d.Id");
         for (int x = 0; x < devices.length; x++)
         {
            System.out.println(((DeviceTo)devices[x]).getCreateDate().getTime());
         }
      }
      catch (Exception e)
      {
         e.printStackTrace(System.err);
      }
   }
}

ActionScript

According to the Adobe documentation, ActionScript (or perhaps it is the Flash player) does not always allow the setting of the "Authorization" header (see http://www.adobe.com/go/kb403030). This is required to connect to the BrightBase Web Services API. To help get around this limitation, you may set the "BB-Authorization" header instead with the exact same information.

Since ActionScript (2 or 3) is somewhat limited, the example below illustrates how to send a raw SOAP envelope to the BrightBase Web Service. There are several libraries you can use which takes a WSDL and stubs out proxy methods, even in ActionScript but none are 100% reliable and few handle security well. Using the example below, you will need to BASE64 encode your username and password in a form of “username:password” adhering to the HTTP standard for BASIC authentication. (TIP: If you don’t have a program to BASE64 something, use Firebug in Firefox to inspect the headers sent and copy-and-paste the “Authentication” header value.)

This example shows creating a contact. To get the full XML SOAP request for this or any of the methods, please go to your https://--YOUR--DEPLOYMENT-- page and click on the method you wish to run. This will show you the full XML document spec for each Web Service method. 

			
   var newContactXml:String = 
      "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n" +
      "<soap:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" " +
      "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" " +
      "xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">\n" +
      "  <soap:Body>\n" +
      "    <UpdateSimpleContact xmlns=\"http://ws.brightdoor.com/\">\n" +
      "      <contact>\n" +
      "        <Honorific/>\n" +
      "        <FirstName>First_TestFromAS</FirstName>\n" +
      "        <MiddleName/>\n" +
      "        <LastName>Last_TestFromAS</LastName>\n" +
      "        <Suffix/>\n" +
      "        <Salutation/>\n" +
      "        <SpouseFirstName/>\n" +
      "        <SpouseMiddleName/>\n" +
      "        <SpouseLastName/>\n" +
      "        <CompanyName/>\n" +
      "        <PreferredCommunicationMethod/>\n" +
      "        <DoNotCall>false</DoNotCall>\n" +
      "        <CreateDate>2008-03-01T18:00:00Z</CreateDate>\n" +
      "        <UpdateDate>2008-03-01T18:00:00Z</UpdateDate>\n" +
      "        <ForeignSysId/>\n" +
      "        <PhysicalAddresseses>\n" +
      "           <SimplePhysicalAddress>\n" +
      "               <Label>Work</Label>\n" +
      "               <Address1>6501 Weston Parkway</Address1>\n" +
      "               <Address2>Suite 320</Address2>\n" +
      "               <City>Cary</City>\n" +
      "               <State>NC</State>\n" +
      "               <Zip>27513</Zip>\n" +
      "               <Country>US</Country>\n" +
      "               <IsShipping>true</IsShipping>\n" +
      "               <IsPreferred>true</IsPreferred>\n" +
      "               <UpdateDate>2008-03-01T18:00:00Z</UpdateDate>\n" +
      "           </SimplePhysicalAddress>\n" +
      "        </PhysicalAddresseses>\n" +
      "        <ContactType>Prospect</ContactType>\n" +
      "        <ContactStatus>A Prospect</ContactStatus>\n" +
      "        <WorkPhone>9195551234</WorkPhone>\n" +
      "        <WorkPhoneExt>123</WorkPhoneExt>\n" +
      "        <HomePhone>9196661234</HomePhone>\n" +
      "        <FaxPhone>91977712345</FaxPhone>\n" +
      "        <MobilePhone>9198881234</MobilePhone>\n" +
      "        <PersonalEmail>noone@nowhere.com</PersonalEmail>\n" +
      "        <WorkEmail/>\n" +
      "        <PrimaryPhone>9195551234</PrimaryPhone>\n" +
      "        <PrimaryEmail>noone@nowhere.com</PrimaryEmail>\n" +
      "      </contact>\n" +
      "    </UpdateSimpleContact>\n" +
      "  </soap:Body>\n" +
      "</soap:Envelope>"

   var requestXML:XML = new XML(newContactXml);
   var responseXML:XML = new XML();

   requestXML.addRequestHeader("SOAPAction",
                                 "http://ws.brightdoor.com/UpdateSimpleContact");
   requestXML.addRequestHeader("Content-Type",
                                 "text/xml; charset=utf-8");
   requestXML.addRequestHeader("BB-Authorization", "Basic --BASE 64 username:password--");

   responseXML.onHTTPStatus = function(httpStatus:Number)
      {
         trace('httpStatus=' + httpStatus);
      }
					
   responseXML.onLoad = function(success:Boolean)
      {
         trace(responseXML.toString());
      }

   requestXML.sendAndLoad("https://--YOUR--DEPLOYMENT--", responseXML, "POST");

PHP5

Be certain you have uncommented out the php_soap.dll (Windows) or php_soap.so (Unix/Linux) and php_openssl.dll (Windows) or php_openssl.so (Unix/Linux) extensions in your php.ini file.

The sample code below has several lines commented out that may help your debugging if you uncomment them. In addition, you can set the 'trace' value to 1 instead of 0.

There are two code snippets below. The first shows the use of the "Simple" objects which require a little less code. The second shows an example of using a "full" object and a small example of the BrightDoor Query Language (BDQL).

For the Web Service Methods that return or accept an object, you will need to setup 'classmap' (usage included in the example below). There are third-parties PHP5 libraries (such as http://www.urdalen.no/wsdl2php/) which auto stub out the classes (much like Axis in the Java language), but BrightDoor doesn't officially support them because they do not take authentication into account. If you find one that supports authentication, please let us know at BrightDoor API Support! We'd love to share that with others.

When you create your own stub classes, the only properties that must be declared are the non-string properties. For the 'Id' property, it should be init'ed to "-1" so the API knows that it is a new entry. 

<?php
# Auto-map types to classes you define yourself
$classmap = array();
$tmpClient = new SoapClient("https://--YOUR--DEPLOYMENT--?WSDL",
                             array(login" => "--YOUR WEBSERVICE USERNAME--",
                                   "password" => "--YOUR WEBSERVICE PASSWORD--"));
 
foreach($tmpClient->__getTypes() as $type)
{
   $array = split(" ", $type);
   if($array[0] == "struct" && class_exists($array[1]))
   {
      $classmap[$array[1]] = $array[1];
   }
}
unset($tmpClient);

# Now create the proxy client
$client = new SoapClient("https://--YOUR--DEPLOYMENT--?WSDL",
                         array("login" => "--YOUR WEBSERVICE USERNAME--",
                               "password" => "--YOUR WEBSERVICE PASSWORD--",
                               "classmap" => $classmap,
                               "trace" => 0));

#var_dump($client->__getFunctions());
#var_dump($client->__getTypes());	

try
{
   $return = $client->getVersion();
   print "API Version: " . $return->GetVersionResult . "\n";
}
catch (SoapFault $exception)
{
   echo $exception;
}

$c = new SimpleContact();
$homeAddress = new SimplePhysicalAddress();
$workAddress = new SimplePhysicalAddress();

$homeAddress->Label = "Home";
$homeAddress->Address1 = "1234 Main Street";
$homeAddress->City = "Raleigh";
$homeAddress->State = "NC";
$homeAddress->Zip = "27601";
$homeAddress->UpdateDate = time();

$workAddress->Label = "Work";
$workAddress->Address1 = "1234 Work Street";
$workAddress->Address2 = "Suite 100";
$workAddress->City = "Cary";
$workAddress->State = "NC";
$workAddress->Zip = "27501";
$workAddress->UpdateDate = time();

$c->FirstName = "ContactFirstName";
$c->LastName = "ContactLastName";
$c->CreateDate = time();
$c->UpdateDate = time();
$c->PhysicalAddresseses = array(2);
$c->PhysicalAddresseses[0] = $homeAddress;
$c->PhysicalAddresseses[1] = $workAddress;

try
{
   $pk = $client->UpdateSimpleContact(array("contact" => $c));
   print "Contact Created: " . $pk->UpdateSimpleContactResult . "\n";
}
catch (SoapFault $exception)
{
   echo $exception;
   $count = sizeof($exception->detail->errors->error);
   for ($x = 0; $x < $count; $x++)
   {
      echo $exception->detail->errors->error[$x] . "\n";
   }
}

#print "Request :\n".$client->__getLastRequest() ."\n";
#print "Response:\n".$client->__getLastResponse()."\n";

class BaseTransferObject
{
   public $Id = -1;
   public $IgnoreNullValues = false;
}

class SimpleContact extends BaseTransferObject
{
   public $Honorific;
   public $FirstName;
   public $MiddleName;
   public $LastName;
   public $Suffix;
   public $Salutation;
   public $SpouseFirstName;
   public $SpouseMiddleName;
   public $SpouseLastName;
   public $CompanyName;
   public $PreferredCommunicationMethod;
   public $DoNotCall = false;
   public $CreateDate;
   public $UpdateDate;
   public $ForeignSysId;
   public $PhysicalAddresseses;
   public $ContactType;
   public $ContactStatus;
   public $WorkPhone;
   public $WorkPhoneExt;
   public $HomePhone;
   public $FaxPhone;
   public $MobilePhone;
   public $PersonalEmail;
   public $WorkEmail;
   public $PrimaryPhone;
   public $PrimaryEmail;
}

class SimplePhysicalAddress extends BaseTransferObject
{
   public $Label;
   public $Address1;
   public $Address2;
   public $City;
   public $State;
   public $Zip;
   public $Country;
   public $IsShipping = false;
   public $IsPreferred = false;
   public $UpdateDate;
}
?>

PHP5 Example using a full object. 
<?php
# Auto-map types to classes you define yourself
$classmap = array();
$tmpClient = new SoapClient("https://--YOUR--DEPLOYMENT--?WSDL",
                             array(login" => "--YOUR WEBSERVICE USERNAME--",
                                   "password" => "--YOUR WEBSERVICE PASSWORD--"));
 
foreach($tmpClient->__getTypes() as $type)
{
   $array = split(" ", $type);
   if($array[0] == "struct" && class_exists($array[1]))
   {
      $classmap[$array[1]] = $array[1];
   }
}
unset($tmpClient);

# Now create the proxy client
$client = new SoapClient("https://--YOUR--DEPLOYMENT--?WSDL",
                         array("login" => "--YOUR WEBSERVICE USERNAME--",
                               "password" => "--YOUR WEBSERVICE PASSWORD--",
                               "classmap" => $classmap,
                               "trace" => 0));

#var_dump($client->__getFunctions());
#var_dump($client->__getTypes());	

$c = new ContactTo();

$c->FirstName = "ContactFirstName";
$c->LastName = "ContactLastName";
$c->CreateDate = time();
$c->UpdateDate = time();
$c->Interests = array(1);

$obj = new SoapVar($c, SOAP_ENC_OBJECT, "ContactTo",  "http://ws.brightdoor.com/");

try
{
   $ch = $client->FindTopObject(array("bdql" => "from Interest where Name='--Interest Name--'"));
   $c->Interests[0] = $ch->FindTopObjectResult;

   $pk = $client->UpdateObject(array("obj" => $obj));
   print "Contact Created: " . $pk->UpdateObjectResult . "\n";
}
catch (SoapFault $exception)
{
   echo $exception;
   $count = sizeof($exception->detail->errors->error);
   for ($x = 0; $x < $count; $x++)
   {
      echo $exception->detail->errors->error[$x] . "\n";
   }
}

#print "Request :\n".$client->__getLastRequest() ."\n";
#print "Response:\n".$client->__getLastResponse()."\n";

class BaseTransferObject
{
   public $Id = -1;
   public $IgnoreNullValues = false;
}

class ContactTo extends BaseTransferObject
{
  public $Username; // string
  public $Password; // string
  public $Honorific; // string
  public $FirstName; // string
  public $MiddleName; // string
  public $LastName; // string
  public $Suffix; // string
  public $Salutation; // string
  public $DisplayName; // string
  public $SpouseFirstName; // string
  public $SpouseMiddleName; // string
  public $SpouseLastName; // string
  public $CompanyName; // string
  public $BrightSync = false; // boolean
  public $Signature; // string
  public $Registered = false; // boolean
  public $AllowPrivatePortal = false; // boolean
  public $DoNotCall = false; // boolean
  public $CreateDate; // dateTime
  public $UpdateDate; // dateTime
  public $Charter = false; // boolean
  public $PreferredCommunicationMethod; // string
  public $Active = true; // boolean
  public $ForeignSysId; // string
  public $ContactTypeId = -1; // int
  public $ContactStatusId = -1; // int
  public $ReferralSourceId = -1; // int
  public $PhoneNumbersList; // ArrayOfContactPhoneNumberTo
  public $PhysicalAddressesList; // ArrayOfContactPhysicalAddressTo
  public $EmailAddressesList; // ArrayOfContactEmailAddressTo
  public $Attributes; // ArrayOfContactAttributeTo
  public $Interests; // ArrayOfInterestTo
}
?>

Perl

It is recommended that you use the SOAP::Lite perl package (http://www.soaplite.com/). 

#use SOAP::Lite +trace => 'debug';
use SOAP::Lite;

my $service = new SOAP::Lite
		-> uri('http://ws.brightdoor.com/')
		-> on_action( sub { join '/', 'http://ws.brightdoor.com', $_[1] } )
		-> proxy('https://--YOUR--DEPLOYMENT--?WSDL');

print "Server Time: " . $service->GetSystemTime()->result() . "\n";
print "OD Version: " . $service->GetVersion()->result() . "\n";

# Get some devices
my $method = SOAP::Data
      -> name('FindObjects')
      -> attr({xmlns => 'http://ws.brightdoor.com/'});
my @params = (
   SOAP::Data
      -> name('start')
      -> type('xsd:int')
      -> value(0),
   SOAP::Data
      -> name('maxResults')
      -> type('xsd:int')
      -> value(10),
   SOAP::Data
      ->name('bdql')
      -> type('xsd:string')
      -> value("from Device d where d.DeviceType.BdCode = 'BRIGHTLEAD' order by d.Id")
      );
my @result = $service
                 -> call($method => @params)
                 -> valueof("//FindObjectsResult/BaseTransportObject");

foreach $item (@result)
{
   foreach $key (keys %$item)
   {
      print $key . "=" . $item->{$key} . "\n";
   }
   print "----\n";
}

sub SOAP::Transport::HTTP::Client::get_basic_credentials
{ 
   return '--YOUR WEBSERVICE USERNAME--' => '--YOUR WEBSERVICE PASSWORD--';
}


Real Estate Sales & Marketing for the New World.    1-800-894-5982


© 2005-2008 BrightDoor Systems, Inc. All Rights Reserved.