That got me to thinking… what status codes does ColdFusion throw an error for when throwonerror is set to yes? Here’s the list for every HTTP status code:

CFHTTP with throwonerror=”yes”

I also ran it with throwonerror=”no”, which has almost the results you would expect with the exception of code 411:

CFHTTP with throwonerror=”no”

Notice Status Code 411 doesn’t return a numerical status code but rather a string “Connection Failure. Status code unavailable.” The FileContent is set to “Connection Failure” while all other status codes are left blank (assuming that the request doesn’t return any data, as my test script does). Good to know.

Problematic SSL Certificates

For processing credit cards and payment processing transactions in general, the most insidious error I have run into is the “I/O Exception: peer not authenticated” error. This basically means ColdFusion is unable to read and authenticate the SSL certificate and initiate a secure connection. Generally this is either a self-signed certificate or, these days, a wildcard SSL certificate. Interestingly, ColdFusion handles these scenarios a little bit differently depending on how throwonerror is set:

In summary, using throwonerror=no looks reasonably safe but you still must account for the catch-all COM.Allaire.ColdFusion.HTTPFailure. My battle-tested code (which has processed more than $15MM) suggests you also need to check for coldfusion.runtime.RequestTimedOutException which is a different kind of exception when CFHTTP times out or the page times out.

So seems to be the mental state of David Epler as he has been driven to build the “Unofficial Updater 2“. It is an Ant script on steroids bundled in a JAR that knows how to go out and fetch all of the updates from Adobe.com and apply them to your CF8 or CF9 server installation.

I’m not going to belabor the awesomness; here’s how to get your server up to date in about 5 minutes:

1. Start by verifying your current security issues, use Pete Freitag’s HackMyCF.com for a baseline
2. Backup your /opt/jrun directory (just be safe): tar -cf /opt/jrun4
3. Download the Unofficial Updater from http://uu2.riaforge.org/
4. Run it: java -jar Unofficial-Updater2.jar text
5. Tell it where stuff lives in your installation (it knows how to handle Standalone, Jrun Multi-server and EAR/WAR installs)
6. Wait about 4 minutes for it to finish grabbing everything and install…
7. Re-run HackMyCF.com and BOOM! Rest easy, friend.
8. Proceed to have David Epler’s baby

Please Adobe, please send David a big check so you can take his IP and use it for your next update, mmmm kay?

Strip whitespace from end of lines

Extra white space at the end of a line probably won’t cause any problems but it’s unnecessary and just taking up space. You can strip it with this.

Find: ([\S])[ |\t]+$
Replace: $1

A variant of this one is to find “^[ |\t]+$” which will find all lines that only contain spaces and tabs.

Find unescaped ampersands

Most ampersand characters need to be escaped in web apps – this will track all ampersands not followed by the most commonly escaped variants like   – add your own as needed.

Find: [^ ]&[^ |(amp;)|(nbsp;)|(gt;)|(lt;)]

 

Convert isDefined to structKeyExists

StructKeyExists is the preferred method of checking if a variable is defined but updating all of those isDefined()s by hand is a drag. Convert your entire code base with this search and replace:

Find: [iI]sDefined\("(FORM|URL).([A-Za-z0-9]+)"\)
Replace: structKeyExists($1, "$2")

^((?!output)[^>\n\r])*<cffunction(((?!output)[^>])*)>

This regular expression should handle cases where cffunction start tag is on one line and end tag is on another, where start and end tags are on one line and Ben Nadel-style “attribute-per-line” tags broken up by newlines. Click the “replace” button and when prompted for the replace pattern, use:

$1<cffunction$2 output="false">

BEFORE you run this search and replace, save and commit your code so anything that goes sideways can be easily reverted.

You can test this in a single file using the CTRL+F search and replace dialog box first as demonstrated in the above screenshot (note, the screenshot does not have the right regex).

There are a huge number of functions in popular frameworks like Coldspring 1.2, Model-Glue 2 and Transfer ORM that are missing an output tag (and a smaller number of instances where output=”true”, which should also be corrected). If you instantiate these frameworks in persistent scopes (who doesn’t?), this is a fix you’ll want to apply.

This issue may also be fixed in CF 8.0.1 cumulative hot fix 4 but it was also supposed to be fixed in CHF3. In all cases, the update is easy and is one less thing to worry about.

I have no knowledge of whether or not this exists in CF9.

