The API Guys

We Integrate Systems

Automatically change Next Action information on Opportunity records

One of the big disagreements I have with Infusionsoft is the use of opportunity records. Infusionsoft wants salespeople to be heavily engaged with opportunity records, constantly updating them, manually moving them through stages and recording what their next action is going to be and when it should take place. I’m not the most sophisticated salesperson, but I just don’t see the point of having to change the opportunity stage AND set the Next Action Date and the Next Action Notes. That’s three actions just to get a reminder to show up two days from now in My Day reminding me to follow up on a proposal I sent.

Instead, I want to cut it down to just one action. (With Stage Moves, I could even cut it down to none, but one thing at a time.) For this example, when I move the opportunity stage to “Proposal Sent”, I want to automatically set the Next Action Date to two days from now at 8:00 am, and I want to set the Next Action Notes to say “Follow up on proposal.”

In Campaign Builder, I’ll start by adding an Opportunity Stage Moved goal, set the goal to the stage I want to trigger from. Then I’ll add a sequence with two HTTP Post snippets.

The first snippet will use Any Date to set the Next Action Date. We need the contactId and App parameters (with our PDev token) to begin with. We’ll set the date to “now”, the time to 8:00 am, and the adjustment to +2 days. The format needs to be the Infusionsoft standard for date/time fields. The saveTo field name we want is “Opportunity.NextActionDate” (no tildes!).

The second snippet will use Any Text to set the Next Action Note. Again we need the contactId and App parameters (with our PDev token). Our textToSave value will be whatever we want to put in the note, and the saveTo value will be “Opportunity.NextActionNotes”.

Now when I mark an opportunity as “Proposal Sent”, the Next Action Date and Next Action Notes will automatically get set as well.

If you want to super-charge this, you can even automate stage moves with our Any Opportunity to Any Stage plugin!

How to set up an HTTP Post in Infusionsoft

HTTP Posts are a way of passing data from one server to another. In order to make our Pocket Developer plugins work, you will need to send data to our server, so that we can tell Infusionsoft what you want done with it.

In Infusionsoft, setting up an HTTP Post is fairly simple. Just go to Campaign Builder, drag out a new sequence or open an existing sequence, and drag the Send HTTP Post snippet from the Process section in the left sidebar.

https://screencast.com/t/O0xUxeQlMh

To configure your HTTP Post, you will need to add a POST URL and add some name/value pairs, also known as parameters.

The POST URL will be the URL of the server where you want to send the data. It may specify a particular directory or script where the code that will catch the data you are sending and interpret it. Any service that asks you to send data via HTTP Post will provide you with the URL where they want you to send the data. For instance, to send data to Pocket Developer’s AnyText plugin, you will use this URL:

http://pocketdeveloper.net/AnyText/

When you create the HTTP Post in Infusionsoft, the first parameter will be filled in by default, with “contactId” as the name, and the merge field for contact Id as the value of the field. You can have as many name/value pairs as you want. If you hover to the right of a parameter, plus and minus buttons will appear; use the plus button to add a parameter, and minus to delete them. For example, if you also want to send the contact’s first name, you might add a parameter with the name “fname” and the value “~Contact.FirstName~”.

The service you are sending the data to will typically provide the names you should use. For instance, to use PDev plugins, in addition to contact Id you must provide your PDev token, so that we know which Infusionsoft application is making the request. This is done by adding a parameter with the name “App” and the value of your PDev token to every HTTP Post to PDev. Our PDev documentation will tell you what other parameters (name/value pairs) to use with each plugin, as well as telling you which ones are required (must be present for the plugin to function) or optional (can be added for convenience and to unlock special features).

Infusionsoft OAuth Flow

OAuth 2 has recently become the web standard for authenticating APIs for use in custom applications.  As a user you have probably seen it any time you try to install an application that works with Facebook, Github or any number of others.  Infusionsoft has adopted the OAuth 2 standard and is slowly pushing us to use it in lieu of the more simple API key authentication. So what is OAuth 2 and how does it work?  And more importantly, how do you set up an Infusionsoft OAuth API connection?

What is OAuth 2?

