Signal Integration with Eloqua Guide

Source:

Published:

Keywords: Certain Signal, Eloqua, OAuth2, Basic Credentials, Flow, Retry Queue

Document ID: https://platform-support.certain.com/hc/en-us/articles/10901808925975#split1

Certain Signal: Eloqua Native Integration Guide.

This document is a guide to using Certain Signal to integrate with Eloqua.

Signal also integrates with other products, including Marketo and Salesforce via native integrations and others via Webhooks or Advanced Webhooks.

This product is not included with Certain Platform by default.

If you’re interested in it after reading this document, email help@certain.com including your account name.

Contents

What is Signal? How does it work?

Certain Signal processes data from your events in real-time.

Certain Signal passes processed event data from Certain Platform to your instance of Eloqua.

This real-time integration empowers sales and marketing teams to take intelligent, prompt action on the right event data.

Almost everything is set up at the account level.

Signal processes information from the events in your account.

For event-level information, Signal uses the custom tags attached to data such as Registration Statuses.

Important: Signal processes outbound information.

Signal processes outbound information by processing information from Certain.

Signal sends processed outbound information to Eloqua.

Prerequisites

Data-Flow Considerations

Eloqua Credentials

To set up a Connection in Signal, decide which of the two authentication options to use.

The authentication options are OAuth2 and Basic Credentials.

Setting up a Connection is explained on page 7.

OAuth2

Your Eloqua administrator needs to create an OAuth2 app in Eloqua.

The administrator creates the OAuth2 app by going to Settings > App Cloud Developer > Create New App.

The administrator provides the following details.

Basic Credentials

This option uses an Eloqua user: Username and Password.

The user is likely an integration-only user.

The integration-only user example is (MyOrganization/Integration).

The user could be a regular user.

The user must have access in Eloqua to:

Overview of Setup Steps

Steps

| Step | See Page | |---|---:| | On Certain Platform 1. Add tags in the account | 3 | | 2. Apply those tags | 4 | | 3. Add Event Question for Campaign ID | 5 | | 4. Answer that question in events | 5 | | In Certain Signal 5. Add Connection | 6 | | 6. Configure a Flow | 8 |

Setting up Tags

What Are Tags?

Tags are a way of identifying event-level data using labels set at the account level.

Certain Signal uses tags to identify event-level data.

You can apply tags to generic items in events.

Tags apply especially to custom registration statuses and custom registration properties.

This guide does not cover other uses for tags.

For example, events may have several custom registration statuses in addition to standard ones.

You can apply the same Tags to more than one status.

You can also choose to give each status its own Tag.

When you set up a Flow in Certain Signal to send data to Eloqua when an attendee’s Registration Status changes, the Flow uses tags applicable to those statuses.

The Flow uses tags instead of the statuses themselves.

That setup means the flow can apply to any event in your account.

Setting Tags Up for an Account

1. As an Administrator, go to Account Settings > Management > Tags.

2. Enter a Name and a Label for the tag.

3. Select the Object(s) to which the tag can apply.

4. Click Add.

5. Repeat as required for as many tags as needed.

6. Important: Add enough tags to apply to all of the following that you will use in flows (see page 10):

7. Also add enough tags to apply to all of the following that you will use in filters for flows (see pg 10):

Applying Tags in an Account

Apply tags to relevant information in each event where information should flow through Certain Signal.

The relevant information is Registration Statuses and Registration Custom Properties.

You can also tag Attendee Types and Events.

The tagging of Attendee Types and Events supports filtering registration records by attendee type or event.

Default Registration Statuses apply to all events.

An Administrator applies Default Registration Statuses tags at the account level.

1. Go to Account Settings > Management > Registration Statuses. 2. Select one or more tags for each status.

Important: Even if standard registration statuses are not used, best practice is to set up tags for all of them.

It is essential to tag at least the ‘New’ status.

Certain uses the ‘New’ status “behind the scenes” when first processing each registration.

If standard registration statuses are used, it is essential to tag all of them.

Tagging all standard registration statuses is required so the statuses can be used in Flows configured in Signal (see page 8).