[1] – How cfcomponent output=true can affect memory consumption (MxUnit.org)
[2] – Fixing a mysterious memory leak on ColdFusion (Peter Farrell)

01/10 13:03:28 user MessageBrokerServlet: init
**** 90 seconds of "working" ****
01/10 13:05:13 user CFFormGateway: init

01/10 12:32:58 Information [scheduler-12] - Starting debugging...
01/10 12:32:58 Information [scheduler-12] - Starting sql...
****  almost 2 minutes here ****
01/10 12:34:46 Information [scheduler-12] - Pool Manager Started
01/10 12:34:46 Information [scheduler-12] - Starting mail... 

This simply would not do. Not only was it slow, it was unpredictable, sometimes taking 90-115 seconds and other times as long as 224 seconds. We generally restart our CF servers when we do deployments and the sluggish startup meant more queued requests and timeouts as we come back from an update. No bueno.

I turned to my friends on the CFGURU list hoping someone had the answer. The always helpful Dan Switzer pointed me to a cfaussie thread which was Ubuntu specific but had my same behavior:

With the startup you can see that cranking up the Message Broker Servlet (ie Livecycle/Blaze) is taking almost a minute, which I find is usually due to some network ports used by LCDS still being open from the last time ColdFusion was run.

The good news was that they were experiencing the exact same problem I was. The bad news is that I have nothing to do with Blaze or LiveCycle so I wasn’t sure this was related. We are also running RHEL/CentOS but the Ubuntu connection proved helpful later in my research.

Anytime I see hanging processes in ColdFusion, I generate a complete JVM stack trace. Unfortunately, I’m quite bad at reading them. I identified a BLOCKED process but Daryl Banttari took a look and set me straight:

This is the thread that's your root problem:

"scheduler-10" prio=10 tid=0x00002aaaac28c800 nid=0x5edd runnable [0x00000000441de000]
   java.lang.Thread.State: RUNNABLE
at java.io.FileInputStream.readBytes(Native Method)
at java.io.FileInputStream.read(FileInputStream.java:199)
at java.io.BufferedInputStream.read1(BufferedInputStream.java:256)
at java.io.BufferedInputStream.read(BufferedInputStream.java:317)
- locked <0x00002b4fc75a5018> (a java.io.BufferedInputStream)
at java.io.BufferedInputStream.fill(BufferedInputStream.java:218)
at java.io.BufferedInputStream.read1(BufferedInputStream.java:258)
at java.io.BufferedInputStream.read(BufferedInputStream.java:317)
- locked <0x00002b4fc75a4ce0> (a java.io.BufferedInputStream)
at sun.security.provider.SeedGenerator$URLSeedGenerator.getSeedByte(SeedGenerator.java:453)
at sun.security.provider.SeedGenerator.getSeedBytes(SeedGenerator.java:123)
at sun.security.provider.SeedGenerator.generateSeed(SeedGenerator.java:118)
at sun.security.provider.SecureRandom.engineGenerateSeed(SecureRandom.java:114)
at java.security.SecureRandom.generateSeed(SecureRandom.java:495)
at com.rsa.jsafe.provider.c7.engineGenerateSeed(Unknown Source)
at java.security.SecureRandom.generateSeed(SecureRandom.java:495)
at java.security.SecureRandom.getSeed(SecureRandom.java:482)
at com.rsa.jsafe.crypto.au.g(Unknown Source)
at com.rsa.jsafe.crypto.au.a(Unknown Source)
at com.rsa.jsafe.provider.JSA_FIPS186PRNGXChangeNoticeGeneral.engineNextBytes(Unknown Source)
at java.security.SecureRandom.nextBytes(SecureRandom.java:433)
- locked <0x00002b4fdca32370> (a java.security.SecureRandom)
at java.security.SecureRandom.next(SecureRandom.java:455)
at java.util.Random.nextInt(Random.java:253)
at flex.messaging.util.UUIDUtils.createUUID(UUIDUtils.java:110)
at flex.messaging.util.UUIDUtils.createUUID(UUIDUtils.java:97)
at flex.messaging.log.AbstractTarget.<init>(AbstractTarget.java:52)
at flex.messaging.log.LineFormattedTarget.<init>(LineFormattedTarget.java:79)
at flex.messaging.log.ConsoleTarget.<init>(ConsoleTarget.java:34)
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:39)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)
at java.lang.reflect.Constructor.newInstance(Constructor.java:513)
at java.lang.Class.newInstance0(Class.java:355)
at java.lang.Class.newInstance(Class.java:308)
at flex.messaging.config.MessagingConfiguration.createLogger(MessagingConfiguration.java:298)
at flex.messaging.MessageBrokerServlet.init(MessageBrokerServlet.java:114)
at coldfusion.flex.ColdFusionMessageBrokerServlet.init(ColdFusionMessageBrokerServlet.java:24)
at coldfusion.bootstrap.ClassloaderHelper.initServletClass(ClassloaderHelper.java:94)
at coldfusion.bootstrap.BootstrapServlet.init(BootstrapServlet.java:59)
at jrun.servlet.WebApplicationService.loadServlet(WebApplicationService.java:1213)
- locked <0x00002b4fdbc4e5c8> (a java.lang.Object)
at jrun.servlet.WebApplicationService.preloadServlets(WebApplicationService.java:793)
at jrun.servlet.WebApplicationService.postStart(WebApplicationService.java:295)
at jrun.ea.EnterpriseApplication.start(EnterpriseApplication.java:203)
at jrun.deployment.DeployerService.initModules(DeployerService.java:708)
at jrun.deployment.DeployerService.createWatchedDeployment(DeployerService.java:243)
at jrun.deployment.DeployerService.deploy(DeployerService.java:428)
- locked <0x00002b4ed0c3f140> (a java.util.HashMap)
at jrun.deployment.DeployerService.checkWatchedDirectories(DeployerService.java:179)
at jrun.deployment.DeployerService.run(DeployerService.java:889)
- locked <0x00002b4ed0c3f140> (a java.util.HashMap)
at jrunx.scheduler.SchedulerService.invokeRunnable(SchedulerService.java:230)
at jrunx.scheduler.ThreadPool$DownstreamMetrics.invokeRunnable(ThreadPool.java:320)
at jrunx.scheduler.ThreadPool$ThreadThrottle.invokeRunnable(ThreadPool.java:428)
at jrunx.scheduler.ThreadPool$UpstreamMetrics.invokeRunnable(ThreadPool.java:266)
at jrunx.scheduler.WorkerThread.run(WorkerThread.java:66)