OAuth 2 is a standard protocol for authentication which can be set up by a web service in order to provide access to their data.  The protocol essentially defines the following 3 types of players or roles which will interact together.

  1. Resource Owner – The resource owner is essentially going to be the end user who will be the one to authenticate the application. For Infusionsoft, this translates to a User in Infusionsoft.  The authentication will ultimately be done by the User or by someone on behalf of the User.
  2. Client – The client is going to be the application that is set up to connect with Infusionsoft in a more generic sense.  The resource owner will essentially be authenticating the client to be able to talk with their Infusionsoft installation.  The client can also have a server which securely stores the resource owner’s access tokens for continual use of the API without the need for re-authentication.
  3. Resource Server/Authentication Server – The resource server is where the user account information is stored, while the authentication server is where the access details are stored in order to for the client to connect with the resource server.  Essentially, Infusionsoft itelf is the resource server, and the OAuth API is the Authentication Server.  From the developers point of view, these are both the same.

How Does It Work?

The OAuth 2 protocol has standard flow, which follows the procedure below:

Abstract Protocol Flow

  1. Developer registers their application (client) with the resource server.  This is usually done with a client_id and client_secret.  Once the developer sets this up, they will use those details to communicate with the resource server in order to set up an authentication process for the user to follow.
  2. The application first will send the user to an authorization request using its client_id and/or client_secret. 
  3. The user will be asked to login to their resource (Infusionsoft) in order to grant permission for the application to use their resource data.  This only needs to be done once as the application can then store the token for subsequent requests.
  4. When the user grants permission for the application to use their resource, a grant code is sent to a url that the application would have specified when sending in the client_id and/or client_secret.
  5. When the application (via the url from above) is sent a grant code, that code is then used to generate an access_token.  The application does this by making a request to the authentication server with the client_id, client_secret, and grant code.  Assuming that those credentials are valid, the authentication server will then return an access_token that will be used to connect directly with the resource server.
  6. When the application has received the access_token, it will store it in its database (encrypted) for later use.  Usually an access_token will only be valid for a certain period of time and therefore sometimes comes with a refresh_token which can be used to get a new access_token.  The refresh_token should be stored along with the access_token.
  7. The application is now free to connect with the resource server and do whatever is intended. Every call made to the resource server will require the access token.

How do I set up an Infusionsoft OAuth API connection

So now that you understand how OAuth 2 works in general, (simple right?) what is the procedure for setting it up for Infusionsoft?

Essentially an Infusionsoft OAuth 2 connection can be set up in any language, but they have provided a wrapper for use with PHP to simplify the process as well as make xml-rpc calls more simple and readable. You can install the PHP SDK from composer or download it directly from github at https://github.com/infusionsoft/infusionsoft-php.  The link also provides more documentation on how to use the SDK.

Essentially there are 3 steps in Authenticating the application.

  1. Send the user to Infusionsoft to Authorize the application. 
    require_once 'vendor/autoload.php';
$infusionsoft = new \Infusionsoft\Infusionsoft(array( 
    'clientId' => 'XXXXXXXXXXXXXXXXXXXXXXXX', 
    'clientSecret' => 'XXXXXXXXXX', 
    'redirectUri' => 'http://myapplicationurl.com/myapplicationauthorizationscript.php'
)); 
echo 'Click here to authorize;';
  2. Accept the grant back from Infusionsoft after the user has logged in an granted permission. 
    require_once 'vendor/autoload.php';

$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId'     => 'XXXXXXXXXXXXXXXXXXXXXXXX',
    'clientSecret' => 'XXXXXXXXXX'
));

/** 
 * This will send the grant code to Infusionsoft and return an access token
 * expiration, and refresh token that you can store in your database.  It will also
 * set the token for you so that you are ready to make calls to the API.
 */
$infusionsoft->requestAccessToken($_GET['code']);

// you should encrypt this array after you serialize it for security.
$token_array = serialize($infusionsoft->getToken());

// store $token_array somewhere and/or begin making API calls
  3. Get the token from the database and set it for making calls to the API 
    require_once 'vendor/autoload.php';

// Decrypt and unserialize the token object from your database
$token_array = some_method_for_retrieving_and_unserializing_token();

// Set up your Infusionsoft object.
$infusionsoft = new \Infusionsoft\Infusionsoft(array(
    'clientId'     => 'XXXXXXXXXXXXXXXXXXXXXXXX',
    'clientSecret' => 'XXXXXXXXXX'
));

// Set the token
$infusionsoft->setToken($token_array);

