Custom Audiences


Import contacts on demand

In This Guide

  • Intro to Custom Audiences
  • API Reference
  • Step by Step Example

Custom Audiences Intro


The Custom Audience lets you create a custom campaign/program step, which will import contacts on demand.

The most common use-case is importing & updating contacts:

  • Segment contacts outside Eloqua e.g. a data-warehouse
  • Import/segment contacts from an internal or external system

Creating a Custom Audience 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 50 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.audience

The eloqua.audience function sends an audience back to Eloqua. It does 2 things.

  1. The contacts will be imported/updated into your Eloqua database
  2. The contacts will be added to your campaign or program

Therefore the Custom Audience is useful for both importing and segmenting contacts.


eloqua.each(contact => {
    eloqua.audience([
    { C_EmailAddress: 'test.lead@justaddfeatures.com', C_FirstName: 'Test', C_LastName: 'Lead' },
    { C_EmailAddress: 'test.lead2@justaddfeatures.com', C_FirstName: 'Test' }
]);
});

In the above example, eloqua.audience() is passed two hard-coded contacts.

These contacts will be created if they do not exist in Eloqua, and whatever fields you pass will be updated.

You return an array of contacts. Each contact 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 eloqua.audience() 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).



Examples



Basic Example

This basic example creates/updates one contact, setting their name to 'Bruce Wayne'.

eloqua.audience([   { C_FirstName: "Bruce", C_LastName: "Wayne" }   ]);


API Sample

The below sample demonstrates using a Custom Audience to retrieve an audience from an API.


const fetchJSON = require('node-fetch-json'); // use node-fetch instead if you do not want JSON
fetchJSON("https://example.com") // replace this with your URL, e.g. https://username:password@example.com/api
    .then(data => {
        // you may need to reformat the data here
        eloqua.audience(data);
    });


Real API Example

The below example includes an extra step to map results.

This is a real, working example which queries a sample-data site and fetches contacts.


const fetchJSON = require('node-fetch-json'); // use node-fetch instead if you do not want JSON
fetchJSON("https://jsonplaceholder.typicode.com/users") // replace this with your URL, e.g. https://username:password@example.com/api
    .then(data => {
        data = data.map(data => { return { C_EmailAddress: data.email, C_FirstName: data.name.split(" ")[0], C_LastName: data.name.split(" ")[1], C_City: data.address.city, C_BusPhone: data.phone } })
        eloqua.audience(data);
    });



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