Looks like it's stuck trying to read from /dev/random while trying to create a UUID?

The key was that Java was waiting on input to the secure number generator code. Thanks to Daryl’s stack trace reading kung fu, I had something to Google. On Linux, /dev/random is a “blocking” number generator meaning if it doesn’t have enough random data to provide, it will simply wait until it does. Here’s some background on /dev/random. Keyboard and mouse input as well as disk activity can generate the randomness, or entropy, needed but perhaps not fast enough for particular applications. A lack of random data would force the JVM and ColdFusion to wait, for eternity if necessary, until chaos caught up with /etc/init.d/coldfusion8multi.

It turns out a lot of applications experience this problem: any that use random number generators. I found frustrated users of Apache, SSL, Livecycle/Blaze DS and a myriad of other applications as my search terms refined.

Verify the culprit

Before you try the changes below, verify that this is indeed your problem. It’s easy! First, start by checking how much entropy you have:

cat /proc/sys/kernel/random/entropy_avail

This kernel facility in /proc has been available since 2.3.16 so it should work on any reasonably recent Linux. A full pool should be 4096 (check your poolsize config in /proc/sys/kernel/random/poolsize). On my normal servers, I had values around 3500 but this particular server was 150. Stop ColdFusion (or Apache or LCDS or whatever app is giving you fits) and run the following command before starting CF again:

watch –interval 0.1 cat /proc/sys/kernel/random/entropy_avail

Now start ColdFusion and what you may see is as it gets to MessageBrokerServlet, the available entropy drops to near-zero, climbs back up to around 50-70, then drops to zero and repeats like a stairmaster until it completes and CF can resume at a normal pace.

Make random data non-randomly appear

Now we know roughly what the problem is: there ain’t enough random data. How do we make it so ColdFusion and JRun can start up faster? We need to ensure that there is a constantly available source of entropy so the JVM can seed its secure number generator quickly.

Armed with new search terms for Java’s SecureRandom, I came across a StackOverflow thread which offered a JVM argument to switch from the blocking /dev/random to the less-secure-but-non-blocking /dev/urandom:

-Djava.security.egd=file:/dev/./urandom

I appended that onto the end of java.args in /opt/jrun4/bin/jvm.config and the server started up in 12 seconds! I felt a little bit of hair on my head grow back at that moment.