// Now you are ready to make calls to the API

     

And that’s it!  Now you are ready to start building an application that connects to Infusionsoft via the API.

Merge Infusionsoft data into Google Doc or PDF

You can merge data from Infusionsoft into a Google Doc — or PDF — with no code at all. This recipe requires an HTTP Post in an Infusionsoft campaign, a Google Form, a Google Spreadsheet, a Google Doc, and the autoCrat add-on for Google Apps.

1. Prepare the Google Doc merge template. Insert tags formatted as a field name inside double carrots, e.g. “Dear <<firstname>>:”. Use a single word for your field name, but it can be whatever you want. (Click here to see an example.)
2. Set up a Google Form with “questions” for all the data you want to merge. In the form settings under the gear icon, deselect any sign in restrictions (so you can submit data via HTTP Post). (Click here to see an example.)
3. On the Google Form under Responses, click the “more” dots and choose “Select response destination” to set a Google Spreadsheet to hold the data.


4. In the Google Spreadsheet, install the add-on autoCrat.
googlemerge_autcratinstall
5. In autoCrat, create a new job to merge the data from the spreadsheet into the Google Doc. In step 9, be sure to select “Yes” for the option “Run on form trigger”. (If you want to create a PDF instead of a Google Doc, select the correct type in step 4.)

(Here comes the most technical part. In order to create the HTTP Post, you need the form’s POST URL and you need the html names of the fields you want to fill out, which is different than the names you gave them. I recommend copying this information to a text file for reference as you will need to paste it into Infusionsoft.)

6. View the Google Form you created (as if you are going to fill it out) in Chrome.
7. Hover over the blank space on the form just above the title and right click on the from and choose Inspect to open the page source code. A few lines up you should see this: form action=" followed by a URL. Copy the URL to a text file.
8. Hover over the first field you will want to fill out and right click to Inspect again. In the source code scroll down a few lines until you see something that looks like this: input type="hidden" name="entry.1462991265" Copy the name (in this case entry.1462991265) to the text file and note what it identifies.
9. Repeat step 8 for each field. Keep track of which entry name belongs to which information.

Ok, hard part done. Now you should have a text file with a URL and a list of html field names and what they stand for.

10. In a campaign in Infusionsoft (at the point where you want the document to be created), create an HTTP Post.
11. Copy the URL from your form into the POST URL field in the HTTP Post.
12. Add a name/value pair with the name “submit” and the value “Submit”.
13. Add name/value pairs for each of the data fields you want to send to the Google Doc. The name will be the entry name you copied in step 8. The value will be the Infusionsoft merge field, e.g. ~Contact.FirstName~.
14. Set your HTTP Post to Ready and publish the campaign.
Screenshot 2016-08-29 17.01.03

That’s it! When the HTTP Post fires, it will send the data from the values into the form fields you designated as names. That data will be saved as a form entry and will be sent to the spreadsheet. AutoCrat will merge the data from the speadsheet into the Google doc and, if you selected it, create a PDF on your Google Drive.

Update Opportunity Records with a Web Form

flashlight_photo-1460804198264-011ca89eaa43We love opportunity records, because a single contact can have more than one, and because you get another 100 custom fields for each one. We like use them for a lot of things that are not the typical manually-handled sales pipeline that Infusionsoft teaches, and we’ve developed some interesting techniques for working with them.

One of our Pocket Developer customers recently asked about how to have assistants use an Infusionsoft web form to update opportunity records. For an added wrinkle, a given contact might have multiple opportunity records active at the same time.

There are two problems with this scenario. First, Infusionsoft web forms can only input data to contact records, not opportunities. Second, since there are multiple opportunities, we need to be able to designate the specific opportunity to add data to. Fortunately both of these problems can be handled with Pocket Developer, with a little finessing. It requires a teeny, tiny bit of html code and an understanding of URL query strings… which I am going to explain thoroughly below, so you’ll be up and running in no time at all.

1) Create a campaign with whatever goal trigger you want to start with.

2) Add a sequence and add two processes to the sequence:
a) Create an Opportunity — set the default options (title, stage, assigned user, etc.) to whatever you wish them to be.
b) An HTTP Post to Email Anyone. Set the “to” parameter to the email of the person you will want to fill out the form (or a field containing that information), and the templateId to the id number of the email template that will be sent to them.

