Authoring code for FlowBoost: Standard vs. Pro

Sanford Whiteman -

Being so close to the innards of the service, and daydreaming about what you can do with Marketo + FlowBoost + JavaScript, I sometimes forget the big user-facing question: Where does my code go?

As you probably know, FlowBoost's “configurator,” if you will, is the Admin » Integration » Webhooks section in the Marketo UI.

Every FlowBoost ’hook uses the same ingredients:

  1. Your FlowBoost-flavored JavaScript code, which goes in the Template box in Webhook Editor.
  2. A couple of copy-and-pasteable Headers for your API key (instructions come with the key).
  3. Appropriate Response Mappings (assuming you're updating lead fields: if you're merely forwarding to an outside service and/or using the Webhook is Called trigger, you don't need any mappings)

In the Marketo UI, when you click New Webhook you're ready to add code right away, since you're looking at the Webhook Editor page (step 1 above). It takes just a couple of clicks to have your code ready to run, but remember to do steps 2 and 3 afterward.

Setting your FlowBoost URL and encodings

Before entering code, let's set your URL and tell Marketo how to encode/decode data:

  • Paste your FlowBoost URL in the URL box. All FlowBoost subscriptions use the same URL structure: https://api.figureone.com/flowboost/v{API version}/run. In the example below, the subscriber is using version 21: https://api.figureone.com/flowboost/v21/run
  • Leave Request Type at POST (the default).
  • Set both Request Token Encoding and Response Type to JSON.

Here's an example:

Very simple!

A note about version numbers

Note that you supply the FlowBoost API version to use. Unless there are critical fixes that absolutely must be backported to older versions, the way a given version works will never change — similar to APIs like the SFDC API — ensuring results are always predictable. You control when to upgrade by bumping the version number, and you can downgrade as necessary.

Two ways to author FlowBoost-flavored JavaScript

The stuff above was probably predictable, but the main thrust of this post is to explain the two different ways to write JavaScript code for the Template box.

We call these options Authoring Environments (AEs): the Standard AE and the Pro AE. Don't worry, though, there's nothing too complex about AEs! These branding terms simply relate to bright-line technical rules:

  • Standard runs your code in global scope. Any variable you declare in your code is automatically part of the response. Standard is the default for both FlowBoost Free and FlowBoost Standard users.
  • Pro nests your code inside an additional, immediately-invoked function. Thus variables at the top-level scope of your code won't automatically appear in your response. Rather, you use return to select what gets sent back as properties of the response object. Pro is the default for FlowBoost Pro users.

More on the Standard AE

The screenshot above shows perfectly working code for the Standard AE, a one-liner:

var leadScore = {{Lead.Lead Score}} * 2;

Since the variable leadScore is global, you'll see this wicked-easy response if the lead's Lead Score in Marketo is currently 2:

{
  "leadScore": 4
}

But starting out in global scope in Standard doesn't mean you can't nest your own functions (and you absolutely should use modular code, even if you're only writing 10-20 lines in total). It just means to keep things easy, you don't have to do anything but declare a var.[1]

Here are two other Standard snippets that will give the exact same response as above:

// declare a function and call it
var leadScore;

function doubleIt(score){
	return score * 2;
}

leadScore = doubleIt({{Lead.Lead Score}});


// JS function hoisting is fun
var leadScore = doubleIt({{Lead.Lead Score}});

function doubleIt(score){
	return score * 2;
}

So again, you can use deeper code structure in Standard AE, including creating your own functions and variables local to those function scopes. But you don't have to.

And on to the Pro AE

The true reason there even are different AEs is highly technical and will have to remain secret for now (I'm too busy to get that far into the FlowBoost “kernel” at present).

But a happy byproduct of having the Pro AE is that it also makes it harder to screw up by unintentionally returning data in the response. Take this Standard snippet:

var leadScore = {{Lead.Lead Score}},
    multiplier = 2,
    newLeadScore = leadScore * multiplier;

That's pretty well-structured code, because it puts the “magic number” 2 in its own variable (so you can change the multiplier) and puts the score token you're operating on its own var as well (so you can change the score token easily). The only minor wrinkle is that this will be your result:

{
  "leadScore": 2,
  "multiplier": 2,
  "newLeadScore": 4
}

Because all three of your vars are in global scope, they all come back in the response. Technically, this isn't a problem (if you don't map any of those properties, they aren't going to touch the Marketo db) but it can start to look cumbersome while you're debugging.

In Pro, you can more tightly control what gets returned, with only one more line of code:

var leadScore = {{Lead.Lead Score}},
    multiplier = 2,
    newLeadScore = leadScore * multiplier;

return newLeadScore;

{
  "response": 4
}

Since your code is effectively wrapped in a function, the local variables stay local. Only what you return (in this case, the number 4) gets returned to Marketo, in the response object. You can also return an object, of course:

var leadScore = {{Lead.Lead Score}},
    multiplier = 2,
    newLeadScore = leadScore * multiplier,
    lastName = {{Lead.Last Name}},
    lastNameYelling = lastName.toUpperCase();

return { 
  leadScore: newLeadScore,
  lastName: lastNameYelling
};

{
  "response": {
    "leadScore": 4
    "lastName" : "WHITEMAN",
  }
}

This allows you to name properties in your response (as is naturally necessary if you're setting multiple field values!).

AEs are mutually exclusive

You'll know when your code doesn't fit the current AE, since you'll get either no result or an error.

Pro-type syntax in the Standard AE will throw an error…

/* 
  code ends with `return`, so it should be in Pro 
*/

var phoneFormatted;

(function(){
	var phoneNumber = FBUtil.phone.parse({{Lead.Phone Number}}, 'US');
	phoneFormatted = FBUtil.phone.format(phoneNumber, FBUtil.PNF.INTERNATIONAL);
})();

return phoneFormatted;

{
  "errorMessage": "ERR: Compile error (strict mode): SyntaxError: Illegal return statement"
}

… because you can't use return from global scope.

Similarly, Standard-type syntax in the Pro AE won't return any results…

/* 
  opposite of the previous example: 
  does not end with `return`, so it belongs in Standard 
*/

var phoneFormatted;

(function(){
	var phoneNumber = FBUtil.phone.parse({{Lead.Phone Number}}, 'US');
	phoneFormatted = FBUtil.phone.format(phoneNumber, FBUtil.PNF.INTERNATIONAL);
})();

{}

… since you haven't returned any.

Switching to the Pro AE for Free or Standard subscriptions

As noted above, the Standard AE is the default for Free and Standard users. You can manually switch to Pro authoring if you want by appending the query param authoringEnv=pro to your webhook URL.

It's also possible for Pro users to ratchet back to Standard using authoringEnv=standard. But don't do this unless you aren't using any Pro features, such as network or database access for that particular 'hook.

Next up: Response Mappings

Response Mappings don't have a lot of flexibility (so less chance of confusion!) but I'll cover a couple of details in my next post.

Notes

[1] Or if you want to be really simple, don’t even include the var. In early versions of FlowBoost we enforced strict mode to force the var, but not anymore. So the simplest way to return a value is now:

aResponseVariable = "a value";