Solving for Production

At this stage I’ve identified the culprit but I had uneasy feelings about using /dev/urandom in production where evil doers are constantly trying to do evil things to our server, application and users. We don’t want an insecure random number generator.

Following the Ubuntu connection from Stack Overflow, this post on slow Apache starts described the same symptoms and the use of rngd (a random number generator daemon) to populate the entropy pool. Rngd is included in rng-tools or rng-utils depending on your distro. On RHEL 5.5, it was already installed under /sbin.

The trick is to feed rngd data from the kinda-insecure /dev/urandom and let it figure out what is secure enough to pass to /dev/random with a FIPS-140 test. You can run rngd two ways. If you want to populate /dev/random once, right now, run it in the foreground:

/sbin/rngd -r /dev/urandom -o /dev/random -f -t 5

Ctrl-C out of it after 15 seconds and check entropy_avail – you should find it’s up around 4000. Very nice! Now, how about running it as a daemon so you don’t have to ever worry if ColdFusion has enough to start quickly? I added this to my /etc/rc3.d/S99local file so it will automatically start every time the server is started:

/sbin/rngd -r /dev/urandom -o /dev/random -t 5
 

Fire that up, restart ColdFusion, crack a beer and ride off into the sunset. Another ridiculous unexpected behavior solved by yours truly.

Interesting side note: Once upon a time, Intel included hardware RNGs in their chip sets that would be exposed as /dev/hw_random. If you had one of those, you could use it as the parameter for -r. Unfortunately that practice died out in the 800 series chips and are no longer available. You can still buy external, cryptographically secure hardware RNGs that can be used for rngd but the above seems to be “good enough” according to the tubes.

If you want to go nuts, you can use a radio tuned to static as an audio input to provide the source data. Unless your a crypto-nerd, this thread about RNG sources will make your eyes bleed.

Resources

EGD – entropy gathering daemon is a userspace substitute for /dev/random, written in perl. It could be used with the java.security.egd parameter above in lieu of /dev/random.

http://whatan00b.com/slow-apache-starts-on-ubuntu Llinked to from the StackOverflow thread on the Java SecureRandom slowness, explained entropy and how to monitor it.

http://blog.sbf5.com/?p=50 Pointed me in the right direction for using rngd to generate entropy for /dev/random

Increasing entropy pool on RHEL/Fedora without keyboard or mouse Another source to monitoring entropy and using rngd that turned up in Google as I got more specific with my searches.

Wikipedia on Hardware RNGs An overview of ways to source random data

Did you know? /proc/sys/kernel/random/uuid contains a fresh Version 4 UUID.

info Recovering 719 session(s)

Turns out there was a corresponding line during shutdown:

info 719 session(s) persisted

Poking around the Internet, how to disable session persistence is an unanswered question. With some searching (mostly JRun-focused), you can find how to enable it but there is nothing on how to disable what is seemingly default behavior. This had stumped myself and at least two other experienced admins so I went hunting.

The first bit of useful information I picked up from the JRun docs is that session persistence across restarts is possible and the default behavior is to put it into files stored in the WEB-INF/sessions directory. Sure enough, I had about 700 files in there (in my case, in /opt/jrun4/servers/INSTANCE1/cfusion.ear/cfusion.war/WEB-INF). Deleted the contents of that directory so my next restart wouldn’t take so long. Progress!

Next was to investigate the WEB-INF/jrun-web.xml file which controls the session persistence config. The contents (minus comments) are quite short:

<jrun-web-app>
    <enable-jrun-web-services>false</enable-jrun-web-services>
    <session-config>
      <persistence-config>
        <active>false</active>
      </persistence-config>
    </session-config>
</jrun-web-app>

Well, that certainly looks right, but why are the sessions still being persisted? No session replication options were checked in the enterprise manager and there was no JRun or ColdFusion clustering enabled. What gives?

The answer is the added instances were missing the jrun-web.xml and the default behavior is to persist sessions! Copying in jrun-web.xml from the default “cfusion” instance in /opt/jrun4/servers/cfusion/cfusion-ear/cfusion-war/WEB-INF (and j2ee-web.xml, also missing, for good measure) resolved the problem and eliminated the session persistence and recovery with a restart.

Next quest to solve: Why JRun doesn’t pass java.ext.dirs from jvm.config to the underly JRE.

