Import Leads From WordPress to Insightly with Caldera Forms & Insight.ly API v2.2

Recently I had a client ask to take submissions from a formsite.com form into their Insight.ly account as soon as submitted from their WordPress site.  This was no easy task as formsite uses javascript embedded code to generate an iframe and load the form.  I pulled it off by interfacing both the formsite api and the insightly api on a thank you page redirect from formsite but it was gross code and had a moderate failure rate at importing correctly.

Remove The Middle Man

Don’t let its modern, sexy homepage fool you, Formsite is pretty archaic in methods and form generation.  It’s a sad case a site and tool so large can be so crappy.  I needed to just build a form that shot the info over to insightly while also looking nice and sending an email to the site owner.

I’ve done some work for Caldera and I can honestly say they have the best, easiest to use and easiest to extend form building system for WordPress… bar none.  They also look gorgeous.  The drag and drop interface is beautiful and works flawlessly.  The options and extensions vary from simple needs to extremely complex ones.  What we are going to build here is somewhere in between.

Extending Caldera Forms

First build a form.  The Insightly API has some requirements but they are not documented well.  From trial and error I believe first name, last name and email are the main requirements… maybe phone.  So create a simple form in Caldera with these and whatever else you need then let’s move on.

Add the official Caldera plugin Caldera Forms Run Action to your WordPress installation.  This plugin allows you to to hook into the form data being processed before, during and after the processing.  Before we start writing code, let’s set that up on our form.

Go to the “Processing” tab on the form editing page, add a processor of type “Run Action” and fill in details like this.  You can use a different name for your filter/hook but just remember it when we start coding.

Run Action Processor Settings

We are saying we want to do some stuff with the form data after the user submits but BEFORE it gets processed.  This way if we have any trouble with the insightly api we can let the user know so they can fix their input.

Hooking Into Caldera

To do this, you need to put some code into WordPress.  You can do this in your theme’s functions.php file but I recommend you create a very small plugin.  To create this plugin you will add a folder to your wp-content/plugins directory called caldera-insightly.  Inside that folder you will create a php file named caldera-insightly.php.  That file will look like the below code.  Don’t forget to go to “Plugins” in your admin and activate it.

This code is BARE BONES.  I did not build this out like a big proper plugin but it’s simple in its functions and will work for the basics of interfacing the insightly API v2.2.  I explain the code below.

The add_filter line is where we put in the hook that we registered on the Run Action processor on our caldera form.  The second parameter ‘process_insightly_data’ tells it what function to perform on the data from the form.  Remember this is all happening before Caldera processes the data so if we return anything at all from this function the processing fails and the user gets an error message.

$form_data[‘first_name’] is referencing the “slug” of the form field.  You can see this when building your form in caldera.  Each field input has a slug that is sent as the form data.

Insightly requires the data to be formatted in JSON with very specific keys.  You can see a list of options here.  The FIRST_NAME, LAST_NAME and so on are very straight forward.  The complicated shit happens when you hit the LEAD_SOURCE or want to do CUSTOM_FIELDS.  I’ve had a time and a half working with custom fields and got it to work once, so I just avoid it now if I can.  The lead source requires you to already have lead sources setup in insightly.  You need to get the ID’s of those sources and use them to create your lead source array.

Lead source is not required so you can delete that whole section if you want.

After building our array of data we json_encode it and send it on its merry way.  Don’t forget to grab your API key and replace it in this code.  To get that code once logged into insightly click your profile picture in the top right corner then hit User Settings.  Scroll down on that page and you will see API KEY at the bottom.

I detect for “LEAD_ID” in the return string as this means a new lead was created and assigned an ID.  If it’s not there then we return that an error has occurred.  This could be handled better but I was in a hurry as the client wasn’t paying for a lot of hours.

SVN What?

I was so proud that my plugin got accepted into WordPress.org last night.  Now, I’m so lost on how to actually get it activated there.  But I’m working on it.

I just started using Git and tools associated.  I’ve figured out the repository system for the most part and mine are with BitBucket.  Wordpress requires you to use their repository which they call an SVN.  I guess SVN is a different kind of repository with features that allow better version tracking .. or something like that.  I’m still a bit lost.

So, after consulting with some dev friends I finally got this TortoiseGit system that I followed a few commands I found online and it seems to be doing something.  This little turtle is being thrown from an icon of earth into a folder.  And it’s taking forever.

My bit of reading indicates that when you do your first commit to activate your plugin, WordPress has to look through every single plugin in their system.  Why? I haven’t the foggiest, but hopefully after a few hours this turtle is completely in his folder and my plugin is active.

Publishing My First Plugin

I submitted my plugin WP People Pop a few days ago to the WordPress.org system.  I waited anxiously to get my response and see if it was approved.  Well, this morning I got my answer, no.  No, it has not been approved yet.

I read through the email and turns out you aren’t supposed to include libraries with your plugin that WordPress already provides in its core.  I was using jQuery UI to handle some interface items and I included the whole UI package in my plugin’s directory.

I checked out the list of included libraries and turns out you can’t just include all of jQuery UI but you have to include each component you need, seperately.  I guess this makes sense, why have more code included than necessary?

I resubmitted with changes.  Oh, they also made sure to mention I need to clear the now unused js files out.  Email below:

There are issues with your plugin code. Please read this ENTIRE email, address all listed issues, and reply to this email with your corrected code attached. It is required for you to read and reply to these emails, and failure to do so will result in your plugin being rejected.

## Including jquery files (or calling them remotely)

WordPress includes its own version of jquery and many other similar JS files, which have all been rigorously tested with WP and many of the most common plugins. In order to provide the best compatibility and experience for our users, we ask that you not package your own (especially not an older version) and instead use wp_enqueue_script() to pull in WordPress’s version.

Please review http://codex.wordpress.org/Function_Reference/wp_enqueue_script and update your plugin accordingly. You need to both change your code to use our jquery as well as remove the unused files. Remember! Keeping unused files out of your plugins makes them smaller and less potentially vulnerable! if you have any jquery files included in your plugin that WP core has, just delete them.

Offloading jquery js, css, and other scripts to Google (or jquery.com or anywhere else frankly) is similarly disallowed for the same reasons, but also because you’re introducing an unnecessary dependency on another site.  If the file you’re trying to use isn’t a part of WordPress Core, then you should include it -locally- in your plugin, not remotely.

If your code doesn’t work with the built-in versions of jquery, it’s most likely a no conflict issue. If you can’t guess, we -really- want you to use our JS files, and if you can’t, we need to know why so we can fix things for everyone. If you’re just including it because you want to support old versions of WP, or because you think they may not have jquery, please don’t. If they don’t have the default jquery, a lot more than your plugin will break. And if they’re on older versions of WordPress, they need to upgrade, and we don’t recommend you support anything except the most recent version of WP and one release back.

WordPress already has jquery and jquery UI included. Do not include your own. The CSS is fine, but the JS is not.

—-

Please make sure you’ve addressed ALL issues brought up in this email. When you’ve corrected your code, reply to this email with the updated code attached as a zip, or provide a link to the new code for us to review. If you have questions, concerns, or need clarification, please reply to this email and just ask us.