Custom Actions


Easily trigger anything from Eloqua!

In This Guide
  • Intro to Custom Actions
  • API Reference
  • Step by Step Example

Custom Actions Intro


The Custom Action lets you easily create Campaign & Program steps that trigger an action.

This action is completely custom. It can be whatever you need. Some common types of action are:

  • Call an external API
  • Send data to an internal tool
  • Receive data from an internal or external tool

Creating a Custom Action is incredibly simple: place it. Click to open a code-editor. Change a few lines of JavaScript. Then click 'test' to check it works.

It really is that simple. And if you prefer not to do the JavaScript, help is available.



Intro Video


play_circle_outline Play 45 second demo


API Reference


eloqua.log

You can use eloqua.log("Message here...") anywhere in your action.

eloqua.log("Hello World!");

This built-in function logs whatever you pass to it. This message will be visible in 2 places:

  1. When you test your feature, it will display in a blue info box
  2. In the 'Logs' tab after your feature runs in a campaign or program


eloqua.each

Every Custom Action starts with eloqua.each(...).

eloqua.each(contact => {
    // Your code here
});

This function will loop over all the contacts sent by Eloqua.

The contact object properties & functions listed below are available inside this wrapper. The contact object inside this loop will refer to each contact, one at a time.


contact.done

The contact.done function does 2 things.

  1. It lets Eloqua know your function has finished running (for that contact).
  2. Optional: it lets you update that contact in the Eloqua database

eloqua.each(contact => {
    contact.done();
});

In the above example, contact.done() is called without any parameters. This means that no-updates are sent back to Eloqua, so the contacts' data will not be changed.

The above example just loops through every contact and marks your function as complete. This is the simplest possible Custom Action. (It does not actually do anything.)


You can also pass updates back to Eloqua:

eloqua.each(contact => {
    contact.done({ C_FirstName: "Darth", C_LastName: "Vader" });
});

In this example, every contact in the action would have their name updated to 'Darth Vader'

To pass updates, you pass an object into contact.done().

The object needs to have Eloqua's internal fieldname as the key, and the update as the value.

The editor makes this process much easier. In the contact.done() object you can start typing any field - and JustAddFeatures will autocomplete the internal field-names for you!

This autocompletion support is actually smart enough to know all the custom fields in your specific instance, and will highlight an error if you pass the wrong type. (E.g. if you try to pass a string to an Eloqua Number field).


contact.fields

The contact.fields object lets you access the contact's fields from the Eloqua database:

eloqua.each(contact => {
    var name = contact.fields.C_FirstName + ' ' + contact.fields.C_LastName;
    eloqua.log(name); // logs contact's full name
});

Fields must be accessed using their internal field-name.

Again - the editor's autocomplete makes this extremely easy. Just start typing and all the fields in the database (including custom fields) will be available & type-checked.


contact.error

The contact.error function elegantly handles errors:

eloqua.each(contact => {
    contact.error("My custom error message");
});

Specifically, it does 2 things:

  1. It lets Eloqua know your function has errored (for that contact). If you chose a 'route errors' step in your campaign/program, the contact will be sent there.
  2. The error message will be elegantly displayed when you test your function, or in the Log tab.


Examples


Multi-Channel Campaigns

Pre-Made Actions

The following actions are available as pre-made products:

These pre-made actions each have their own dedicated UI and a very high-quality experience. Check the links for more information!


Basic Example

This basic example updates the contact's first-name in Eloqua to be lower-case except for the first letter.

This avoids a situation where your emails say e.g. "Hello SAM" or "Hello sam". It makes sure it's always "Sam".

I'm including this example as it shows how to use contact.done() to send updates and contact.fields to access existing contact values.


eloqua.each(contact => { // loops over all contacts
    let name = contact.fields.C_FirstName; // current contact's first name
    name = name.substr(0,1) + name.substr(1); // fixes the name
    contact.done({ C_FirstName: name }); // returns the update
});


API Example

The below example demonstrates using a Custom Action to retrieve some information.

Specifically - we use an API to retrieve the weather in the contact's current city. This could be used to do some interesting targeting/personalisation -- but mostly it just makes a nice example. This could be any API for any service (including your internal business tools).


let fetchJSON = require('node-fetch-json'); // you can import a selection of npm modules
eloqua.each(contact => {  // loops over each contact
    fetchJSON('http://api.openweathermap.org/data/2.5/weather?q=' + contact.fields.C_City + ',' + contact.fields.C_Country + '&appid=API_KEY_HERE')
        .then(data => {
                contact.done({   C_Weather1: data['weather'][0]['main'] + ' (' + data['weather'][0]['description'] + ')'   }) // Update each contact when the API returns values
            })
        .catch(err => { contact.error(err) })
});



Advanced Topics


Advanced Use-Cases Only

This section covers advanced topics. Most people will never need to use these settings. If you do have an advanced use-case, we recommend our consulting services!

Config Object

In the 'Action' tab if you click on the more icon ('...'), you can select Advanced Settings.

One of these settings is a config object. This is designed for a situation where you want to re-use the same code, but pass different "settings" into it each time.


The entire config object is available as eloqua.config - therefore you can access whatever properties you give it:

eloqua.config.my_setting_name // accesses the config object supplied

Again - the config is unique to each instance of your app, and is designed to allow re-use.



Global Settings Object

You may want to have some values stored outside of your code. E.g. API keys. This can be useful for security (less visible), and also means they can be centrally maintained even if they are used in many functions.

You can set global config through the Just Add Features global settings.

An object with all the global settings is available as eloqua.globals - therefore you can access whatever global properties you setup:

eloqua.globals.my_global_setting // accesses the globals object