Update, literally 3 minutes after posting: So I’m moving on to my next quest, the above-stated java.ext.dirs conundrum and I type into Google: “jrun 4 java.ext.dirs” and up pops THIS post in spot #7! Google instant MEANS instant!

The question becomes, how do you tell if the connection was secure? For payments or other sensitive data requirements we might want to or need to require SSL. Typically in a ColdFusion application you would check the CGI variable “HTTPS” or “SERVER_PORT_SECURE”:

<cfif NOT cgi.server_port_secure>
  // redirect to secure version of the URL
</cfif>

In the case of the F5 BIG IP, it sets a CGI parameter called “BIGIPSSL” that we can check in ColdFusion, so all is not lost:

<cfif NOT cgi.bigipssl>
  // redirect to secure version of the URL
</cfif>

But there’s a rub (of course!) We also have DNS that points to each individual server for debugging purposes and we might want to access them securely. That means that we’ll be hitting the sites via SSL directly as well as proxied through the load balancer. What happens when we want to check a CGI parameter that doesn’t exist?

<cfif NOT cgi.server_port_secure
       AND cgi.bigipssl NEQ true>
  // redirect to secure version of the URL
</cfif>

Turn out, nothing! CF just returns a blank string when you check a CGI parameter that doesn’t exist so the above code will safely work for all possible scenarios: secure and insecure connections in front of and behind an F5 load balancer.

Bonus hack

If you wanted to only rely on one variable, you could add the following line (assuming mod_env is enabled in your Apache setup) to your HTTPS VirtualHost config:

SetEnv bigipssl true

This will cause any SSL connections that bypass the load balancer to also set the bigipssl value which can be checked in the CGI scope. This technique can be used for any number of helpful host-specific setup values.

In my development environment, this report printed as expected but we received reports that in production, there was a blank page inserted between each printed page. I couldn’t replicate it locally but I did see it on our live servers. Same code and same versions of ColdFusion (8.0.1 with chf3) but different results. It wasn’t until I put the two Acrobat windows on top of each other and flipped between them that I could see the entire page was being scaled. In the case of the production server, it was being scaled larger so that it overran the margins and triggered a second, blank page. Here’s the code:

<cfdocument pagetype="letter"
                  backgroundvisible="yes"
                  format="#attributes.format#"
                  margintop="0.20"
                  marginright="0"
                  marginbottom="0"
                  marginleft="0.25"
                  orientation="portrait">

See in this image how the margin has disappeared when CFDocument scaled the page:

With some trial and error I was able to determine that it was specifically the two fields at the top right of the report, Car Class and Car Number, that were determining whether or not the page was scaled. By increasing the width of the absolutely-positioned <div> tags used to display that data, I forced CFDocument to believe the content was wide enough and prevent scaling. In short, I changed the code like so:

Original:
<div class="data" style="top: 0.31in;
                  left: 6.9in;
                  width: 0.85in;">#vchVehicleNumber#</div>
Fix:
<div class="data" style="top: 0.32in;
                  left: 7.07in;
                  width: 1in;">#vchVehicleNumber#</div>

You can compare how this impacted the rendering in this side-by-side image with the div size made visible with a background color:

Left to right the right margins are captured from: Production server with 1in width and no blank pages, production server with 0.85in width and blank pages, development server with 0.85in width and no blank pages.

No rhyme or reason to this that I’m aware of but another nail in the coffin for CFDocument. The underlying icebrowser library may have been the best thing available when CFMX was released but I agree with Jason Delmore that CFDocument needs an overhaul!

While Batchbook does have the pretty cool web forms which can capture contact data from any ole web form, it doesn’t give you total flexibility with filling in customized data fields. In our case, we wanted to create companies rather than individuals as part of a sales pipeline so we needed to have more control than the web forms currently allow.

Start with a contact form

Here’s the HTML form that we’re using – it still uses the original web form field names so all I’ve done here is changed the form ACTION to point at my CFM instead of Batchbook:

