Transcription
Certain Signal: Eloqua Native Integration GuideThis 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 andothers via Webhooks or Advanced Webhooks – see separate guides.)This product is not included with Certain Platform by default, but if you’re interested in it after reading thisdocument, please email [email protected], including your account name.ContentsWhat is Signal? How does it work? . 2Prerequisites . 2 Data-Flow Considerations . 2 Eloqua Credentials . 2Overview of Setup Steps . 3Setting up Tags . 3 What Are Tags? . 3 Setting Tags Up for an Account . 3 Applying Tags in an Account. 4 Applying Tags in an Event . 4Recording an Event’s Campaign Name . 5Opening Certain Signal . 6Setting up a Connection . 6 What are Connections? . 6 Adding a Connection . 6Setting Up Flows . 8 What is a “Flow”? . 8 The Flow List . 8 Configuring a Flow . 8Flow Data Source .10 Available sources . 10 Activate for . 10Flow Filters .10Flow Destination .11 Setting up a Destination . 11 Mappings . 11 Campaign ID . 13 Form . 13Metrics Dashboard .14 Account Insights . 14The Retry Queue.16Replaying a Flow .17 2020 Certain, Inc.Certain Signal for Eloqua Page 1 of 17
What is Signal? How does it work?Certain Signal processes data from your events in real time, passing it from Certain Platform to yourinstance of Eloqua.This real-time integration empowers sales and marketing teams to take intelligent, prompt action on theright event data.Almost everything is set up at the account level. Signal processes information from the events in youraccount. For event-level information this is based on the custom tags you attach to data such as RegistrationStatuses, as explained in this document.Important: Signal processes outbound information, processing information from Certain and sending it toEloqua.PrerequisitesData-Flow Considerations Do you capture data in registration questions that will be synced to Eloqua?o If so, you’ll need to apply tags to those questions: see page 5.Do you have different data mappings based on registration status, or attendee type?o If so, you’ll need to apply tags to those items: see page 4.How many Eloqua campaigns?o One campaign that’s common to all events, or one campaign per event?o If one per event, you’ll need an Event Question for the Campaign ID: see page 5.Eloqua CredentialsFor you to set up a Connection in Signal (see page 6), you need to decide which of the two authenticationoptions you will be using: OAuth2 (our recommendation) or Basic Credentials. (Setting up a Connection isexplained on page 7.) The choice you make determines the information you require in advance. OAuth2Your Eloqua administrator will need to create an OAuth2 app in Eloqua, by going to Settings App CloudDeveloper Create New App.They then need to provide you with the following details: EndpointClient IdClient SecretCallback URL:https:// Certain Platform Domain /svcs/maintegration/oauth2Callback Basic CredentialsThis option uses an Eloqua user login: Username and Password.The user is likely to be one set up for integrations only, such as (MyOrganization/Integration), but could be aregular user. 2020 Certain, Inc.Certain Signal for Eloqua Page 2 of 17
They must have access in Eloqua to: Create ContactsAdd Contacts to a ListExternal ActivitiesOverview of Setup StepsStepSee PageOn Certain Platform1. Add tags in the account2. Apply those tags3. Add Event Question for Campaign ID4. Answer that question in events3455In Certain Signal5. Add Connection6. Configure a Flow68Setting up TagsWhat Are Tags?Tags are a way of identifying event-level data using labels you set at the account level.You can then apply those tags to generic items in events, especially custom registration statuses and customregistration properties for use in Certain Signal. (Tags can be used for other purposes as well, but this guidedoesn’t cover that.)For example, your events may have several custom registration statuses in addition to the standard ones.You can apply the same Tags to more than one status, or you might choose to give each one its own Tag.When you set up a Flow in Certain Signal to send data to Eloqua when an attendee’s Registration Statuschanges, for example, you specify the tags applicable to those statuses, not the statuses themselves. Thatmeans the flow can apply to any event in your account.Setting Tags Up for an Account1.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; for example, ‘Registration Statuses” and/or“Custom Registration Properties”.4.Click Add.5.Repeat as required for as many tags as you need.6.Important: Add enough tags to apply to all of the following that you will use in flows (see page10): 2020 Certain, Inc.Certain Signal for Eloqua Page 3 of 17
7.a.Registration Statusesb.Custom RegistrationPropertiesAlso add enough tags to apply to allof the following that you will use infilters for flows (see page 10):a.Attendee Typesb.EventsApplying Tags in an AccountIn each event from which you want information to flow through Certain Signal, apply tags to the relevantinformation: Registration Statuses and Registration Custom Properties.(You can also tag Attendee Types and Events, so that you can filter registration records by attendee type orevent: see Filters on page 10.)Default Registration StatusesThese apply to all events, so an Administrator applies the tags at the account level.1.2.Go to Account Settings Management Registration Statuses.Select one or more Tags for each status.Important: Even if you don’t use any standard registration statuses, best practice is to set up tags for all ofthem, but it’s essential to tag at least the ‘New’ status (which Certain uses “behind the scenes” when firstprocessing each registration).If you do use standard reg statuses, it’s essential that you tag them all, so that you can use them in the Flowsyou configure in Signal: see page 8.Applying Tags in an EventCustom Registration StatusesIf any of the Flows you configure in Signal will watch or activate for changes of Registration Status (see page10): 2020 Certain, Inc.Certain Signal for Eloqua Page 4 of 17
1.2.In each event, go to Plan Event Setup Custom StatusesSelect at least one tag for each status.Custom Registration PropertiesIf any of the Flows you configure in Signal will activate for Custom Reg Properties (see page 10):1. In each event, go to Plan Configure.2. Under Custom Registration Properties, select at least one tag for each custom reg property in theevent.Standard Registration PropertiesThese tags are set up for you automatically, with names identical to the properties themselves:Complete, Badge Printed, On To Do List, Invoice Generated, and Test.You only see them in Signal, where, just like Custom Reg Properties, you can activate Flows forthem(see page 10). There’s nothing to edit on Certain Platform.Attendee Types(Optional– 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 on which you may wish to filter registrations. (SeeFilters on page 10.)Events(Optional– for use with filters – see page 10.)1. In each event you may wish to include in a filter (for example to ensure that only registrations forthat event are passed to Eloqua):2. Go to Plan Event Setup Details.3.Select one or more Tags for the event.Registration Questions(Optional– for use with mapping Certain fields to Eloqua fields – see page 11.)1.In each event in which you use registration question to capture data from attendees, and wish topass those answers and/or questions to Eloqua:2.Go to Plan Event Setup Questions.3.Select just one Tag for each question. (Selecting more could result in duplicate data in Eloqua.)Recording an Event’s Campaign NameIf any of your Flows in Signal will include an action to ‘Trigger Campaign’ or ‘Create/Update Contact’ (seepage 13) where the campaign is set per e vent rather than using the same campaign for all events, then youneed to set up an event question to record the Campaign Name for each event. 2020 Certain, Inc.Certain Signal for Eloqua Page 5 of 17
1.2.As an Administrator in Certain Platform,go to Account Settings Management Event DataAdd an Event Question, such as ‘Eloqua Campaign Name’In each event:3.4.As an Event Planner or Administrator in Certain Platform,go to Plan Event Setup Custom Event DataEnter the Eloqua Campaign Name for that event in the custom question field.Opening Certain SignalWhen Signal is activated for your account, the Account Settings Implementation menu—available toAdministrators—includes an extra option: Signal Real-Time Data IntegrationClick that link to open Certain Signal in a separate window; it runs separately from Certain Platform.Note: To return from Signal to Certain Platform at any time, clickSetting up a ConnectionWhat are Connections?A Connection in Certain Signal specifies how to connect to your instance of Eloqua – your Targetapplication.You can actually have multiple connections, perhaps to Eloqua and another application. (Other targetapplications are covered in separate guides.)Each Flow (see page 8) requires a Connection. Multiple flows may use the same Connection.You can set up a Connection before configuring your first Flow, but you also have the option to do so whileconfiguring a Flow. This guide assumes you’re setting up the Connection first.Adding a ConnectionAs an Administrator youmay set up one or more Connections for your account. You need only do so once –you can then use them in the Flows you set up (see page 8, below).1. Go to Account Settings Implementation Signal Real-Time Data Integration.2. As noted above, Certain Signal opens in a separate window. 2020 Certain, Inc.Certain Signal for Eloqua Page 6 of 17
3.Click Connections in the left navigation panel.4. Click Add A Connection in the Connection List page that opens.5. Enter the details in the Connection Setup screen that opens. Target: Select Eloqua as the third-party app to connect to.Connection Name: Enter a name of your own choice. This could be just ‘Eloqua’ or ‘EloquaConnection’, for example.Service URL: Enter the beginning of the Eloqua URL to which you are redirected when youlog in to Eloqua: the part starting with “https://” and ending with “eloqua.com”.For example: https://secure.p03.eloqua.comAuthentication Type: Select the authentication type to be used: ‘Basic Authentication’ or‘OAuth2’. Basic Authentication – using an Eloqua username and password.If you select this option, complete the following two fields User Name – An Eloqua user, likely to be one set up for integrations only,such as ‘MyOrganization/Integrationuser”. but could be a regular user.This user must have the minimum permissions described on page 1. Password – The Eloqua password for that user. OAuth2 – our recommended best practice, this is an industry-standard securemethod of authentication.If you select OAuth2 then you also enter the following five fields: Grant Type: Select ‘Authorization Code’Client Id and Client Secret: These two long strings of characters areunique to the OAuth2 app your Eloqua administrator has set up, asexplained under ‘Eloqua Credentials’ on page 2. Access Token URL: Use the default value. Refresh Token URL: Use the default value. Scope: Use the default value if there is one.Test Connection URL: Use the default value. 2020 Certain, Inc.Certain Signal for Eloqua Page 7 of 17
Force Update: Relevant only for ‘Add to List’ actions. If selected, then if Eloqua already hasa record for the Contact whose data is being sent, that Contact will be updated where anydetails in Certain differ — for example, their phone number.6.Click Save & Test.7.If the test is successful, click Close. If it’s not, check that the values in step 5 are all correct.Setting Up FlowsWhat is a “Flow”?A flow is a configuration to manage the flow of data from Certain to Eloqua. You create Flows from thelanding page in Signal: see Configuring a Flow, below. You may configure several flows for an account, whichmight all use the same Connection (explained above).You only need to configure a flow once at the account level. When a flow is complete, it will start picking updata for each event in that account within about a minute.The minute’s delay is because Signal runs independently from Certain Platform. So if you edit a flow then thesame slight delay occurs before that change takes effect in the processing of the registrations.The Flow ListAs an Administrator in Certain Platform. go to Account Settings Implementation Signal Real-Time DataIntegration.As noted above, Certain Signal opens in a separate browser window.The main screen in Signal is the Flow List, which lists all flows.The Status column shows whether a flow is completely set up.The Active column shows whether the flow is running. Click the toggle button to change a flow from Activeto Inactive, or vice versa.Configuring a FlowClick ADD A FLOW to start setting up a new flow – see screenshot overleaf. 2020 Certain, Inc.Certain Signal for Eloqua Page 8 of 17
The configuration consists of: Name‘Live’ or ‘Test‘ status. (See immediately below.)Source: What information the Flow will look for, and what it will activate for in your events.(See page page 10.)Filters: Optional filters to narrow down that information. (See page page 10.)Destination: Where and how that information goes into Eloqua. (See page page 11.)‘Live’ or ‘Test’The Live toggle switch determines whether your Flow is Live or Test:A Live Flow will pick up all live registrations in live events. It will ignore test registrations, even in live events.A Test Flow picks up all test registrations: that’s all registrations in test events, plus any registrationsmarked as ‘Test’ in live events."Best Practice: Set a new flow up as Test—and test it—before setting it to Live. 2020 Certain, Inc.Certain Signal for Eloqua Page 9 of 17
Flow Data SourceNext, specify the Source of data for the flow (optionally applying Filters).The Source of a Flow is what the Flow will watch for in your data in Certain and when it will activate, basedon that data.For example, it might watch for any change to a Registration Status, and activate if an attendee’s status haschanged to a status tagged as ‘Registered’.Available sourcesYou set a flow to watch for any one of the following: Registration Create Update: When a registration is created or updated.Registration Status Change: When a registration’s status changes.Session Registration Status Change: When a registration’s session registration status changes.Event Create Update: When an event is created or updated.Note: You can always save an incomplete Flow and complete it at a later date. As soon as a Flow is complete,it will start 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 listAs shown in the screenshot above, you can activate for tags applied to Registration Statuses and/orRegistration Properties. Other options may be added depending on what the Flow is watching for: If the Flow is watching for Registration Status Change, you must activate for Registration Statuses.If it’s watching for Session Registration Status Change, you must activate for Session RegistrationStatuses.And if it’s watching for Event Create Update, you must activate for Event Statuses.The tags available for selection are those set up for that object; see page 3.For example, the tags for Registration Statuses include Registration Status tags, which you can apply to: standard registration statuses at account level (see page 4)custom registration statuses at event level (see page 4)Flow FiltersYou can filter the data going into a flow by selecting fields in any of these three filter types:Event fields, Profile fields, and Attendee Type tags.The flow will only include a registration if it meets the rule(s) specified in the filter. 2020 Certain, Inc.Certain Signal for Eloqua Page 10 of 17
EventAvailable fields:— standard event fields (e.g., Event Code)— custom event fields— event tagsProfileAvailable fields:— standard profile fields (e.g., Position)— custom profile fieldsAttendee Type TagsAvailable fields:— tags that can be applied to Attendee TypesNote: For custom fields you can only select “enumerated” questions – those that have pre-configuredanswers; that is, questions that are of types Select, Multi-select, Checkbox, or Radio.Flow DestinationSelect Eloqua from the integrations set up by Certain foryour account. (Eloqua may be the only one.)Setting up a Destination1.Give the Destination a name of your choice,2.Select the Connection to use.Note: You can instead click New Connection toadd a connection; the process to set one up is the same as described on page 5.3.Select the action for this connection from those listed as available: Add to List Create/Update Contact External Activity (available only if the Flow is activated for Session Registration Statuses) Form PostYour choice of action determines the other configuration options.If the action is ‘External Activity’, the following two fields are displayed.Select a value in each drop-down list; the values to choose from are automatically populated byEloqua. External Asset TypeExternal Activity TypeMappingsThe Available Mappings option is available for most actions. 2020 Certain, Inc.Certain Signal for Eloqua Page 11 of 17
A mapping specifies how each target field in Eloqua matches a source field in Certain.Select a mapping from the drop-down list.If nobody has set any mappings up yet, or you need something other than one of the existing mappings, clickNew Mapping to add one:1.Give the mapping a name of your choice.Best Practice: For multiple mappings, used for different flows, make the names self-explanatory.For example, ‘Contact Mapping’ and ‘Form Mapping’2.The left column lists Eloqua fields: the “target” fields.Under each one is the default “source” field in Certain matching that target field.For example: target field ‘Company’ defaults to source field ‘Organization’, meaning the value of theOrganization field in Certain will populate the Company field in Eloqua.3. By default, only the First Name, Last Name and Email fields are mandatory. Select the checkboxnext to a target field to make it mandatory. If a required field is missing, there’ll be a validation error when the flow tries to update Eloqua.This is not normally fixable, so would not go into the Retry Queue.4.Click the x after a source field label to delete that field. Clickto add a new one.Note: You can concatenate multiple source fields for the same target field, and even type fixed text.For example, for target field ‘Title’ you could choose source fields ‘Position’ and ‘Organization’,separated by two spaces and “@”:The Certain fields you can choose from as the source of the data going into the target fields inEloqua include: Profile Standard FieldsProfile Custom FieldsRegistration Standard FieldsRegistration Custom Question Tags – one field for the question, and one for its answer(See page 5 about not using the same tag for more than one question.))Registration Standard PropertiesAccount Standard Fields (Account Code)Event Standard Fields (e.g., Event Code and Event Name)Event Custom FieldsFlow Fields (Flow Name)Macros (e.g., Current Date) 2020 Certain, Inc.Certain Signal for Eloqua Page 12 of 17
5.In the second column you can select a transformation option for each field.The default of no selection means the data will be sent to Eloqua unchanged.The options are: lower case Proper Case UPPER CASE Trim (This removes extra spaces.)Note: You can select more than one transformation for a field. For example, you could change it toProper Case and trim it.6.At the end of the list you can Add Target Fields and select source fields for them.To delete a field from the mapping, click DELETE at the end of that row.If you’ve selected a mapping then two other buttons are enabled, with self-explanatory labels: Edit MappingPreview MappingA third button is also enabled: Refresh Target FieldsUse this if you don’t find a target field you were expecting in an existing mapping.Technical note: This is likely for new fields added since a connection was created, since the targetfields are cached when a connection is tested. A refresh updates the cached mappings.Campaign IDThe Campaign ID is required if your action is ‘Trigger Campaign’ or ‘Create/Update Contact’.(Note: ‘Campaign ID’ in Signal refers to the ‘Campaign Name’ in Eloqua)There are two options: Select Campaign ID Based on Event QuestionIf you have a unique campaign for each event, use a custom event question to specify the CampaignName. (See page 5.) Select that question here. Campaign IDTo move all attendees to a single campaign, regardless of event, enter the campaign Name here.Note: If you specify both an event question and an account-level Campaign ID, then the event questionbased campaign will take precedence.FormIf the selected action is Form Post, then complete the following: Select A Form – Select the Eloqua form to which the data will be sent, Form URL – This is populated automatically based on the form selected. 2020 Certain, Inc.Certain Signal for Eloqua Page 13 of 17
Mapping – The target fields are pre-populated based on the form selected. You then select thetarget fields and map them to the source (Certain) fields, as described under Mappings above.Metrics DashboardTo see the statistics available in Signal, click Metrics in the left navigation panelwhen looking at flows.The choices in the new navigation panel you then see for Metrics depend on the flows and their targets.The first one will be Insights, as illustrated and described below.Other links will be, for example, to Leads Created and Form Posts; those each work in the same way asAccount Insights.Account InsightsSelect whether you want to see Live Flows or Test Flows.Select the period for which you want to see the data;for example, for the last 15 minutes, 1 hour or 4hours, or a number of days.There are three tabs: Summary, Troubleshooting, andActivity Feed. Summary tabThis is the default tab on the Insights page, as shownhere. The figures shown depend on the flows andactions. For some of them you can click the number todrill down further – for example, click UniqueRegistrations to see the registrations processed byany flows in your selected time frame.You can filter or search for records when you’vedrilled down. For example, filter on an Event Code tosee only the registrations in that event.The figures listed below are shown. Remember these are for the whole account: all events and registrations.For each of these you can click the number to drill down to details. Changes Processed: The number of registrations processed. Increments each time a registration iscreated or updated in Certain and then processed by a flow in Signal.Note: This will often include the same registration more than once. For example, creating aregistration and then updating it twice would total three “changes”. Unique Registrations: The number of registrations processed, counting any single registration onlyonce. You may find this the most relevant figure on the page. 2020 Certain, Inc.Certain Signal for Eloqua Page 14 of 17
It’s likely to be lower than Changes Processed. For example, if Joe Citizen’s registration wasprocessed three times then Changes Processed will have increased by 3. But since those changeswere all for the same registration the Unique Registrations will have increased by only 1. Actions Triggered: The number of actions triggered by flows. If you only have one flow with oneaction, then this could be the same as Changes Processed. The more flows you have, and the moreactions configured in those flows, the more actions may be triggered. Actions Not Triggered: Only displayed if registrations were processed by flows without actionsbeing triggered. This could be caused, for example, by a registration having an untagged status. Active Flows: The number of flows actually processing registrations during the selected period.This is not related to whether the flow are shown as ”Active” or ‘Inactive” on the Flow List. External Activities: The number of External Activities created in Eloqua by flows. Form Posts: Relevant for Form Post actions – the number of form posts. Leads Created: The number of leads created in Eloqua by flows. Leads Updated: The number of leads updated in Eloqua by flows. Registration Activity in Certain: Overview information. Processing Status: A pie chart comparing the numbers of failures and successes.Drilling down into the failures provides a high-level view for troubleshooting.For example, you can see why an action has failed. If that’s something you can address, then onceyou’ve done so you can expedite the fix in Signal by going back to Flows and clicking Retry in the leftnavigation panel — see Retry Queue on page 16. Troubleshooting tabThe second tab on the Insights page shows information you may find useful for troubleshooting.For example, if some registrations are not processed because a Registration Status isn’t tagged, this givesyou the chance to rectify that so that the registrations can be processed on the next retry.The numbers shown are as follows. Click a number to drill down to see details of the actual records, In Retry Queue: If an action fails, it joins the Retry Queue—see page 16—and will be tried again.(Maximum automatic retries per action 3.)Total Retried: The number of retries. If an action was retried twice, that would have added 2 to thisnumber.Retried Abandoned: The actions that failed three retries. 2020 Certain, Inc.Certain Signal for Eloqua Page 15 of 17
Validation Errors: No retries possible because failed validation. For example, a contact that couldnot be created because a mandatory target field had no value in the source field. (See ‘Mappings’ onpage 11.)Retry Activity: A chart showing retries by time.Retry Processing Category: A chart showing retries by category – “General”, “System”, “Config”,“Connection”, etc.Connection Activity: A chart showing activity per connection over time. Activity Feed tabThe third tab on the Insights page lists the registrations processed, noting success or failure, RegistrationCode, Event, Flow, etc.This is a rolling history, by date.Think of it as another way to access lower-level data you could see by drillingdown in the Summary or Troubleshooting tabs.The Retry QueueWhen an action fails it usually joins the “Retry Queue”, where it takes its turn to run again. (Failures thatcan’t be resolved, such as missing mandatory fields, are exceptions: they don’t join the queue.) An action canbe retried up to three times, after which it 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 your control as a planner, such as aregistration with a status that hasn’t been tagged, and technical ones such as aconnection being down.Where you can resolve the cause of a failure, such as tagging a registration or setting a flow back to beingactive, that’s all you need do. The action should succeed when retried.For other failures that don’t resolve themselves, you probably need to contact your administrator or askCertain for help.The interval between retries depends on the severity of the reason: the more serious the reason the soonerthe retry.Filtering the QueueYou can filter the records shown in the Retry Queue using these three filters:Integration: Probably only one option, ‘Eloqua’, unless you have multiple integrations set up.Status: ‘All Statuses’, ’Retry’, ‘Error’, ‘Failed’, or ‘Done’.Category: ‘All Categories’, ‘General’. ‘System’, ‘Config’, ‘Certain API’, ‘Connection’, etc.Submitting to the QueueWhen you click an item in the Retry Queue, you see its full details. 2020 Certain, Inc.Certain Signal for Eloqua Page 16 of 17
If that knowledge is enough for you to solve the problem, then once you have done so you can click Submitto Retry Queue, which adds the item straight to the
go to Account Settings Management Event Data 2. Add an Event Question, such as ‘Eloqua Campaign Name’ In each event: 3. As an Event Planner or Administrator in Certain Platform, go to Plan Event Setup Custom Event Data 4. Enter the Eloqua Campaign Name for that event