3) Add a web form goal. This web form must have a field for email and a field to temporarily store the opportunity id. The opportunity id storage field can be a custom field, but since it is for temporary storage you may also choose to use a standard field that you don’t typically use. We often use the Assistant Name field for this purpose. The email and opportunity id fields can be hidden if you like, since we are going to automatically populate them with the link. You should of course also have temporary storage fields for any other information you want the user to add.

4) Copy the hosted link for the web form.

5) Go to the email template you entered in step 2a. Insert an html snippet in the body of the email. (This is where the teeny, tiny bit of code comes in.) Paste in the following:

<a href="url">Link Text</a>

This is how a link is created. <a href=”url”> says to add a link that goes to a url (we’ll add the actual url in the next step). The </a> says to stop linking. The “Link Text” in between is the text that will be made clickable by the other two parts. That’s it… all the code you need to know. (If you want to know more about html links, click here.)

6) Replace what is between the quotation marks with the hosted web form link you copied in step 4.

7) In addition to the url, we need to send a couple of pieces of data to pre-fill the form — the email address and the opportunity id. (This is where you find out about query strings. For a more thorough explanation, click here.) In order to separate this information from the url, we’re going to add question mark. Then we’re going to send in pairs of information in the format “name=value” with each pair separated by an ampersand. For example, if we needed to tell it to set the email address to “hello@theapiguys.com” and the assistant name (which we are using to store the opportunity id) to “1234”, we would add the following to the url:

?Email=hello@theapiguys.com&AssistantName=1234

Because of the way the hosted web form is coded, it will know to put the Email value into the Email field and the AssistantName value in the AssistantName field. (Note that this technique will also work if you use the Infusionsoft javascript snippet to embed your web form on your website, though in that case you will have a different url.)

But we don’t always want to send the same information. We want these values to be dynamic and send the email for the relevant contact and the opportunity id of the opportunity we just created. In order to do this, we will use merge fields. Fortunately since we’re using Email Anyone, we can even directly merge in data from opportunity records, like so:

?Email=~Contact.Email~&AssistantName=~Opportunity.Id~

When the email is generated, Infusionsoft will see this html snippet and perform the merges like it does in any other place in the email. It will transform ~Contact.Email~ into the contact’s id number and it will transform ~Opportunity.Id~ into the id number of the most recently updated (which in this case has to be the one we just created).

Note that this method does have a few drawbacks. Because you are using an html snippet for the link, it will not behave like a regular Infusionsoft link. It won’t be tracked, and there’s no way to add actions like a tag based on the link click. It also cannot complete a link click goal. So this is probably NOT a method you want to use for marketing-type emails. But for administrative purposes, this method can be very useful.

Now you’ve got your web form ready and your email template set up. When the administrator gets the email, they will click on the link and be directed to the webform, which will pre-populate with the values you’ve sent in the query string for those field, including the opportunity id. But they’re still inputting data to the contact record. It’s time to make the real magic happen… getting that info to the opportunity record.

8) Add a sequence with an HTTP Post to AnyText to copy the stored data from the contact record to the opportunity record.

Set the textToSave fields to the fields from your contact record where the data you want to copy to the opportunity is stored.

In the saveTo fields you will use reference notation to merge in the opportunity id storage field, thereby designating precisely which opportunity to write to. Reference notation looks like this:

Table(ID).FieldName

or more specifically in this case

Opportunity(~Contact.AssistantName~)._OtherInfo

The Contact.AssistantName field is where the opportunity id is stored, having been sent in by the web form which was pre-filled by the html link you created. The reference notation will go to the opportunity table, look for the entry in that table that matches what it finds in the Contact.AssistantName field, and (since this is a saveTo value) will write the matching textToSave information to the OtherInfo field for that entry.

9) (Optional) If you like to keep your data clean, you can add a short timer (a couple minutes to make sure the http post has completed copying the data) and then add another HTTP Post to AnyText to set the copied contact fields back to blank. That way, you don’t get confused by potentially old date sitting in those fields. We’ve even used this technique to prevent users from accidentally filling out the form too quickly in succession by adding a warning if the AssitstatName field is still occupied. This is especially useful when users might be handling multiple opportunities at once.

Now your system is set up so that you can update opportunity records from a web form.

©2023 The API Guys