<form method="post" action="https://ourserver.com/form.cfm">
<input type="hidden" name="location[address][country]" value="US" />
<h2>Sign-up Now!</h2>
<table class="form">
<tr><td><label>Company *</label></td></tr>
<tr><td><input type="text" name="company[name]" size="30" /></td></tr>
<tr><td><label>Account Type *</label></td></tr>
<tr><td><select name="supertags[sales first contact][plan]"><option value="">Select a plan - you can change later</option><option value="Plan 1">Plan Uno</option><option value="Plan 2">Plan Dos</option><option value="Plan 3">Plan Tres</option></select></td></tr>
<tr><td><label>First Name *</label></td></tr>
<tr><td><input type="text" name="contact_details[first_name]" size="30" /></td></tr>
<tr><td><label>Last Name *</label></td></tr>
<tr><td><input type="text" name="contact_details[last_name]" size="30" /></td></tr>
<tr><td><label>Email *</label></td></tr>
<tr><td><input type="text" name="location[email]" size="30" /></td></tr>
<tr><td><label>Phone *</label></td></tr>
<tr><td><input type="text" name="location[phone]" size="30" /></td></tr>
<tr><td><label>Organization Address</label></td></tr>
<tr><td><input type="text" name="location[address][address_1]" size="30" /></td></tr>
<tr><td><label>Address 2</label></td></tr>
<tr><td><input type="text" name="location[address][address_2]" size="30" /></td></tr>
<tr><td><label>City, State Zip</label></td></tr>
<tr><td><input type="text" name="location[address][city]" size="15" />, <input type="text" name="location[address][state]" size="4" /> <input type="text" name="location[address][zip_code]" size="10" /></td></tr>
<tr><td><label>Company URL</label></td></tr>
<tr><td><input type="text" name="location[website]" size="40" /></td></tr>
<tr><td><label>Do you have an existing service?  If so, which:</label></td></tr>
<tr><td><input type="text" name="supertags[sales first contact][existing_service]" size="40" /></td></tr>
<tr><td><label>Date of next event:</label></td></tr>
<tr><td><input type="text" name="supertags[sales first contact][date_of_first_event]" size="15" /><br /><small>Format date like mm/dd/yyyy</small></td></tr>
<tr><td><label>Questions/Comments</label></td></tr>
<tr><td><textarea name="supertags[sales first contact][customer_comments]" rows="10" cols="50"></textarea></td></tr>
<tr class="submit"><td><input class="button" type="submit" value="Request Account" /></td></tr>
</table>
</form>

It’s the same contact form you’ve whipped up 100 times before. If you’re using the built in web forms, the field names must match what is above. If I was writing my form handler from scratch I would have selected more normalized names.

Note that we a hidden field at the beginning – not all of the data must be user editable. Of course, I could also just set it in my form handler. The country value is a holdover from the original web form.

Process those fields

Our next step is to process that form submission with ColdFusion and use the Batchbook API to create my contacts and populate my custom data fields:

< !--- credentials --->
<cfset variables.api_key = 'YOUR-SECURITY-KEY' />< !--- get this from "Your Account", right column --->
<cfset variables.root_uri = 'https://[YOUR HOST].batchbook.com/service' />

<cfhttp url="#variables.root_uri#/companies.xml" method="post" username="#variables.api_key#" password="x" charset="UTF-8" timeout="30" throwonerror="no">
	<cfhttpparam name="company[name]" value="#form['company[name]']#" type="formfield" />
	<cfhttpparam name="company[notes]" value="" type="formfield" />
</cfhttp>
< !--- cfdump var="#cfhttp#" --->