Applying Tags in an Event

Custom Registration Statuses

If any Flow configured in Signal will watch or activate for changes of Registration Status, configure tags for custom registration statuses.

1. In each event, go to Plan > Event Setup > Custom Statuses. 2. Select at least one tag for each status.

Custom Registration Properties

If any Flow configured in Signal will activate for Custom Reg Properties, configure tags for custom registration properties.

1. In each event, go to Plan > Configure. 2. Under Custom Registration Properties, select at least one tag for each custom reg property in the event.

Standard Registration Properties

Standard Registration Properties tags are set up automatically.

Standard Registration Properties tags have names identical to the properties themselves.

Standard Registration Properties are:

These tags only appear in Signal.

In Signal, Flows can activate based on these Standard Registration Properties tags.

There is nothing to edit on Certain Platform for Standard Registration Properties.

Attendee Types (Optional)

Attendee Types are for use with filters (see page 10).

1. In each event, go to Plan > Event Setup > Attendee Types. 2. Select one or more Tags for each attendee type for which registrations may be filtered.

Events (Optional)

Events are for use with filters (see page 10).

1. In each event, include the event in a filter. 2. Go to Plan > Event Setup > Details. 3. Select one or more Tags for the event.

Registration Questions (Optional)

Registration Questions are for use with mapping Certain fields to Eloqua fields (see page 11).

1. In each event where registration questions capture data from attendees. 2. In each event where those answers and/or questions should pass to Eloqua. 3. Go to Plan > Event Setup > Questions. 4. Select just one Tag for each question.

Selecting more than one Tag could result in duplicate data in Eloqua.

Recording an Event’s Campaign Name

If any Flow in Signal includes an action to ‘Trigger Campaign’ or ‘Create/Update Contact’ where the campaign is set per event, set up an event question.

Set up the event question when campaign selection is per event instead of using the same campaign for all events.

Set up the event question to record the Campaign Name for each event.

1. As an Administrator in Certain Platform, go to Account Settings > Management > Event Data. 2. Add an Event Question, such as ‘Eloqua Campaign Name’. 3. In each event, as an Event Planner or Administrator, go to Plan > Event Setup > Custom Event Data. 4. Enter the Eloqua Campaign Name for that event in the custom question field.

Opening Certain Signal

When Signal is activated for an account, the Account Settings > Implementation menu includes an extra option available to Administrators.

The extra option is:

Click Signal Real-Time Data Integration to open Certain Signal in a separate window.

Certain Signal runs separately from Certain Platform.

Note: To return from Signal to Certain Platform at any time, click the link to return from Signal to Certain Platform.

Setting up a Connection

What are Connections?

A Connection in Certain Signal specifies how to connect to an instance of Eloqua.

The target application is Eloqua.

Multiple connections are possible.

Multiple connections include connections to Eloqua and other applications.

Each Flow requires a Connection.

Multiple flows may use the same Connection.

A Connection can be set up before configuring the first Flow.

A Connection can also be set up while configuring a Flow.

This guide assumes setup of the Connection first.

Adding a Connection

As an Administrator, set up one or more Connections for the account.

Set up Connections one time.

Use Connections in the Flows set up (see page 8).

1. Go to Account Settings > Implementation > Signal Real-Time Data Integration. 2. Click Connections in the left navigation panel. 3. Click Add A Connection on the Connection List page that opens. 4. Enter the details in the Connection Setup screen.

The Connection Setup screen details are:

Basic Authentication

Basic Authentication uses an Eloqua username and password.

If Basic Authentication is selected, complete the following two fields:

OAuth2

OAuth2 is the recommended best practice.

OAuth2 is an industry-standard secure method of authentication.

If OAuth2 is selected, enter the following five fields:

Force Update

Force Update is relevant only for ‘Add to List’ actions.

If Force Update is selected, and Eloqua already has a record for the Contact whose data is being sent, Eloqua updates the Contact where Certain details differ.

An example detail that can differ is the phone number.

6. Click Save & Test. 7. If the test succeeds, click Close. 8. If the test fails, check that the values in step 5 are correct.