<cfif structKeyExists(cfhttp, "responseheader") AND isStruct(cfhttp.responseheader) AND structKeyExists(cfhttp.responseheader, "location")>

	<cfhttp url="#cfhttp.responseheader.location#" method="get" username="#variables.api_key#" password="x" charset="UTF-8" timeout="30" throwonerror="no">
	</cfhttp>
	< !--- cfdump var="#cfhttp#" --->

	<cfset xmlCompany = xmlParse(cfhttp.fileContent) />
	<cfset id = xmlCompany.company.id.xmlText />

	< !--- now add location to company --->
	<cfhttp url="#variables.root_uri#/companies/#id#/locations.xml" method="post" username="#variables.api_key#" password="x" charset="UTF-8" timeout="30" throwonerror="no">
		<cfhttpparam name="location[label]" value="work" type="formfield" />
		<cfhttpparam name="location[email]" value="#form['location[email]']#" type="formfield" />
		<cfhttpparam name="location[website]" value="#form['location[website]']#" type="formfield" />
		<cfhttpparam name="location[phone]" value="#form['location[phone]']#" type="formfield" />
		<cfhttpparam name="location[street_1]" value="#form['location[address][address_1]']#" type="formfield" />
		<cfhttpparam name="location[street_2]" value="#form['location[address][address_2]']#" type="formfield" />
		<cfhttpparam name="location[city]" value="#form['location[address][city]']#" type="formfield" />
		<cfhttpparam name="location[state]" value="#form['location[address][state]']#" type="formfield" />
		<cfhttpparam name="location[postal_code]" value="#form['location[address][zip_code]']#" type="formfield" />
		<cfhttpparam name="location[country]" value="#form['location[address][country]']#" type="formfield" />
	</cfhttp>
	< !--- cfdump var="#cfhttp#" --->

	< !--- set default values for sales super tag and capture user-provided information --->
	<cfset arrSuperTag = arrayNew(1) />
	<cfset arrayAppend(arrSuperTag, "super_tag[existing_service]=#URLEncodedFormat(form['supertags[sales first contact][existing_service]'])#") />
	<cfset arrayAppend(arrSuperTag, "super_tag[date_of_first_event]=#URLEncodedFormat(form['supertags[sales first contact][date_of_first_event]'])#") />
	<cfset arrayAppend(arrSuperTag, "super_tag[customer_comments]=#URLEncodedFormat(form['supertags[sales first contact][customer_comments]'])#") />
	<cfset arrayAppend(arrSuperTag, "super_tag[plan]=#URLEncodedFormat(form['supertags[sales first contact][plan]'])#") />
	<cfset arrayAppend(arrSuperTag, "super_tag[requested_demo]=#URLEncodedFormat(form['supertags[sales first contact][requested_demo]'])#") />
	<cfset arrayAppend(arrSuperTag, "super_tag[active]=true") />
	<cfset arrayAppend(arrSuperTag, "super_tag[paperwork_sent]=false") />
	<cfset arrayAppend(arrSuperTag, "super_tag[agreement_back]=false") />
	<cfset arrayAppend(arrSuperTag, "super_tag[announced_on_facebook]=false") />
	<cfset arrayAppend(arrSuperTag, "super_tag[buddy_check_complete]=false") />	

	<cfhttp url="#variables.root_uri#/companies/#id#/super_tags/sales.xml" method="put" username="#variables.api_key#" password="x" charset="UTF-8" timeout="30" throwonerror="no">
		<cfhttpparam type="header" name="Content-Type" value="application/x-www-form-urlencoded" />
		<cfhttpparam type="body" value="#arrayToList(arrSuperTag, "&")#" />
	</cfhttp>
	< !--- cfdump var="#cfhttp#" --->

	< !--- create person--->
	<cfhttp url="#variables.root_uri#/people.xml" method="post" username="#variables.api_key#" password="x" charset="UTF-8" timeout="30" throwonerror="no">
		<cfhttpparam name="person[first_name]" value="#form['contact_details[first_name]']#" type="formfield" />
		<cfhttpparam name="person[last_name]" value="#form['contact_details[last_name]']#" type="formfield" />
		<cfhttpparam name="person[company]" value="#form['company[name]']#" type="formfield" />
	</cfhttp>
	< !--- cfdump var="#cfhttp#" --->
</cfif>

Some notes about the above:

• What’s my password? Your password is X. Or Y. Or Z. It doesn’t matter – Batchbook only authenticates you on your unique key which is sent as the username. The password can be anything.
• If you’re new to REST APIs, I suggest enabling the CFDUMPs as they will show you how data comes and goes. Plus, you’ll see what the response headers look like (hint, they aren’t all 200 OKs).
• Associating people with companies – there is no official way to do this. Just make sure the “company” value for the person is a string match for the company record and Batchbook will make the magic happen on their end.
• There is basically no error checking or exception handling here – I’ve got my code wrapped up in some try/catch and I fall back to sending an email to us if all else fails. Plan for failure. At some point the API will be down or the Internet will break and you need to have a contingency plan when dealing with remote third parties.

The above code took me a day or two of toying around to get working properly. While the docs are pretty good, my experience is that API implementations never quite match their documentation. Getting super tags to work (key to our sales process) took a lot of fooling around plus some assistance from the very helpful Eric Krause at Batchbook.

Next post will be how we’re integrating the results of this sales pipeline with Email Center Pro to dynamically generate and send out contracts in preparation for our sales cycle this winter.

1. New limited support for autoresponders and OOO messages which return a code “5″
2. Added new temporary, permanent and spam bounce signatures
3. Added new demo that doesn’t require Coldspring to simplify integration for new users

Download it from bouncedetector.riaforge.org today and upgrade!