Setting Up Flows

What is a “Flow”?

A flow is a configuration to manage the flow of data from Certain to Eloqua.

Flows are created from the landing page in Signal.

This guide includes a section called Configuring a Flow.

Several flows may be configured for an account.

Several flows might use the same Connection.

A flow only needs configuration once at the account level.

When a flow is complete, it starts picking up data for each event in that account within about a minute.

The minute delay occurs because Signal runs independently from Certain Platform.

If a flow is edited, a similar slight delay occurs before the change takes effect in the processing of registrations.

The Flow List

As an Administrator in Certain Platform, go to:

Account Settings > Implementation > Signal Real-Time Data Integration.

Certain Signal opens in a separate browser window.

The main screen in Signal is the Flow List.

The Flow List lists all flows.

The Status column shows whether a flow is completely set up.

The Active column shows whether a flow is running.

Use the toggle button to change a flow from Active to Inactive, or vice versa.

Configuring a Flow

Click ADD A FLOW to start setting up a new flow.

The configuration consists of:

‘Live’ or ‘Test’

The Live toggle switch determines whether a Flow is Live or Test.

A Live Flow picks up all live registrations in live events.

A Live Flow ignores test registrations, even in live events.

A Test Flow picks up all test registrations.

Test registrations include all registrations in test events.

Test registrations also include registrations marked as ‘Test’ in live events.

Best Practice: Set a new flow up as Test—and test it—before setting it to Live.

Flow Data Source

Specify the Source of data for the flow.

Optionally apply Filters.

The Source of a Flow is what the Flow watches for in Certain.

The Source also determines when the Flow activates, based on that data.

For example, the Flow can watch for any change to a Registration Status.

The Flow activates when an attendee’s status changes to a status tagged as ‘Registered’.

Available sources

Set a flow to watch for one of the following:

Note: An incomplete Flow can be saved and completed at a later date.

After a Flow becomes complete, the Flow starts picking up data after the usual minute’s delay.

Activate for …

Choose what the flow should activate for by selecting one or more tags in each appropriate object’s dropdown list.

As shown in the screenshot, activate for tags applied to Registration Statuses and/or Registration Properties.

Other activation options depend on the Flow’s watch configuration.

Tags available for selection are the tags set up for that object (see page 3).

For example, tags for Registration Statuses include Registration Status tags.

Registration Status tags apply to:

Flow Filters

Filter the data going into a flow by selecting fields in these three filter types:

The flow includes a registration only if it meets the rule(s) specified in the filter.

Event

Available fields:

Profile

Available fields:

Attendee Type Tags

Available fields:

Note: For custom fields, select only “enumerated” questions.

Enumerated questions are questions with pre-configured answers.

Enumerated question types are:

Flow Destination

Select Eloqua from the integrations set up by Certain for the account.

Eloqua may be the only integration.

Setting up a Destination

1. Give the Destination a name of your choice.

2. Select the Connection to use.

3. Select the action for this connection from available actions:

Your selected action determines other configuration options.

If the action is ‘External Activity’, configure the following two fields:

These field values are automatically populated by Eloqua.

Mappings

The Available Mappings option is available for most actions.

A mapping specifies how each target field in Eloqua matches a source field in Certain.

Select a mapping from the drop-down list.

If no mappings exist, or if a mapping other than existing mappings is needed, click New Mapping.

New Mapping workflow

1. Give the mapping a name of your choice.

2. The left column lists Eloqua fields as “target” fields.

3. Under each target field, a default “source” field in Certain matches that target field.

4. By default, First Name, Last Name, and Email fields are mandatory.

5. Click the x after a source field label to delete that field.

Note: Concatenate multiple source fields for the same target field.

Fixed text can also be typed.

Example: for target field ‘Title’, choose source fields ‘Position’ and ‘Organization’.

Separate the source fields with two spaces and “@”.

6. In the second column, select a transformation option for each field.

The default of no selection means the data is sent to Eloqua unchanged.

Transformation options are:

Select more than one transformation for a field.

Example: change it to Proper Case and trim it.

7. Add Target Fields at the end of the list and select source fields.

To delete a field from the mapping, click DELETE at the end of that row.

If a mapping is selected, two buttons are enabled:

A third button is also enabled:

Use Refresh Target Fields if the target field is not found in an existing mapping.

Technical note: target fields are cached when a connection is tested.

A refresh updates cached mappings.

Certain source fields available

Certain fields you can choose from as sources include:

Campaign ID

Campaign ID is required if the action is ‘Trigger Campaign’ or ‘Create/Update Contact’.

Note: ‘Campaign ID’ in Signal refers to the ‘Campaign Name’ in Eloqua.

Two options exist:

Select Campaign ID Based on Event Question

Use this option if there is a unique campaign for each event.

Use a custom event question to specify the Campaign Name.

Select that question here.

(See page 5.)

Campaign ID

Enter the campaign Name to move all attendees to a single campaign regardless of event.

Note: If both an event question and an account-level Campaign ID are specified, the event question-based campaign takes precedence.

Form

If the selected action is Form Post, complete:

Metrics Dashboard

To see statistics available in Signal, click Metrics in the left navigation panel when looking at flows.

The choices in the new navigation panel for Metrics depend on the flows and their targets.

The first navigation choice is Insights.

Other navigation links work in the same way, including:

Account Insights

Select whether to see Live Flows or Test Flows.

Select the period for which to see data.

Example periods are:

There are three tabs:

Summary tab

The Summary tab is the default tab on the Insights page.

Figures depend on flows and actions.

Some figures allow drilling down.

For example, click Unique Registrations to see registrations processed by any flows in the selected time frame.

When drilling down, filter on records as needed.

For example, filter on an Event Code to see only registrations in that event.

Figures listed are for the whole account.

The whole account includes all events and registrations.

For each figure, click the number to drill down to details.

Metrics listed include:

Troubleshooting tab

The Troubleshooting tab provides troubleshooting information.

The Troubleshooting tab is the second tab on the Insights page.

Example: some registrations are not processed because a Registration Status is not tagged.

The Troubleshooting tab provides an opportunity to rectify tagging.

The rectification supports processing on the next retry.

Numbers shown include:

Activity Feed tab

The Activity Feed tab is the third tab on the Insights page.

The Activity Feed tab lists the registrations processed.

The Activity Feed tab notes success or failure.

The Activity Feed tab includes:

The Activity Feed tab is a rolling history by date.

The Activity Feed tab provides another way to access lower-level data.

The Activity Feed data could be accessed by drilling down in the Summary or Troubleshooting tabs.

The Retry Queue

When an action fails, the action usually joins the “Retry Queue”.

The Retry Queue runs failed actions again in order.

Some failures do not join the queue.

Failures that cannot be resolved, such as missing mandatory fields, are exceptions.

An action can be retried up to three times.

After three retries, the action does not rejoin the queue.

To see the Retry Queue, click Retry in the left navigation panel on the Flows page.

Causes of failure include ones under control as a planner.

Example planner cause: a registration with a status that has not been tagged.

Causes also include technical ones.

Example technical cause: a connection being down.

If the cause can be resolved, such as tagging a registration or setting a flow back to being active, that resolution is needed.

After resolving the cause, the action should succeed when retried.

Some failures do not resolve themselves.

For failures that do not resolve themselves, contact the administrator or ask Certain for help.

The interval between retries depends on the severity of the reason.

More serious reasons trigger a sooner retry.

Filtering the Queue

Filter records in the Retry Queue using three filters:

Submitting to the Queue

When an item in the Retry Queue is clicked, the interface shows full details.

If the knowledge is enough to solve the problem, click Submit to Retry Queue.

Submitting adds the item straight to the front of the queue.

Replaying a Flow

If aspects of a flow change while the flow has been running for some time, replaying the flow might be needed.

Examples of changed aspects include changing filters.

Replay supports running the flow for the same registrations as before.

The replay makes the flow behave as if the changes had been made earlier.

Certain cannot arrange replay directly through the interface.

A user can ask Certain to arrange replay.

A user may specify a date range or even an event.